CLI and MCP reference

Every command and tool, one line each, and what the exit codes mean.

The Respira Code commands talk straight to the add-on on your site with the stored site key. They need no respira.press login, and the global --mode flag, which defaults to cloud for page and post commands, does not change them. Every command takes --site <name or URL>, which defaults to the only connected site, and --json. With --json, or when stdout is not a terminal, a command prints one object. --output table gives the readable form.

Commands are written short, as respira app deploy. If the respira CLI is not installed, run each one as npx -y @respira/cli app deploy. After npm install -g @respira/cli the short form works as written.

{ "ok": true, "data": { ... }, "meta": { ... } }
{ "ok": false, "error": { "code", "message", "hint", "retry_ok", "cause" } }

respira app

  • app init <slug> [--dir] [--name] [--force]: scaffold an app.
  • app lint [dir] [--no-local] [--site] [--server]: run php -l, PHPStan, WordPress-Extra, tsc, the esbuild compile and, with the site, the upload lint.
  • app test [dir]: run tests/*.php and the page contracts in a canary request and promote nothing. Needs "tests": true in app.json.
  • app deploy [dir] [--checks auto|server|client]: compile, upload, canary, promote and verify.
  • app deploy --canary-only: the canary runs and additive migrations apply, but nothing goes live. The MCP deploy tool takes promote: false for the same.
  • app dev [dir] [--once] [--debounce ms]: compile and deploy after each save. Point it at a staging site.
  • app status [slug]: the serving release, the previous one, failures and the kill switch.
  • app rollback <slug> [--to release] [--force]: swap back to the previous verified release, or the named one.
  • app pull <slug> [--release id] [--out dir] [--force]: read an app back from a site into a folder. See below.
  • app logs <slug> [-f] [--channel] [--level] [--since] [--lines] [--interval]: read or follow an app log.
  • app job list [--app]: the schedule and how late each job runs.
  • app job run <hook> [--app]: run one job now.

Copy an app from one site to another

You can copy an app from one of your sites to another. app pull reads a release back from the first site, and an ordinary deploy puts it on the second.

respira app pull pen-pals --site shop-a --out ./pen-pals
respira app deploy ./pen-pals --site shop-b
  • What it copies. The release as the site holds it: PHP as written, and JavaScript and email templates in their built form (compiled assets/*.js, emails/<kind>/<lang>.json, and the template digests in app.json). Every file is checked against its sha256, and the whole against the release id, before anything is written. Deployed unchanged, the folder gets the same release id on the other site.
  • What it does not copy. Data: the rows in the app's tables, so the other site starts with empty tables made by the migrations. Secret values, which the owner of the other site sets. Tables the app adopted on the first site, which do not exist on the other. Option values, and mail settings: the owner of the other site picks the provider. The command lists these by name in needs, never a value.
  • Release pinning. By default it pulls the release that serves. --release <id> pins one: an older release, or one that failed or only ran a canary. The answer says which it is with state: current, previous, earlier, never_served or failed, and whether it passed its checks on that site. A release that failed there may not work on another site either.
  • The marker. The folder gets a .respira-pulled file that names the release and the sha256 of every file. It is a dotfile, so it never goes up in a bundle. A deploy honours it in one way only: a listed file whose bytes still match is not left behind in a folder where an ordinary deploy would leave it (tests/, node_modules/ and the like). It switches no check off and compiles nothing differently.
  • The output folder must be new or empty. --force writes over files of the release and deletes nothing else.
  • On the other site Respira Code must be installed and switched on, a key must have developer access, the owner approves the first deploy of the app there, and the release goes through the same lint, canary and checks.
  • A name the site never hands back, such as wp-config*.php, auth.json or *.local.json, is left out and listed in omitted. The release id then cannot be reproduced, and the other site gives it a new one.

respira code, db and site

  • code status: whether this key holds developer access, and until when. Without --site, every connected site.
  • code arm [--wait] [--timeout s]: check whether this key has developer access and, if not, say what the owner has to do: press Give developer access on the key, in wp-admin. With --wait it keeps checking. It does not give access itself, and nothing but the owner in wp-admin can. A connect step does not need it.
  • db query <sql> [--limit] [--offset] [--args json]: run one guarded SELECT.
  • db query --write <sql> [--yes] [--approval-token] [--backup-confirmed]: dry run, your yes, then the write.
  • site brief: developer access, host facts (PHP, file changes, loopback, exec), the loader and the apps that run.
  • wp api <query> [--kind] [--scope] [--permission] [--limit n] [--cursor]: search the site's own WordPress for a function, class, hook or deprecation, or with --scope what plugins and the theme declare. It reads the site's own API index. Plugin-only kinds, such as route and listener, need a scope other than core.

MCP tools

The add-on adds 10 tools. The list below is generated from mcp-server/src/code-tools.ts, where the server names them wordpress_* and then exposes each as respira_*. They are listed wherever the add-on answers, and the add-on refuses a call from a key without developer access itself. The server sends tools/list_changed when that answer changes.

  • respira_app_deploy (needs developer:apps): Deploy an app: upload the files the site lacks, canary, promote and verify. Takes promote: false for a canary only and checks: auto, server or client.
  • respira_app_rollback (needs developer:apps): Roll an app back to its previous release, or to the one named in to. A release with a failure record needs force.
  • respira_app_status (needs developer:apps): The apps on the site with the serving and previous release and the failures. With slug, one app with all its releases.
  • respira_app_logs (needs developer:apps): An app's log and always its deploy state. Read it before you retry after a failure.
  • respira_app_pull (needs developer:apps): Read an app back from this site, one page at a time, to copy it to another site. Reads only.
  • respira_db_query (needs developer:sql): One guarded read: a SELECT or EXPLAIN SELECT, with placeholders and a page size.
  • respira_db_write (needs developer:sql): One INSERT, UPDATE or DELETE in two calls: a dry run that returns a receipt, then the write with that receipt.
  • respira_site_brief: What this key may do and what the host can do, before you build.
  • respira_code_status: Whether this key holds developer access, until when, and why not.
  • respira_wp_api_search: Look up a WordPress function, class, hook or deprecation in the site's own files, and what installed plugins declare.

A deploy by path through MCP does not compile TypeScript or email templates; use the respira CLI for those. respira_app_pull returns one page of files at a time: call it again with the release the first answer named and the cursor it gave, until the cursor is null, then deploy all the files to the other site.

Exit codes

  • 0 success.
  • 1 internal, server or network error. Retry once if retry_ok is true.
  • 2 usage, invalid input, confirmation required, unsupported. Fix the call.
  • 3 account sign-in missing or expired. Only a person runs respira auth login.
  • 4 licence required or quota used.
  • 5 site, page or builder not found or unreachable.
  • 6 rate limited. Wait, then retry.
  • 7 CHECKS_FAILED: a check failed. respira doctor found a failing check, or app lint found errors.
  • 10 CODE_SCOPE: the key has no developer access, or the time the owner chose has ended. Only the owner can give it, in wp-admin.
  • 11 CODE_NOT_READY: Respira Code is switched off, setup is not finished, or the licence lapsed.
  • 12 CODE_KILLED: the kill switch is on. Only the owner switches it back.
  • 13 CODE_OWNER_APPROVAL: the owner has to tap or approve once. The first deploy of a new app is this, with the 409 respira_code_first_deploy_tap, and the hint says where.
  • 14 CODE_BUSY: another deploy or rollback holds the lock, or a migration is running. Wait and retry. The same code covers the 409 respira_code_lock_lost: this request no longer held the deploy lock and changed nothing, because another request, a newer deploy or an expired lock took it. Check the app's status before you deploy again.
  • 15 CODE_REFUSED: the site refused the bundle, manifest, migration or statement. Nothing was written.
  • 16 CODE_RELEASE_FAILED: a canary or verify failed. The old release keeps serving.
  • 17 CODE_HOST: this host cannot do it, for example no file changes or no mu-plugins.
  • 130 cancelled.

Never retry a write that timed out. Read the state first, and retry only if the read shows the write did not land.