# How Respira Code works: the terminal and an app, in the open | Respira

> For developers: what the Respira CLI prints when you deploy, roll back and look things up, and what a Respira Code app looks like.

Source: https://www.respira.press/code/how-it-works

---

[Back to Respira Code](https://www.respira.press/code)

# How Respira Code works

For developers: what the terminal prints and what an app looks like.

## What the terminal prints.

Five things you will do in a terminal. Each tab shows what the terminal printed, from a recorded run.

respira app deploy /tmp/pp-scratch/penpal --site penpal-bench --checks server

```
  bundle: /tmp/pp-scratch/penpal
  plan: 86 files, 2033.2 KB, release 1.0.14-9d6dbed2935b
  upload: 1 file, 15.2 KB
  deploy: canary, promote, verify
✓ deployed penpal 1.0.14 as 1.0.14-9d6dbed2935b (previous: 1.0.11-7a97d231de33)
! assets is not read by this version of Respira Code yet

  canary: passed in 88 ms
    ok   home (HTTP 200, 46 ms)
    ok   login (HTTP 200, 25 ms)
    ok   rest (HTTP 200, 35 ms)
    ok   contract:0 (HTTP 200, 38 ms)
    ok   contract:1 (HTTP 200, 42 ms)
    ok   contract:2 (HTTP 200, 42 ms)
    ok   contract:3 (HTTP 200, 60 ms)
    ok   contract:4 (HTTP 200, 69 ms)
    ok   contract:5 (HTTP 200, 72 ms)
    ok   contract:6 (HTTP 200, 78 ms)
    ok   contract:7 (HTTP 200, 74 ms)
    ok   contract:8 (HTTP 200, 78 ms)
    ok   admin_ajax (HTTP 200, 25 ms)
    ok   direct:release (HTTP 200, 3 ms)
    ok   direct:state (HTTP 200, 4 ms)
    ok   app_health (HTTP 200, 50 ms)

  verify: passed in 89 ms
    ok   home (HTTP 200, 59 ms)
    ok   login (HTTP 200, 34 ms)
    ok   rest (HTTP 200, 44 ms)
    ok   contract:0 (HTTP 200, 44 ms)
    ok   contract:1 (HTTP 200, 47 ms)
    ok   contract:2 (HTTP 200, 40 ms)
    ok   contract:3 (HTTP 200, 68 ms)
    ok   contract:4 (HTTP 200, 68 ms)
    ok   contract:5 (HTTP 200, 73 ms)
    ok   contract:6 (HTTP 200, 73 ms)
    ok   contract:7 (HTTP 200, 76 ms)
    ok   contract:8 (HTTP 200, 71 ms)
    ok   admin_ajax (HTTP 200, 79 ms)
    ok   direct:release (HTTP 200, 3 ms)
    ok   direct:state (HTTP 200, 3 ms)
    ok   app_health (HTTP 200, 34 ms)

  files     86, sent 1 (15.2 KB)
  emails    compiled 48 templates (confirmare, confirmare2, info, invite, potrivire, remind), sha recorded in app.json
  checks    ran on the site
  snapshot  ptr-37f6b245-5ad4-4e61-8065-8fa3f63e0958, opt-938c4e2d-ece1-4829-86ce-ea61161961a4, tbl-622df65e-aff0-4abc-9233-f33f974a1d69, tbl-44e47ee9-90b3-49be-ad7e-6f8e0b7a94b4, tbl-ae3a1e28-b306-445f-9d0d-8a9d571a7a6e

  bundle (read and hash)    25 ms
  upload                    204 ms
  deploy call               248 ms
    on the site: validate   15 ms
    on the site: lock       2 ms
    on the site: snapshot   14 ms
    on the site: audit      4 ms
    on the site: migrate    1 ms
    on the site: canary     89 ms
    on the site: promote    2 ms
    on the site: verify     89 ms
  total                     477 ms

  within the 5 s budget for a small app

```

recorded 2026-11-11T16:00Z, pen-pal 1.0.14-9d6dbed2935b, Docker bench, PHP 8.4.27, CLI 0.1.6

respira app rollback penpal --site penpal-bench --to 1.0.11-7a97d231de33

```
✓ penpal now serves 1.0.11-7a97d231de33 (was 1.0.14-9d6dbed2935b)
  healthy
  swap 10 ms, total 711 ms

respira app status penpal --site penpal-bench
  penpal
    serving   1.0.11-7a97d231de33
    current   1.0.11-7a97d231de33
    previous  1.0.14-9d6dbed2935b

  release               version   state      failed
  ───────────────────   ───────   ────────   ──────
  1.0.0-57a4e4617547    1.0.0
  1.0.1-6846a49e13ba    1.0.1                yes
  1.0.11-7a97d231de33   1.0.11    current
  1.0.12-c0a6b0232f16   1.0.12               yes
  1.0.13-be81af07f354   1.0.13
  1.0.14-9d6dbed2935b   1.0.14    previous
  1.0.2-2c19b599071a    1.0.2
  1.0.3-52f6e85d7d40    1.0.3
  1.0.4-88e8ce179749    1.0.4                yes
  1.0.5-95a02dfbfdde    1.0.5                yes
  1.0.5-a2f25844c935    1.0.5
  1.0.6-2d4a05775480    1.0.6
  1.0.7-0b0a2e04feb6    1.0.7
  1.0.8-10222c32e9fa    1.0.8
  failed 1.0.1-6846a49e13ba: fatal, Uncaught Error: Call to undefined function RespiraApp\Penpal\penpal_case_study_missing_function() in wp-content/respira-apps/penpal/releases/1.0.1-6846a49e13ba/includes/Matcher.php:30
  failed 1.0.12-c0a6b0232f16: fatal, Uncaught Error: Call to undefined function RespiraApp\Penpal\penpal_undefined_helper_latent() in wp-content/respira-apps/penpal/releases/1.0.12-c0a6b0232f16/includes/Matcher.php:29
  failed 1.0.4-88e8ce179749: manifest, php file without the ABSPATH guard as its first statement: includes/Store.php (inside a namespace the guard calls \defined; no app declares defined, function_exists, class_exists, constant, die or exi
  failed 1.0.5-95a02dfbfdde: manifest, php file without the ABSPATH guard as its first statement: includes/Store.php (inside a namespace the guard calls \defined; no app declares defined, function_exists, class_exists, constant, die or exi

```

recorded 2026-11-11T16:00Z, pen-pal 1.0.11-7a97d231de33, Docker bench, PHP 8.4.27, CLI 0.1.6

recorded gate run g1-t04-latent (test harness)

```
PASS  T04 good release 1.0.0-60b2d40db9d2 deployed (loopback, 488 ms); X-Respira-App-g1-t04-1k7gzm5a9: 1.0.0-60b2d40db9d2
PASS  T04 latent release 1.0.1-4cc19bd464de passes the canary and is promoted; X-Respira-App-g1-t04-1k7gzm5a9: 1.0.1-4cc19bd464de
      req 1: HTTP 200, X-Respira-App 1.0.1-4cc19bd464de, 44 ms
      req 2: HTTP 200, X-Respira-App 1.0.1-4cc19bd464de, 45 ms
      req 3: HTTP 500, X-Respira-App 1.0.1-4cc19bd464de, 19 ms
      req 4: HTTP 200, X-Respira-App 1.0.0-60b2d40db9d2, 43 ms
      req 5: HTTP 200, X-Respira-App 1.0.0-60b2d40db9d2, 46 ms
PASS  T04 request 3 returns 500 (the latent fatal)
PASS  T04 attributed to 1.0.1-4cc19bd464de: Uncaught Error: Call to undefined function g1_latent_boom() in wp-content/respir (by path)
PASS  T04 request 4 serves previous: X-Respira-App-g1-t04-1k7gzm5a9: 1.0.0-60b2d40db9d2
PASS  T04 fatal to healthy in 0.04 s (budget 10 s), no human action, no Respira request in between
PASS  T04 GET /apps/g1-t04-1k7gzm5a9: current 1.0.1-4cc19bd464de (failed), serving 1.0.0-60b2d40db9d2

```

Recorded: the gate run for a latent fatal (PHP 8.4, Docker bench, 11 November 2026). This is the test harness output, not the CLI’s own. The release passed its canary, failed on the third request, and the next request was served by the previous release.

respira wp api wp\_insert\_post --site penpal-bench --limit 1

```
function   wp_insert_post( $postarr, $wp_error = false, $fire_after_hooks = true )
           wp-includes/post.php:4598  |  since 1.0.0
           Inserts or updates a post in the database.
           near: wp_get_recent_posts, wp_get_post_terms, wp_get_post_tags, wp_get_post_categories, wp_untrash_post_comments

  1 of 6 matches in WordPress 7.1.4

```

recorded 2026-11-11T16:00Z, pen-pal 1.0.11-7a97d231de33, Docker bench, PHP 8.4.27, CLI 0.1.6

respira db query "SELECT id, status, lang FROM wp\_penpal\_people ORDER BY id LIMIT 3" --site penpal-bench

```
  id   status   lang
  ──   ──────   ────
  1    vechi    ro
  2    vechi    ro
  3    vechi    ro

  3 rows, 0 ms

respira db query "UPDATE wp_penpal_people SET lang = 'ro' WHERE id = 1" --write --site penpal-bench
  dry run: UPDATE on wp_penpal_people would touch 1 row
Run it on 1 row of wp_penpal_people? [y/N] n
  not run. Nothing was changed.

```

recorded 2026-11-11T16:00Z, pen-pal 1.0.11-7a97d231de33, Docker bench, PHP 8.4.27, CLI 0.1.6

## An app is a folder you can read.

A manifest, an entry file, migrations and tests. The manifest says what the app owns: its tables, its routes with their rate limits, its admin screen, its scheduled jobs and the secrets it may ask for.

Respira Code reads it before the first line runs. A route with no permission check, or a public write with no rate limit, is refused at upload.

app.json

```
{
  "slug": "penpal",
  "name": "Pen-pal",
  "version": "1.0.11",
  "requires_php": "7.4",
  "requires_wp": "6.2",
  "entry": "entry.php",
  "health": true,
  "tables": ["penpal_people", "penpal_matches", "penpal_mail"],
  "routes": {
    "namespace": "penpal/v1",
    "endpoints": [
      {"path": "/signup", "auth": "public", "rate_limit": "5/hour"},
      {"path": "/me", "auth": "public", "rate_limit": "20/hour"},
      {"path": "/stats", "auth": "public", "rate_limit": "60/min"},
      …
    ]
  },
  "admin_pages": [{"slug": "penpal", "capability": "edit_pages"}],
  "cron": [{"hook": "penpal_hourly", "schedule": "hourly"}],
  "secrets": ["RESEND_KEY"],
  …
}
```

entry.php

```
namespace RespiraApp\Penpal;

foreach ( array( 'Store', 'Text', 'Geo', 'Fit', 'Receipts', 'Letters', 'Mailer', 'Matcher', 'PublicApi', 'Jobs', 'Pages', 'Admin', 'App' ) as $respira_penpal_part ) {
	require_once __DIR__ . '/includes/' . $respira_penpal_part . '.php';
}
unset( $respira_penpal_part );

App::boot( __DIR__ );
```

The pen-pal app, trimmed. Long lists are shortened to names, some keys are left out, and the dots mark what is cut.

## Measured on a real app.

- 827 msto deploy a release: upload, canary, promote, verify.
- 0.39 sto roll back to the release before.
- 1failed request is what a release with a hidden fatal cost. The next request was served by the previous release.

Pen-pal 1.0.11 on a Docker test bench, 11 November 2026.

Before any code runs, **48 rules** read every file of a release. **29** of them stop the upload.
