Your first app
From a site brief to a release that serves, and back again.
This page walks one app from a site brief to a rollback. The command output is real: it comes from a test site, while building a Black Friday app with a landing page, a countdown and automatic cart discounts, and is trimmed. The manifest further down is a pen-pal app Mihai built for a client site, abridged.
Before you start: two things only the owner can do
Ask the site owner for both now, so you are not waiting later. The commands below are written short, as respira site brief. If the respira CLI is not installed, run each one as npx -y @respira/cli site brief --site my-site. After npm install -g @respira/cli the short form works as written.
- Connect the agent. Two blocks. First, the owner gives a key developer access: on the Respira Code screen, under Keys, press Give developer access on the key the agent already uses, or press Create a Respira Code key and run the connect command it shows once. Then the owner pastes the prompt under Paste this to your AI agent to the agent. How long the access lasts is the owner's choice: 24 hours, 7 days, 30 days or until the owner switches it off.
- Allow the first deploy. The first deploy of every new app is refused with a 409,
respira_code_first_deploy_tap, and the respira CLI exits with 13. The owner opens the Respira Code screen in wp-admin and presses the button labelled Allow the first deploy. Then you deploy again. It is needed once per app, and an agent cannot press it, so ask the owner before you deploy. The refusal also names the page:wp-admin/admin.php?page=respira-code#first-deploys.
1. Brief the site
respira site brief reads what the site can do: developer access, PHP, whether file changes are allowed, whether the site can fetch its own pages, the apps loader and the apps that already run.
$ respira site brief --site bf --output table
http://bench.test:8093
This key holds developer:apps, developer:sql, developer:cli until 2026-11-12T19:58:22.000Z.
WordPress 7.1.4
Respira plugin 9.3.11
PHP 8.4.27 (fpm-fcgi)
file changes allowed yes
mu-plugins writable yes
loopback (site fetches itself) yes, HTTP 200 in 176 ms
apps loader installed 1.1.3
kill switch off Read the loopback line. A host that cannot fetch its own pages cannot run the canary itself, so the respira CLI runs the checks from your machine and the site checks the signed result. Nothing for you to change, but the deploy takes longer. Run it with --output table for a readable form; without a terminal every command prints one JSON object.
About modes: the respira CLI has a global flag, --mode cloud|direct, and the default is cloud, which sends page and post commands through respira.press. --mode direct sends those commands from your machine straight to the plugin on the site. The Respira Code commands (app, db, code, site brief, wp api) always go from your machine straight to the add-on, so the flag changes nothing for them.
2. Scaffold
respira app init black-friday --dir ./app --name "Black Friday"
cd app app init writes app.json, entry.php, migrations/, i18n/, assets/ and tests/. The slug is lowercase letters and digits with hyphens inside, at most 40 characters, and it starts and ends with a letter or a digit.
3. Write the manifest
{
"manifest_version": 1,
"slug": "pen-pals",
"name": "Pen pals",
"version": "1.0.0",
"requires_php": "7.4",
"entry": "entry.php",
"health": true,
"tables": [ { "name": "pen_pals_people" }, { "name": "pen_pals_matches" } ],
"routes": {
"namespace": "pen-pals/v1",
"endpoints": [
{ "path": "/signup", "methods": ["POST"], "auth": "public", "public": true,
"reason": "Anyone may sign up; the handler rate limits.", "rate_limit": "5/hour" },
{ "path": "/admin/overview", "auth": "capability:edit_pages", "rate_limit": "240/min" }
]
},
"cron": [ { "hook": "pen_pals_hourly", "schedule": "hourly", "timeout": 120 } ],
"contracts": [
{ "url": "/pen-pals", "status": 200, "must": ["id=\"pp-form\""], "must_not": ["Fatal error", "[["] }
],
"i18n": { "default": "en", "languages": ["en", "ro", "de"] }
} The manifest page lists every key. Three things in this one matter on day one. A write route may be public only when its endpoint says "auth": "public", "public": true and a reason, and its handler calls respira_app_rate_limit() before the first write. contracts are page checks the canary runs: they are how a release that breaks a page gets caught. health turns on your respira_app_health filter as a check.
Every PHP file starts with the ABSPATH guard. Inside a namespace, write it with the leading backslash, so an app cannot declare its own defined() and turn the guard into nothing.
namespace RespiraApp\PenPals;
if ( ! \defined( 'ABSPATH' ) ) {
exit;
} Keep every function and class inside a namespace such as RespiraApp\PenPals. A release that declares a name WordPress or another plugin already defines is refused before it loads.
Inside a namespace, call the kit with a leading backslash, or import the name with use function. The lint reads \respira_app_rate_limit() and \respira_app_owner_request() only in those two forms. An unqualified call could run a function of your own namespace first, so it does not count as the kit's, and a public route written with it is refused.
function signup( \WP_REST_Request $request ) {
$ip = isset( $_SERVER['REMOTE_ADDR'] ) ? \sanitize_text_field( \wp_unslash( $_SERVER['REMOTE_ADDR'] ) ) : '';
if ( ! \respira_app_rate_limit( 'signup:' . $ip, 5, 3600 ) ) {
return new \WP_REST_Response( array( 'error' => 'slow_down' ), 429 );
}
// The first write comes after the check.
return new \WP_REST_Response( array( 'ok' => true ), 201 );
} 4. Lint
respira app lint
respira app test --site my-site
respira app deploy --site my-site
respira app status black-friday --site my-site
respira app rollback black-friday --site my-site respira app lint runs the local tools it finds, then, with --site, uploads the release and shows the add-on's own lint. The upload lint page has every rule with its fix.
$ respira app lint . --site bf --output table
site lint: upload, then the add-on lints the release
upload: 13 files, 48.3 KB
warning Deprecated WordPress functions were not checked: the WordPress API index is not built on this site yet. [site: deprecated-index-missing]
ran: php -l, the site lint
skipped phpstan: PHPStan is not installed
to install it: composer require --dev phpstan/phpstan php-stubs/wordpress-stubs
✓ no errors, 1 warning An error refuses the release and nothing is written. The exit code is 15.
$ respira app lint /tmp/ex/broken2 --site bf --output table # an unprepared query, an eval and an unescaped echo
✗ 4 things to fix before this release can go up. Nothing was written. includes/Cart.php:40 [no-eval] eval() runs text as code. Fix: Remove eval().
[exit 15] 5. Deploy
The first deploy of a new app stops at the owner's approval. The release is uploaded, nothing serves it, and no table is touched.
$ respira app deploy . --site bf --output table
plan: 13 files, 48.3 KB, release 0.1.0-40ca8e59fb6b
deploy: canary, promote, verify
✗ The first deploy of this app needs the site owner to approve it once on the Respira Code screen. Ask them, then deploy again.
It takes one tap, and only for the first deploy of each app. Where: http://bench.test:8093/wp-admin/admin.php?page=respira-code#first-deploys
[exit 13] After the owner presses Allow the first deploy, run the same command again. These steps run:
- Upload. The respira CLI sends only the files the site lacks. A release id is the version plus a content hash, so the same files are the same release.
- Check and lock. The site validates the release, asks for the first-deploy approval if the app is new, and takes the deploy lock. One deploy runs at a time.
- Snapshot and migrate. Pointers, options and tables are snapshotted, then additive migrations run.
- Canary. For 120 seconds only requests that carry a one-use token see the new release. The site checks the home page,
wp-login.php, the REST index, each contract and your health filter. Tests intests/*.phprun here too. - Promote. The
currentpointer moves.previouskeeps the old one. - Verify. The same checks run again with no token. A failure swaps the pointer back.
On a host that cannot fetch its own pages, the deploy answers with a handoff and the respira CLI runs the checks from your machine, with a signed result the site re-checks. That is what --checks auto, the default, does. --checks client forces it and --checks server insists on the site.
6. Read a canary refusal
The first real deploy of 0.1.0 failed its own contract. The page checks said the landing page had to contain bf-hero, and the app's output filter had removed the tag around it.
$ respira app deploy . --site bf --output table
✗ 0.1.0-40ca8e59fb6b did not pass its canary
canary: failed in 657 ms
ok home (HTTP 200, 158 ms)
ok login (HTTP 200, 93 ms)
ok rest (HTTP 200, 184 ms)
ok contract:0 (HTTP 200, 161 ms)
FAIL contract:1 (HTTP 200, 175 ms)
/black-friday/: missing marker "bf-hero"
ok admin_ajax (HTTP 200, 107 ms)
ok direct:release (HTTP 200, 3 ms)
ok direct:state (HTTP 200, 3 ms)
ok app_health (HTTP 200, 653 ms)
✗ 0.1.0-40ca8e59fb6b failed its canary and was never promoted; the old release keeps serving
fix the app and deploy again; the failed checks are in the details
[exit 16] - Each line is one check.
okpassed,FAILdid not, and the lines under a failure say why: a status that was not expected, a marker that is missing, a marker that must not be there, or a critical error page. contract:1is the second item ofcontractsin app.json, counting from 0.- The release was never promoted. The old release, or nothing for a first deploy, keeps serving.
- The release is now recorded as failed. A release that failed stays failed: change a file and deploy again, and the new content hash makes a new release id.
- The exit code is 16.
error.details.failedin the JSON output lists each failed check with the status it got.
7. A deliberate broken deploy
This one is deliberate, to show what the guard does. Version 0.2.0 calls a method that does not exist. The lint did not see it: it reads your code for risky patterns and never runs it. The canary did, because the home page answered 500.
$ respira app deploy /tmp/ex/broken --site bf --output table # 0.2.0 calls a method that does not exist
✗ 0.2.0-deea1e84b027 did not pass its canary
canary: failed in 311 ms
FAIL home (HTTP 500, 227 ms)
HTTP 500, expected 200
WordPress critical error page
ok login (HTTP 200, 220 ms)
FAIL contract:0 (HTTP 500, 210 ms)
/: missing marker "<!-- respira-app:black-friday -->"
/: forbidden marker "There has been a critical error" present
[exit 16] The release never served. The status shows it as failed, with the fatal, and the version that was serving before keeps serving.
$ respira app status black-friday --site bf --output table
black-friday
serving 0.1.2-0004d92ac749
current 0.1.2-0004d92ac749
previous 0.1.1-9adfc5e4b498
release version state failed
0.1.0-40ca8e59fb6b 0.1.0 yes
0.1.1-9adfc5e4b498 0.1.1 previous
0.1.2-0004d92ac749 0.1.2 current
0.2.0-deea1e84b027 0.2.0 yes
failed 0.2.0-deea1e84b027: fatal, Uncaught Error: Call to undefined method RespiraApp\BlackFriday\Cart::round_to_nearest_five() If a request dies without reaching shutdown three times, or a fatal comes from the app's files after a release serves, the crash guard marks the release failed and the previous one takes over on the next request.
8. Roll back
$ respira app rollback black-friday --site bf --output table
✓ black-friday now serves 0.1.1-9adfc5e4b498 (was 0.1.2-0004d92ac749)
healthy
swap 18 ms, total 503 ms This is what a rollback does, exactly.
- The target is a release that passed verify on this site. By default that is
previous, when it passed and has no failure record. Otherwise it is the most recently verified release other than the one that serves.--to <release>names one. A release that never passed verify here is refused withrespira_code_rollback_unverified: deploy it instead, with its canary and approval. A verified release with a failure record needs--force. - It restores pointers only. It moves
currentandpreviousafter taking a pointer snapshot. Tables stay as they are, applied migrations stay applied, and rows written since stay. If the release you roll back to expects an older table shape, that is yours to handle: migrations are additive for this reason. - Then the site checks the result. If the target passes, the answer says
healthy. If it fails its checks, that release is marked failed and, on a host that can fetch its own pages, the rollback tries the next verified release, up to four in all. If none is healthy, the app is disabled and the other apps keep serving. That answer exits with 16.
Rolling forward again is an ordinary deploy of the same files. Same files, same release id, and the canary runs again.