Frappecli

核心用法

frappecli 是面向 Frappe Framework 及 ERPNext 的命令行管理工具，通过 REST API 与远端站点交互。主要能力覆盖：

1. 站点管理：列举 Doctype、查看模块、获取元数据
2. 文档 CRUD：支持 list/get/create/update/delete 完整生命周期，支持过滤、分页、字段选择
3. 文件管理：上传（私有/公开）、下载、关联文档的文件列表
4. 报表引擎：直接运行系统报表，支持 JSON/CSV 导出
5. RPC 调用：调用 Frappe 内置或自定义方法，支持参数传递
6. 多站点切换：配置文件管理多个环境（prod/staging），一键切换

显著优点

• 运维友好：无需登录 Web 后台，脚本化批量操作
• 输出灵活：支持 table/json/csv 三种格式，便于与 jq/awk 管道集成
• 安全设计：API Key/Secret 认证，不依赖 Cookie Session
• 跨平台：Homebrew 一键安装，源码安装依赖轻量（uv）

潜在缺点/局限性

• 功能边界：仅限已暴露的 REST API 能力，无法执行服务器本地命令（如 bench 操作）
• 权限依赖：受 Frappe 权限系统严格约束，某些 Doctype 可能不可见
• 网络依赖：纯 API 工具，离线环境无法使用
• 生态成熟度：GitHub 星标较低（~早期项目），长期维护待观察

适合人群

• ERPNext 实施顾问/开发者：快速验证数据、调试 API
• DevOps 工程师：CI/CD 流水线中自动化数据迁移或报表生成
• 系统管理员：批量导入导出、跨站点数据同步

常规风险

| 风险项 | 说明 |

|--------|------|

| 凭据泄露 | `config.yaml` 包含 API Secret，需确保 `~/.config/frappecli/` 权限 600 |

| 误删数据 | `doc delete` 不可逆，生产环境建议先 `--dry-run` 或备份 |

| 传输安全 | 务必使用 HTTPS 站点，避免中间人窃取 Token |

| 权限放大 | API Key 若绑定高权限用户，泄露风险等同账号盗用 |

核心用法

frappecli 是一款面向 Frappe Framework 和 ERPNext 实例的命令行管理工具，通过 REST API 实现对企业资源的程序化操作。

主要功能模块

| 模块 | 典型命令 | 用途 |

|------|---------|------|

| **Site 管理** | `frappecli site doctypes` | 列举 Doctype、查看元数据 |

| **文档 CRUD** | `frappecli doc [list/get/create/update/delete]` | 完整的文档生命周期管理 |

| **文件管理** | `frappecli file [upload/download/list]` | 附件上传下载，支持公私权限 |

| **报表导出** | `frappecli report run --format csv` | 内置报表 JSON/CSV 导出 |

| **RPC 调用** | `frappecli rpc frappe.ping` | 调用自定义 Frappe 方法 |

| **多站点** | `--site staging` | 生产/测试环境切换 |

配置要点

工具通过 ~/.config/frappecli/config.yaml 管理多站点凭证，支持 API Key + Secret 认证，默认站点可一键切换。

---

显著优点

• 企业级 ERP 原生支持：专为 Frappe/ERPNext 设计，覆盖 90% 以上日常管理场景
• 批量操作友好：配合 jq 可实现复杂的数据筛选和批量处理流水线
• 多环境隔离：生产/ staging 凭证分离，避免误操作生产数据
• 输出格式灵活：Table/JSON/CSV 三种格式，便于集成到数据分析流程
• Homebrew 一键安装：brew install pasogott/tap/frappecli 快速部署

---

潜在缺点与局限性

• 外部依赖较重：需单独安装 frappecli Python 包，版本锁定需手动管理
• 凭证本地存储：API 密钥默认存于明文 YAML 文件，需配合文件权限或环境变量加固
• 网络可达性要求：依赖目标 Frappe 实例的 REST API 可用性
• 输入验证边界：JSON filter 和文件路径参数需用户自行确保合法性，工具层转义有限
• 非 T1 来源：由个人开发者 (pasogott) 维护，非企业级背书

---

适合人群

| 角色 | 使用场景 |

|------|---------|

| ERPNext 管理员 | 日常数据维护、用户管理、配置变更 |

| 企业开发者 | 集成测试、数据迁移、自动化脚本 |

| 财务/运营人员 | 报表批量导出、客户数据查询 |

| DevOps 工程师 | 多站点部署、CI/CD 数据同步 |

---

常规风险

| 风险类别 | 说明 | 缓解建议 |

|---------|------|---------|

| **凭证泄露** | API Key 存储于本地文件 | 使用 `chmod 600` 限制权限，或改用环境变量注入 |

| **数据误操作** | `doc delete` 等命令不可逆 | 生产环境操作前先在 staging 验证，启用 Frappe 审计日志 |

| **供应链攻击** | 依赖 frappecli PyPI 包 | 优先 Homebrew 安装，或源码安装时验证 commit hash |

| **传输层中间人** | 自签名证书场景 | 显式配置证书信任，避免 `--insecure` 类选项 |

| **路径遍历** | 文件下载 `-o` 参数 | 验证输出目录合法性，避免 `../../../etc` 类注入 |