●v0.2.0 — Phase 2 complete

Talk to ERPNext
like a colleague who knows the system.

A kubectl-style CLI for the entire Frappe ecosystem. One tool for humans and AI agents.

$ bun add -g frappe-ctl

Requires Bun ≥ 1.3 · also works with npm i -g frappe-ctl

Quickstart

From zero to your first ERPNext result in under 2 minutes.

Install

            bun add -g frappe-ctl
            frappe-ctl --version
              0.2.0
          

Add your site profile

Get your API key from Frappe → User Settings → API Access.

            frappe-ctl profile add mysite \
              --url https://mycompany.erpnext.com \
              --key YOUR_API_KEY \
              --secret YOUR_API_SECRET
             
            frappe-ctl profile use mysite
          

Run your first command

            frappe-ctl next get Customer --limit 5 --sparse
             
              NAME              CUSTOMER_NAME       CUSTOMER_TYPE
              CUST-0001         Acme Corp           Company
              CUST-0002         BuildRight Infra     Company
              ...
          

Examples

The grammar is always: frappe-ctl <app> <verb> <DocType> [name] [flags]

// How many open Sales Orders?

          frappe-ctl next count "Sales Order" --filter "status=Open"
            47
        

// Find a project by partial name

          frappe-ctl next search Project "V Builders" --sparse
            [{ "name": "PROJ-0043", "project_name": "V Builders Phase 2", "status": "Open" }]
        

// What fields does Sales Order require?

          frappe-ctl next describe "Sales Order" --required
            FIELDNAME          FIELDTYPE    LABEL
            customer           Link         Customer
            transaction_date   Date         Date
            delivery_date      Date         Delivery Date
            ...
        

// Check payload before creating (no wasted API calls)

          frappe-ctl next validate "Sales Order" \
            --data '{"customer":"Acme Corp"}' \
            --output json
           
            { "valid": false, "missing": ["transaction_date"] }
        

// Follow a link field — Sales Order → its Project, one command

          frappe-ctl next link "Sales Order" SAL-ORD-001 project --sparse
            { "name": "PROJ-0043", "status": "Open", "customer": "Acme Corp" }
        

AI Integration

Two ways to plug frappe-ctl into any AI assistant.

📄

Skill file — any AI

frappe-ctl.skill.md ships in the package. Drop it into your AI and it immediately knows the CLI — token patterns, verb reference, safety rules.

→ Per-platform setup

🔌

MCP server — Claude / Cursor

Start a JSON-RPC stdio server. Claude Desktop and Cursor get typed tools (frappe_get, frappe_count, frappe_validate, …) — no commands to write.

→ MCP config

// Skill file — load once, works everywhere

Platform	How to load	Auto?
Claude Code	Add `@frappe-ctl.skill.md` to your project `CLAUDE.md`	1 line
Cursor	Already in `.cursor/rules/` — opens automatically	✓ auto
OpenAI Codex CLI	`AGENTS.md` at project root — loaded automatically	✓ auto
ChatGPT / Perplexity	Paste `frappe-ctl.skill.md` into custom instructions	paste
Claude Desktop	Add as project knowledge, or use MCP server below	manual

Find the skill file after install: cat $(npm root -g)/frappe-ctl/frappe-ctl.skill.md · Full AI setup guide →

// MCP — Add to claude_desktop_config.json or .cursor/mcp.json

        {
          "mcpServers": {
            "frappe": {
              "command": "frappe-ctl",
              "args": ["mcp", "--site", "production"]
            }
          }
        }
      

Read-only by default (5 tools). Add --allow-mutations for create/patch/delete. · Full setup guide →

Talk to ERPNextlike a colleague who knows the system.