ffc-reports-api
Skill16 starsChanged 37 days agoMITView on GitHub
Answer questions about Frappe/ERPNext data with ffc without fetching every row - run query reports (General Ledger, Accounts Receivable...), totals and counts per group (ffc aggregate, count-docs --group-by), text search and title-to-name lookup (ffc search), whitelisted server methods (ffc call-method) and raw authenticated requests to any endpoint (ffc api). Use it whenever the user asks "how many", "total per customer", "top 10", "find the invoice for Acme", wants a report, or needs an endpoint ffc has no command for. Read ffc-core first for flags and safety rules.
In this repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- desktop/CLAUDE.mdCLAUDE.md
- ffc-bulk-lifecycleSkill
- ffc-coreSkill
- ffc-dev-clientSkill
- ffc-dev-commandSkill
- ffc-dev-desktopSkill
- ffc-dev-mcp-toolSkill
- ffc-devSkill
- ffc-dev-testingSkill
- ffc-files-collabSkill
- ffc-mcpSkill
- ffc-setupSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Never put count(name) as n in list-docs --fields: Frappe v16 rejects it (exit 6).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Reports, aggregates, search, methods and raw API
Pick the right tool
| Question | Command |
| Total / average / min / max, optionally per group | ffc aggregate |
| Quick count per value of one field (list sidebar) | ffc count-docs --group-by |
| A saved Frappe report | ffc run-report |
| "Which document is Acme?" | ffc search TEXT -d DocType |
| Text across many DocTypes | ffc search TEXT |
| A whitelisted Python method | ffc call-method |
| Any other path (desk methods, v2 API, files, paging) | ffc api |
aggregate (computed by the site)
ffc aggregate -d ToDo --group-by status --json # count per status
ffc aggregate -d "Sales Invoice" --group-by customer --sum grand_total --count --limit 10 --json
ffc aggregate -d "Sales Invoice" --sum grand_total --min posting_date --max posting_date --filters '{"docstatus":1}' --json
ffc aggregate -d "Sales Invoice" --group-by status,currency --sum grand_total --order-by "sum_grand_total desc" --json- Columns:
count,sum_F,avg_F,min_F,max_F. No aggregate flag means--count. No--group-bymeans one row over all matches. --group-bytakes up to 5 fields (repeat or comma-separate);--sum/--avg/--min/--maxrepeat or take CSV.--order-bynames a group field or an aggregate column withasc/desc; default: first aggregate, largest first.--limitdefault 100,0= all; a warning on stderr says when groups were cut.- Fields must be plain fieldnames of the DocType.
customer.territoryoritems.qtyis a usage error (exit 2) before any request. - It works on Frappe v15 and v16 (it picks the syntax from the cached version and retries once with the other). A field above the user's permission level is exit 5.
- Never put
count(name) as ninlist-docs --fields: Frappe v16 rejects it (exit 6).
count-docs --group-by
ffc count-docs -d ToDo --group-by status --json # [{"status":"Open","count":4}, ...]
ffc count-docs -d "Sales Invoice" --group-by assigned_to --filters '{"docstatus":0}' --jsonAt most 50 groups, most frequent first (use aggregate for more). owner puts your own group first. assigned_to is not a field: it counts open and closed (not cancelled) ToDos per System User whose reference_name matches; Frappe does not compare reference_type. An unknown field is exit 6.
Reports
ffc list-reports --module Accounts --json
ffc run-report -n "General Ledger" --filters '{"company":"Acme","from_date":"2026-01-01","to_date":"2026-03-31"}' --timeout 2m --json
ffc run-report -n "Accounts Receivable" --filters @filters.json --limit 100 --keys columns,result --jsonrun-report:-n/--name(required),--filters(JSON object; most reports need some, e.g.company),-l/--limit(rows, table and JSON;0= all),--keys.- Heavy report:
--preparedruns it as a Frappe prepared report on the site'slongqueue worker. It reuses your finished result for the same filters (stderr names it and its finish time;--freshmakes a new one), else your queued job, else starts one, and waits up to--wait(default 5m). A wait that runs out exits 7 with a resume command (--prepared-name NAMEwith the same--filters). Each new job leaves a Prepared Report document (deleted after 30 days). --jsonreturns the full response (columns,result, and Frappe's other keys); trim with--keys columns,result.- Heavy reports outrun the 30 s default: raise
--timeout. list-reports:-m/--module,-l(default 50),--all,--page-size.- Filter names per report are not exposed by ffc. When unsure, read the report's filter definitions on the site or ask the user. (UNVERIFIED: no ffc command lists a query report's filters.)
search
ffc search acme -d Customer --json # [{"value":"CUST-0042","description":...,"label"?}]
ffc search "" -d Item --limit 5 --json # first 5 items
ffc search overdue invoice --json # global search, ranked- With
-d: the Link-field search (search fields, title, link query, user permissions). Use it to turn a title into a document name beforeget-doc. Frappe marks the answer cacheable for 60 s, so a proxy may hide a document created a moment ago. - Without
-d: global search. It covers only DocTypes in Global Search Settings and fields flagged "In Global Search", so no hit proves nothing; fall back tolist-docs --filters '[["field","like","%x%"]]'.a & bsearches each phrase (at most 5) and combines the hits. -l/--limitdefault 20, at least 1. TEXT is positional; several words are joined; put--before a text starting with-.
call-method
ffc call-method --method frappe.client.get_count --args '{"doctype":"ToDo","filters":{"status":"Open"}}'
ffc call-method --method frappe.auth.get_logged_user --get
ffc call-method --method frappe.desk.form.load.getdoctype --args '{"doctype":"ToDo"}' --raw
ffc call-method --method erpnext.some.method --args @args.json --dry-run- POST to
/api/method/<method>(--getfor GET-only methods). Prints themessagevalue as data: JSON even without--json, or the--output/--jqyou ask for.--rawprints the whole response (desk methods answer indocs,docinfo). --dry-runholds back every request, reads included.- A method can do anything the user may do: treat it as a write unless you know it only reads, and confirm first.
ffc api (raw, authenticated)
ffc api /api/method/frappe.desk.form.load.getdoc -f doctype=ToDo -f name=TD-0001
ffc api /api/resource/Currency --paginate -f 'fields=["name","enabled"]'
ffc api POST /api/method/frappe.client.set_value -f doctype=ToDo -f name=TD-0001 -f fieldname=status -f value=Closed --dry-run
ffc api /private/files/contract.pdf --output-file contract.pdf
ffc api DELETE /api/resource/ToDo/TD-0001 --dry-runffc api [METHOD] PATH. PATH is site-relative; full URLs are refused, so credentials never leave the site. HeadersAuthorization,Cookie,Host,X-Frappe-Site-Name,X-Forwarded-Hostare refused.- Defaults to GET even with fields (unlike gh). Name
POST/PUT/DELETEto write; only--input FILEimplies POST. -f key=valuestring field;-F key=valuetyped (true,false,null, number, JSON,@FILE,@-). GET/HEAD send fields as query parameters, other methods as a JSON body.-H "Name: value",-i/--include(status and headers on stderr),--silent,--output-file PATH(binary),--paginate(every page of/api/resource/<DT>or/api/v2/document/<DT>as{"data":[...]}; pass anorder_by),--dry-run(nothing sent).- The body streams to stdout;
--jq/--outputparse a JSON body. A status of 400 or more prints the body and exits with the mapped code. Never retried.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

