Get connected in 5 minutes

1. Install

Requires Bun ≥ 1.3.0.

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

No npm/yarn needed. Bun installs the binary globally and it runs natively — no Node transpile step.

2. Get your API key from Frappe

Frappe uses token key:secret auth — not Bearer, not Basic.

3. Create a profile

Profiles store your site URL + credentials. You can have multiple (dev, staging, prod).

$ frappe-ctl profile add prod \
    --url https://yoursite.erpnext.com \
    --key <api_key> \
    --secret <api_secret>

$ frappe-ctl profile use prod

Config is saved to ~/.config/frappe-ctl/config.json. You can override it per-command with --site <profile>.

Multiple sites

$ frappe-ctl profile add uat --url http://localhost:8080 --key k --secret s
$ frappe-ctl profile list
  prod   https://yoursite.erpnext.com   (active)
  uat    http://localhost:8080

$ frappe-ctl --site uat next get Customer   # override per-command

4. First 5 commands

Verify your connection and explore before writing anything.

Check the connection

$ frappe-ctl next count Customer
142

If you see a number, you're connected. If you see an auth error, double-check your API key and secret.

List some docs

$ frappe-ctl next get Customer --limit 5
┌─────────────────────────┬──────────────┬──────────────┐
│ name                    │ customer_name│ customer_type│
├─────────────────────────┼──────────────┼──────────────┤
│ CUST-0001               │ Acme Corp    │ Company      │
│ CUST-0002               │ Jane Doe     │ Individual   │
│ ...                                                   │
└─────────────────────────┴──────────────┴──────────────┘

Inspect a DocType's schema

$ frappe-ctl next describe "Sales Order" --required
# Shows only the fields that are required to create a Sales Order
# Much smaller than the full 170-field schema

Search instead of filter

$ frappe-ctl next search Customer "acme"
CUST-0001   Acme Corp   Company

Get a single doc (token-efficient)

$ frappe-ctl next get Customer CUST-0001 --sparse --strip-meta
# --sparse strips null/empty fields (~55% smaller)
# --strip-meta removes Frappe system fields (owner, creation, etc.)

5. Connect your AI assistant

Two ways — skill file for any AI, MCP server for Claude Desktop / Cursor.

Skill file — give any AI instant context

frappe-ctl.skill.md ships with the package. Drop it into your AI and it immediately knows how to use the CLI: token-efficient patterns, verb reference, safety rules, output parsing.

After installing globally, find the skill file at:

$ cat $(npm root -g)/frappe-ctl/frappe-ctl.skill.md

@./node_modules/frappe-ctl/frappe-ctl.skill.md

MCP server — direct tool calls

Exposes frappe-ctl as typed tools so Claude / Cursor can call ERPNext directly without you writing commands. Best for Claude Desktop, Cursor, and VS Code.

Read-only (safe for exploration)

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

Exposes 5 read-only tools: frappe_get, frappe_count, frappe_search, frappe_describe, frappe_validate.

With write access

{
  "mcpServers": {
    "frappe": {
      "command": "frappe-ctl",
      "args": ["mcp", "--allow-mutations"],
      "env": {}
    }
  }
}

Adds frappe_create, frappe_patch, frappe_delete. Delete still requires force: true.

Pin to a specific profile

"args": ["mcp", "--site", "prod"]

Verify it's working

Restart Claude Desktop / Cursor, open a new chat, ask:

How many open Sales Orders are there on my ERPNext site?

If connected, the AI calls frappe_count and returns a live number.

6. Safe read-only mode

Hard-block all mutations for read-only agent sessions or demos.

$ FRAPPE_CTL_READONLY=1 frappe-ctl next get Customer
# All write verbs (create, patch, delete, submit, ...) are blocked at the CLI level
# Even --allow-mutations on the MCP is ignored when this env var is set

Useful when giving an agent access to explore a production site without any write risk. Set it in the MCP env block:

  "env": { "FRAPPE_CTL_READONLY": "1" }

7. Troubleshooting

401 Unauthorized

API key or secret is wrong, or the user doesn't have API access enabled. In Frappe go to User → API Access → Generate Keys. Make sure you copied the secret (not just the key — they're different values).

403 Forbidden

The user has API access but lacks permission for this DocType. Add the DocType to the user's role permissions in Frappe.

command not found: frappe-ctl

Bun's global bin directory is not in your PATH. Add it:

$ echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc

HTTP 417 on filters

Frappe returns 417 when a filter field is not in its allowlist, or the in operator receives an array instead of a comma-separated string. Use "field,in,A,B,C" syntax.

Output is a table but I want JSON

JSON is the default when stdout is not a TTY (i.e., when piped). Force it explicitly:

$ frappe-ctl next get Customer -o json

MCP not appearing in Claude Desktop

Fully quit and restart Claude Desktop (Cmd+Q, not just close the window). Also verify the frappe-ctl binary is in your PATH by running which frappe-ctl in a new terminal.

Still stuck?

Open an issue at github.com/MalharDotTech/frappe-ctl/issues. Include the command you ran and the full error output.