frappectl CLI
A Frappe command line for agents: reads ERP documents and reports, runs read-only SQL and keeps profiles with no write rights
- 70 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Writable profiles create, change and delete ERP documents and call site methods, and `query` reads data through the system console
- The API key and secret open access to the accounting and customer data of the site
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/frappectlDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Writable profiles create, change and delete ERP documents and call site methods, and `query` reads data through the system console
- The API key and secret open access to the accounting and customer data of the site
This is third-party code. Review the repository files before installing.
What it does
frappectl is a command-line client for the REST API v2 of Frappe version 16 and newer, built for people and AI agents. It installs as `uv tool install frappectl` or `pip install frappectl` and gives two commands: `frappectl` and the short alias `fr`. Agents are advised to start with `frappectl guide`: one screen covers site selection, core verbs, filtering and a fallback path to the raw API. The commands cover documents (`doc list`, `get`, `create`, `update`, `delete`, `submit`, `cancel`, `amend`), doctypes (`doctype list` and `show` display the schema), reports (`report run`), read-only SQL through System Console (`query`, which needs the System Manager or Administrator role), whitelisted methods (`method search`, `list`, `show`, `call`), file transfer and raw `frappectl api method/<path>` calls. `frappectl assistant` launches a coding agent configured as a Frappe assistant. Authentication has three paths: the `FRAPPE_SITE`, `FRAPPE_API_KEY` and `FRAPPE_API_SECRET` variables, stored profiles with the secret in the OS keyring, or OAuth through the browser. A new profile is read-only by default and refuses unsafe HTTP methods before the request leaves the machine. Terminal output uses tables, and a pipe or the `--json` flag gives clean JSON with logs and errors on stderr.
Who it is for. Frappe and ERPNext administrators and developers who want to work with site documents from the terminal and let an agent read data safely.
Good fit when
- The agent has to fetch overdue invoices with an amount filter and print only name, customer and total as JSON
- Before editing a document you need to view the doctype schema with `frappectl doctype show`
- A production site needs a profile that physically cannot change data
- The Accounts Receivable report should run from a script with the same filters as `doc list`
- A file has to be downloaded or uploaded to a document with the `--private` flag
Not a fit when
- The site runs on Frappe 15 or older: the client targets REST API v2 of version 16 and newer
- You need an interactive confirmation dialog: the CLI itself asks no questions and leaves confirmation to the caller
- The machine has no keyring and no way to set environment variables
- You need an interface for an ERP end user: this tool is for administrators and agents
Example request
Show overdue Sales Invoices above 1000 through frappectl: name, customer and total as JSONLimitations
- Frappe version 16 or newer is required. For OAuth, sites without dynamic client registration need a pre-registered public `--client-id`, while Frappe 15 and newer enable it by default.
- The secret is stored only in the OS keyring with no plaintext fallback: without a keyring use environment variables.
- The CLI itself does not confirm mutations: protection comes from a read-only profile or confirmation on the agent side.
- `query` requires the System Manager or Administrator role, and OAuth needs a terminal and a local browser, so it does not suit headless runs.
How to disable. Lock a profile with `frappectl auth configure <name> --read-only` or remove it and delete the secret from the keyring. The package comes off with `uv tool uninstall frappectl` or `pip uninstall frappectl`, and config lives in `~/.config/frappe/config.json`.
FAQ
How do I install frappectl?
Run `uv tool install frappectl` or `pip install frappectl`. Two commands are installed: `frappectl` and the short `fr`. The repository version comes from `uv tool install git+https://github.com/frappe/frappectl`.
How do I make the connection safe for an agent?
Create a read-only profile: it refuses unsafe HTTP methods before the request leaves your machine. For environment auth set `FRAPPE_READ_ONLY=1`.
What does frappectl guide show?
A one-screen primer for agents: site selection, core verbs, filters and the raw-API path. It needs neither a site nor authentication.
What output format does frappectl use?
Rich tables in a terminal and clean JSON on a pipe or with `--json`. Logs and errors go to stderr, with exit codes 0 success, 1 failure and 2 usage error.
How do I run SQL?
With `frappectl query "select count(*) from tabUser"`: it runs read-only through System Console. The System Manager or Administrator role is required.
Discussion
No questions or reviews yet.
Related
CLI toolsA single Go binary turns a SQL database into a REST API with roles and an MCP server for Claude Code, Cursor and VS Code
Instant REST and MCP over PostgreSQL: the agent reads an existing database through an MCP endpoint with no backend to write
A CLI checking Python service architecture against documented rules, with skills teaching the agent to code within them.
A terminal REST client with YAML collections next to the code and a skill that lets the agent write and run requests itself
The official FastAPI skill, bundled with the package, teaching agents to write code for the installed version
An MCP server and plugin for agents that generate web APIs from OpenAPI, AsyncAPI, GraphQL, gRPC and SQL specs on a Rust core.
README in short
The README opens with command examples and a note for agents about `frappectl guide`. Install, three authentication paths, read-only profiles, output and scripting rules, a command table and notes on launching the assistant follow.