ERPNext and Frappe, efficiently

Why this playbook exists

An ERPNext site is thousands of DocTypes, reports, and pages. Browsing it costs a screenshot per page, and every image is re-sent on every later turn. Reading a DocType JSON in full costs hundreds of lines for a handful of useful fields. The metadata, the database, and bench answer almost every question in a few lines, so start there and open the browser only to confirm a specific screen.

Where things live

Read metadata cheaply

Pick the cheapest source that answers the question.

1. Fields of a DocType from its JSON, without printing the file: python <skill>/scripts/doctype_fields.py path/to/<name>.json prints one line per field (fieldname, type, label, options, flags) plus counts of Links and child Tables. Add --csv to save the table next to the JSON, --type Link,Table to filter.
2. Live site, inside the bench, one compact query with explicit fields and a limit: bench --site <site> execute frappe.get_all --kwargs "{'doctype':'Custom Field','filters':{'dt':'Project'},'fields':['fieldname','fieldtype','options','insert_after'],'limit_page_length':500}" Same shape for Property Setter (doc_type), Client Script (dt), Server Script (reference_doctype), Workflow (document_type), Report (ref_doctype, is_standard).
3. REST, when bench is out of reach: GET /api/resource/<DocType>?fields=["name","modified"]&limit_page_length=20. Meta comes from GET /api/method/frappe.desk.form.load.getdoctype?doctype=<X>; pipe it into the field script with - as the path instead of printing it.
4. SQL only when the query API cannot express it: bench --site <site> mariadb -e "select count(*) from \tabProject`"`.

Inventory a whole system without browsing

Build an inventory from metadata, then read the inventory.

• App level: python <skill>/scripts/app_inventory.py apps/<app> --out inventory/ writes doctypes.csv, reports.csv, pages.csv, workspaces.csv, print_formats.csv and prints the counts. One line per object is enough to plan work or a report.
• Site level: the get_all queries above, one per customization category, saved to CSV.
• Only then decide which screens need a look. Use get_page_text for what a screen shows; screenshot only when the question is visual (layout, colors, alignment).
• Existing pipelines beat new ones: if the project already has an inventory script or export, run it instead of writing another.

Implement

• Never edit erpnext or frappe core. Work in the custom app. For standard DocTypes use Custom Fields and Property Setters exported as fixtures, doc_events in hooks.py, or override_doctype_class.
• Respect stated boundaries. "Use my fields without adding custom fields" means read the DocType JSON first and build with what exists.
• Client side: <name>.js in the app (frappe.ui.form.on) or a Client Script fixture. Server side: controller methods (validate, before_save, on_submit) or @frappe.whitelist() methods; frappe.get_doc, frappe.db.get_value, frappe.get_all; raw frappe.db.sql only when the query API cannot express it.
• Reports: a Script Report is <name>.py with execute(filters) returning (columns, data); a Query Report is SQL stored in the Report doc. Prefer Script Report for anything with logic and Report Builder for plain lists.
• Pages: a Page doctype with <name>.js for desk pages, Workspace for navigation, www/ or a Web Form for the website.
• Permissions: permissions in the DocType JSON for app DocTypes, Custom DocPerm for standard ones. Test with a non-Administrator user.
• New fields in an app DocType go into its JSON with a sensible insert_after, followed by bench --site <site> migrate.

Apply and verify, with filtered output

• After JSON or fixture changes: bench --site <site> migrate 2>&1 | tail -n 20. After JS or CSS: bench build --app <app> 2>&1 | tail -n 5. Then bench --site <site> clear-cache.
• Tests: bench --site <site> run-tests --app <app> --doctype "<DocType>" (or --module). Keep only failures and the summary: 2>&1 | grep -E "FAIL|ERROR|Error|Ran |OK|FAILED" | head -n 40.
• Errors: tail -n 40 logs/*.error.log, or frappe.get_all('Error Log', fields=['method','error'], limit_page_length=5, order_by='creation desc').
• Remote site: run bench over SSH inside the VM or server, with the same filters on every command.

Token rules specific to Frappe

• Never cat a DocType JSON, workspace JSON, or get_meta output. Use the field script or a targeted grep.
• Every get_all and REST call carries explicit fields and a limit.
• Keep field tables in a file and cite only the fieldnames you use in chat.