erpnext-cli

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

Installation

pip install git+https://github.com/hatlabs/erpnext-cli.git

Configuration

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.

Usage

JSON mode

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

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

Documents

# 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

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

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

Reports

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

Methods

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

Interactive REPL

erpnext-cli

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

Running as a module

python -m erpnext_cli --json document list Item

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 (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