# erpnext-cli

**Repository Path**: xiaohan2013/erpnext-cli

## Basic Information

- **Project Name**: erpnext-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# erpnext-cli

Command-line interface to the ERPNext REST/RPC API. Supports one-shot commands, JSON output for scripting, and an interactive REPL.

本仓库附带 13 个 Hermes / OpenCode 技能（覆盖 ERPNext 全部核心模块），可通过 `npx erpnext-cli install-skills` 或 `uvx erpnext-install-skills` 一键安装。

## Installation

### npx（推荐，零配置）

```bash
# 无需安装，直接运行
npx erpnext-cli --json user whoami

# 首次运行会自动检测 Python 3.10+ 并安装依赖
```

工具会在 `.env` 中查找凭据（当前目录或父目录）：

```bash
# 创建 .env 文件
echo ERPNEXT_URL=http://localhost:8080 >> .env
echo ERPNEXT_API_KEY=your-api-key >> .env
echo ERPNEXT_API_SECRET=your-api-secret >> .env
```

### pip

```bash
pip install git+https://gitee.com/xiaohan2013/erpnext-cli.git
```

### uv（本地开发）

```bash
# 从项目目录直接运行
uv run erpnext-cli --json user whoami
```

### pip editable（本地开发）

```bash
pip install -e .
```

## Configuration

```bash
export ERPNEXT_URL="https://your-instance.example.com"
export ERPNEXT_API_KEY="your-api-key"
export ERPNEXT_API_SECRET="your-api-secret"
```

Or pass as CLI flags: `--url`, `--api-key`, `--api-secret`。

工具会自动从当前目录或父目录的 `.env` 文件加载变量（已 `.gitignore`，不会提交）：

```
ERPNEXT_URL=http://localhost:8080
ERPNEXT_API_KEY=your-api-key
ERPNEXT_API_SECRET=your-api-secret
```

优先级：CLI 参数 > 环境变量 > `.env` 文件。

## Usage

### JSON mode

All commands support `--json` for machine-readable output:

```bash
erpnext-cli --json document list Item --limit 5
```

### Documents

```bash
# List documents
erpnext-cli --json document list Item --limit 10
erpnext-cli --json document list "Sales Order" -f '{"status": "To Deliver and Bill"}'

# Get a single document (metadata is automatically stripped)
erpnext-cli --json document get Item ITEM-001
erpnext-cli --json document get Item ITEM-001 --fields '["item_name", "item_group"]'

# Get with raw output (no stripping)
erpnext-cli --json --raw document get Item ITEM-001

# Create / update
erpnext-cli --json document create Item -d '{"item_code": "NEW-001", "item_name": "New Item", "item_group": "Products"}'
erpnext-cli --json document update Item ITEM-001 -d '{"description": "Updated"}'

# Submit / cancel
erpnext-cli --json document submit "Sales Order" SAL-ORD-2024-00001
erpnext-cli --json document cancel "Sales Order" SAL-ORD-2024-00001

# Query child table rows (parent-child join)
erpnext-cli --json document children BOM "BOM Item" \
  --parent-fields '["name", "item"]' \
  --child-fields '["item_code", "qty", "rate"]' \
  --parent-filters '{"is_active": 1}' \
  --limit 20
```

### Schema

```bash
# List all DocTypes
erpnext-cli --json schema doctypes

# Get field definitions
erpnext-cli --json schema fields Item
```

### Reports

```bash
erpnext-cli --json report run "Stock Balance"
erpnext-cli --json report run "Stock Balance" -f '{"warehouse": "Stores - HL"}'
```

### Methods

```bash
# Call a whitelisted Frappe/ERPNext method
erpnext-cli --json method call frappe.client.get_count -a '{"doctype": "Item"}' -m GET
```

### Users

```bash
# Show current authenticated user info
erpnext-cli --json user whoami

# List users
erpnext-cli --json user list --limit 10
erpnext-cli --json user list -f '{"enabled": 1}'

# Get a single user with roles
erpnext-cli --json user get admin@example.com

# Create a new user
erpnext-cli --json user create newuser@company.com \
  --first-name "New" --last-name "User" \
  --roles '["Employee", "Sales User"]'

# Set/reset a user's password
erpnext-cli user set-password user@example.com
erpnext-cli user set-password user@example.com --password "NewP@ss123" --logout-all

# Get roles assigned to a user
erpnext-cli --json user get-roles user@example.com

# Add roles to a user
erpnext-cli --json user add-roles user@example.com --roles '["System Manager"]'

# Remove roles from a user
erpnext-cli --json user remove-roles user@example.com --roles '["Sales User"]'
```

### Organization

Departments are tree-structured via `parent_department`. The `tree` command builds the hierarchy automatically.

```bash
# List departments (excludes disabled by default)
erpnext-cli --json org department list --limit 10

# Filter departments
erpnext-cli --json org department list -f '{"company": "Your Company"}'

# Get a single department
erpnext-cli --json org department get "Engineering"

# Create a department
erpnext-cli --json org department create "研发部"
erpnext-cli --json org department create "前端组" --parent "研发部"
erpnext-cli --json org department create "财务部" --company "Your Company" --is-group

# View department hierarchy tree
erpnext-cli --json org department tree

# List companies
erpnext-cli --json org company list --limit 5

# Get a single company
erpnext-cli --json org company get "Your Company"

# Create a company
erpnext-cli --json org company create "子公司" --abbr "SUB" --country "China" --currency "CNY"
erpnext-cli --json org company create "Manufacturing Co" --abbr "MFC" --domain "Manufacturing"
```

### Selling

```bash
# List customers
erpnext-cli --json selling customer list --limit 10

# Filter customers
erpnext-cli --json selling customer list -f '{"customer_group": "Commercial"}'

# Get customer details
erpnext-cli --json selling customer get "ABC Corp"

# Create a customer
erpnext-cli --json selling customer create "新客户" --group "Commercial" --type "Company"

# List sales orders
erpnext-cli --json selling order list --limit 10
erpnext-cli --json selling order list -f '{"status": "To Deliver and Bill"}'

# Get a sales order
erpnext-cli --json selling order get "SAL-ORD-2024-00001"

# List quotations
erpnext-cli --json selling quotation list --limit 10

# Get a quotation
erpnext-cli --json selling quotation get "QTN-001"
```

### Buying

```bash
# List suppliers
erpnext-cli --json buying supplier list --limit 10

# Filter by supplier group
erpnext-cli --json buying supplier list -f '{"supplier_group": "Distributor"}'

# Get a supplier
erpnext-cli --json buying supplier get "SUP-001"

# Create a supplier
erpnext-cli --json buying supplier create "新供应商" --group "Distributor" --country "China"

# List purchase orders
erpnext-cli --json buying order list --limit 10
erpnext-cli --json buying order list -f '{"status": "To Receive and Bill"}'

# Get a purchase order
erpnext-cli --json buying order get "PUR-ORD-2024-00001"

# List purchase receipts
erpnext-cli --json buying receipt list --limit 5

# Get a purchase receipt
erpnext-cli --json buying receipt get "PR-001"
```

### Stock

```bash
# Get stock balance for an item
erpnext-cli --json stock balance "ITEM-001"

# Filter by warehouse
erpnext-cli --json stock balance "ITEM-001" --warehouse "Stores - HL"

# List warehouses
erpnext-cli --json stock warehouse list --limit 10

# Get a warehouse
erpnext-cli --json stock warehouse get "Stores - HL"

# Show warehouse hierarchy
erpnext-cli --json stock warehouse tree

# List stock entries
erpnext-cli --json stock entry list --limit 10
erpnext-cli --json stock entry list -f '{"stock_entry_type": "Material Receipt"}'

# Get a stock entry
erpnext-cli --json stock entry get "SE-001"
```

### Manufacturing

```bash
# List active BOMs
erpnext-cli --json manufacturing bom list --limit 10

# Get a BOM with items
erpnext-cli --json manufacturing bom get "BOM-001"

# List work orders
erpnext-cli --json manufacturing work-order list --limit 10
erpnext-cli --json manufacturing work-order list -f '{"status": "Not Started"}'

# Get a work order
erpnext-cli --json manufacturing work-order get "WO-001"
```

### Accounting

```bash
# List chart of accounts
erpnext-cli --json accounting account list --limit 20

# Get an account
erpnext-cli --json accounting account get "1000 - Assets"

# Show account hierarchy tree
erpnext-cli --json accounting account tree

# List journal entries
erpnext-cli --json accounting journal list --limit 10

# Get a journal entry
erpnext-cli --json accounting journal get "JV-001"

# List payment entries
erpnext-cli --json accounting payment list --limit 10

# Get a payment entry
erpnext-cli --json accounting payment get "PE-001"
```

### Quality

```bash
# List quality inspections
erpnext-cli --json quality inspection list --limit 10

# Filter by type
erpnext-cli --json quality inspection list -f '{"inspection_type": "Incoming"}'

# Get a quality inspection
erpnext-cli --json quality inspection get "QI-001"
```

### Subcontracting

```bash
# List subcontracting orders
erpnext-cli --json subcontracting order list --limit 10

# Get a subcontracting order
erpnext-cli --json subcontracting order get "SCO-001"
```

### Assets

```bash
# List assets
erpnext-cli --json asset asset list --limit 10
erpnext-cli --json asset asset list -f '{"status": "In Service"}'

# Get an asset
erpnext-cli --json asset asset get "ASSET-001"

# List asset categories
erpnext-cli --json asset category list

# Get an asset category
erpnext-cli --json asset category get "Electronics"
```

### Projects

```bash
# List projects
erpnext-cli --json project project list --limit 10

# Get a project
erpnext-cli --json project project get "PROJ-001"

# List tasks
erpnext-cli --json project task list --limit 10
erpnext-cli --json project task list -f '{"status": "Open"}'

# Get a task
erpnext-cli --json project task get "TASK-001"

# Show task hierarchy tree
erpnext-cli --json project task tree

# Show tasks for a specific project
erpnext-cli --json project task tree --project "PROJ-001"
```

### CRM

```bash
# List leads
erpnext-cli --json crm lead list --limit 10
erpnext-cli --json crm lead list -f '{"status": "Open"}'

# Get a lead
erpnext-cli --json crm lead get "LEAD-001"

# Create a lead
erpnext-cli --json crm lead create "张三" --company "ABC Corp" --source "Website"

# List opportunities
erpnext-cli --json crm opportunity list --limit 10
erpnext-cli --json crm opportunity list -f '{"status": "Open"}'

# Get an opportunity
erpnext-cli --json crm opportunity get "OPP-001"

# List contacts
erpnext-cli --json crm contact list --limit 10

# Get a contact
erpnext-cli --json crm contact get "CON-001"

# List addresses
erpnext-cli --json crm address list --limit 10
erpnext-cli --json crm address list -f '{"country": "China"}'

# Get an address
erpnext-cli --json crm address get "ADDR-001"
```

### Interactive REPL

```bash
erpnext-cli
```

Launches an interactive session with command history, auto-suggest, and colored output. Type `help` for available commands.

### Running as a module

```bash
python -m erpnext_cli --json document list Item
```

## Install Skills（Hermes / npx skills）

本仓库附带 13 个 Hermes 技能，涵盖 ERPNext 全部核心模块。可通过 `erpnext-cli install-skills` 或 `erpnext-install-skills` 一键安装到 `.hermes_home/skills/`：

### uvx（推荐）

```bash
# 安装到当前目录的 skills/ 下
uvx --from https://gitee.com/xiaohan2013/erpnext-cli erpnext-install-skills

# 安装到指定目录（比如 Hermes skills 目录）
uvx --from https://gitee.com/xiaohan2013/erpnext-cli erpnext-install-skills \
  --target-dir ~/.hermes_home/skills

# 强制覆盖已安装的技能
uvx --from https://gitee.com/xiaohan2013/erpnext-cli erpnext-install-skills \
  --target-dir . --clean

# 只安装指定 skill（可重复）
uvx --from https://gitee.com/xiaohan2013/erpnext-cli erpnext-install-skills \
  --skill erpnext-base --skill erpnext-user

# 使用自定义仓库
uvx --from https://gitee.com/xiaohan2013/erpnext-cli erpnext-install-skills \
  --repo-url https://gitee.com/xiaohan2013/erpnext-cli
```

### npx

```bash
# 安装到当前目录
npx erpnext-cli install-skills

# 安装到指定目录
npx erpnext-cli install-skills --target-dir ~/.hermes_home/skills

# 只安装指定 skill
npx erpnext-cli install-skills --skill erpnext-base --skill erpnext-selling
```

### uv run（本地开发）

```bash
uv run erpnext-install-skills --target-dir ~/.hermes_home/skills
uv run erpnext-cli install-skills --target-dir .
uv run erpnext-cli install-skills --skill erpnext-crm --skill erpnext-org
```

### 可用技能

| 技能 | 模块 |
|------|------|
| `erpnext-base` | DocType 元数据、文档 CRUD、报表、文件操作 |
| `erpnext-user` | 用户账号与角色管理 |
| `erpnext-org` | 组织架构（部门/公司树） |
| `erpnext-selling` | 客户、销售订单、报价单 |
| `erpnext-buying` | 供应商、采购订单、收货单 |
| `erpnext-stock` | 库存余额、仓库、库存分录 |
| `erpnext-manufacturing` | BOM、工单 |
| `erpnext-accounting` | 科目、分录、付款 |
| `erpnext-crm` | 线索、商机、联系人、地址 |
| `erpnext-quality` | 质检单 |
| `erpnext-subcontracting` | 委外加工单 |
| `erpnext-assets` | 资产与资产类别 |
| `erpnext-projects` | 项目、任务（树形） |

## Response stripping

By default, `document get` strips ERPNext system metadata (`owner`, `modified_by`, `creation`, `modified`, `idx`, `doctype`, `_*` fields) and null/empty values to reduce output size. Fields `name`, `docstatus`, and `status` are always preserved. Use `--raw` to disable stripping.

## Authentication

Uses ERPNext token authentication (`Authorization: token {key}:{secret}`). Generate API credentials in ERPNext under Settings > Users > API Access.

## Acknowledgements

This project was initially generated by [CLI-Anything](https://github.com/HKUDS/CLI-Anything) (MIT), a tool that auto-generates structured CLI harnesses from software APIs. The generated scaffolding, REPL interface, and test suite provided the foundation for this tool.

## License

[MIT](LICENSE)