| name | cwcli |
| description | Manage local Frappe/ERPNext Docker instances through the cwcli CLI - list instances, start/stop/restart them, check per-process health, back up and unlock sites, manage bench apps, and search cached apps and sites. Use whenever a task touches a local Frappe or ERPNext development instance, bench, or site: checking whether an instance is running, starting or restarting one, backing up or restoring a site, installing or updating bench apps, or finding which bench holds an app or site. |
| user-invocable | false |
| author | Christopher McKay |
cwcli
Manage Frappe and ERPNext Docker instances - structured and non-interactive.
cwcli manages Frappe/ERPNext Docker instances for local development: instance lifecycle, bench and site operations, and backup/restore.
Use the cwcli axi surface, not the bare human commands.
It is the agent-facing half of the same tool: every verb prints one TOON document on stdout, never prompts, and takes every decision as a flag.
You do not need cwcli installed globally - invoke it with uvx --from caffeinated-whale-cli cwcli axi ....
If cwcli output suggests a follow-up command starting with cwcli, run it as uvx --from caffeinated-whale-cli cwcli ... instead.
cwcli needs a running Docker daemon.
If a command reports error: Could not connect to Docker, ask the user to start Docker rather than retrying.
When to use
Use cwcli whenever a task touches a local Frappe or ERPNext instance: checking what instances exist and whether they are running, starting/stopping/restarting one, reading per-process health, backing up or unlocking a site, listing or updating a bench's apps, or finding which bench holds a given app or site.
Workflow
- Run
uvx --from caffeinated-whale-cli cwcli axi with no arguments for the home view: the live instance list plus suggested next commands.
Start here - it answers "what exists and is it up?" in one call.
- Drill in with the verb you need:
status <project>, benches <project>, apps list <project>, backup <project> --site <site>.
- A project with several benches needs
--bench <index|label>.
When a verb reports multiple benches; pass --bench, run axi benches <project> - it is the verb that answers every other verb's --bench, and it lists the valid values.
- Every response ends with
help: hints. Follow them.
Reading the output
Every verb prints one TOON document on stdout:
instances[2]{projectName,status,ports}:
my-erp,running,8000 8001
old-proj,exited,N/A
Errors are structured on stdout too, with an actionable help: line:
error: multiple benches; pass --bench <index|label>
options[2]:
[0] /workspace/development/frappe-bench
[1] /workspace/development/staging-bench
help: re-run with --bench <index|label>
Exit codes: 0 success (a completed operation, including one with warnings, and a successful read that reports bad news), 1 error, 2 usage error - a flag is missing or wrong, and the help: line names the fix.
Verbs
ls List all Frappe/ERPNext instances; emit them as TOON.
where Search cached instances for apps/sites matching a string; emit matches as TOON.
backup Back up a site's database (and optionally files); emit the outcome as TOON.
unlock Remove a site's locks folder; emit the outcome as TOON.
stop Stop a project's containers; emit the outcome as TOON.
start Start a project's containers + bench; emit the outcome as TOON (never prompts).
status Report a project's per-process health; emit the report as TOON (`overall` first).
logs Read a bounded tail of a bench's per-process logs; emit them as ONE TOON document.
restart Restart ONE supervised process; emit the outcome as TOON (never prompts, no --watch).
inspect Inspect a project's benches, sites, and apps; emit the report as TOON.
benches List a project's benches with their indices and labels; emit them as TOON.
label Set or clear a bench's durable user label; emit the outcome as TOON.
migrate Run 'bench migrate' against ONE site under maintenance mode; emit the report as TOON.
run-tests Run 'bench run-tests' for ONE app against ONE named site; emit the report as TOON.
config Report the effective cwcli configuration; emit it as one TOON document. READ-ONLY.
init Provision a new instance, bench, and site; emit the report as TOON (never prompts).
self-update Report whether a newer cwcli is available; emit the check as TOON. READ-ONLY.
setup Install the SessionStart hook into every detected agent harness; emit TOON.
apps list List a bench's available apps, and (with --installed/--site) installed per site.
apps update Update app(s) and migrate affected sites; emit the report as TOON.
apps checkout Fetch and check out a ref into an app already in the bench; emit the report as TOON.
Run uvx --from caffeinated-whale-cli cwcli axi <verb> --help for a verb's flags.
Rules
- Never prompts. A missing decision is a usage error naming the flag, never a hang. If a verb seems to want input, pass the flag its
help: line names.
- Read verbs exit 0 even when the news is bad.
axi status on a fully stopped project, and axi self-update --check on an outdated install, both succeeded - the answer is in the document, not the exit code.
axi output is always TOON, never JSON. JSON lives on the human commands' --json flag. Do not pass --json to an axi verb.- Destructive verbs are deliberately absent. There is no
axi apps install or axi apps uninstall (uninstalling an app drops its tables), and no axi restore or axi rm. Ask the user to run the human command; do not work around this.
Ambient context (optional)
uvx --from caffeinated-whale-cli cwcli axi setup installs a SessionStart hook into Claude Code, Codex, and OpenCode, so the home view lands in every session's opening context automatically.
It is the same information this skill describes, plus live state.
The user only needs one of the two.
