Run and test
CLI command reference
The chalupa command table: each command's flags and behavior.
Reviewed 2026-10-16
Each row gives a command, its flags and what it does. Actions that change something are listed with their risk and exact phrase in Actions and confirmations. The install, the operator UI and the safety rules are in Local CLI and operator UI.
Command reference
| Command | Behavior |
|---|---|
chalupa |
Opens the operator UI when both input and output are interactive terminals. Prints help when invoked with no arguments outside a TTY. |
chalupa doctor --secrets [--config PATH] [--json] |
Names-only credential report: what the config needs, where each resolves from (TinyVault project and key, ambient, legacy file), locked or missing state and conflicts. See Choose the TinyVault source. |
chalupa doctor [--json] [--verbose] |
Reports separate offline and full-operator readiness without running the operator tools. --verbose (-v) adds a footnote stating what the check did and did not query. |
chalupa inspect [--config PATH | --demo] [--json] |
Builds a local inspection. Needs a config (here, above, or --config); --demo describes the bundled demo-harbor fixture. |
chalupa status [--config PATH] [--json] [--timeline] |
Reads local Pulumi status for BYOC; managed configs query the console and print the host and expiry. With --json, a running BYOC host that has a registered session also reports startedAt, expiresAt, extensionsLeft, elapsedMs and estimatedSpendUsd (omitted, never zero, when unknown; spend needs a known hourly rate). |
chalupa receipt [--last | --since 7d | --campaign NAME] [--json] [--redact] [--config PATH | --env NAME] |
Prints one line per session from the local timing ledger: alive, ready in (and the long pole) or why it never became ready, flows, wait vs work, idle, estimated cost and retained storage (data plus image cache). Offline; see Costs and idle observation. |
chalupa mark SPAN --start|--end|--point [--label KEY=VALUE] [--outcome ok|failed|skipped] (--config PATH | --env NAME) |
Appends one span boundary (or, with --point, one instant) to the session ledger so a harness can time its own phase: image-build per image, apps-build, apps-up, first-flow, flows. A local file append only. |
chalupa box timeline [--session ID] [--backfill] [--json] [--config PATH | --env NAME] |
One session stage by stage, offline: the ledger plus the box's own facts from the snapshot down took (container starts, the health gate, SSH throttling and refused forwards). --backfill keeps those facts for older closed sessions before snapshots rotate. See Costs and idle observation. |
chalupa tui [--config PATH] |
Opens the interactive operator UI. An explicit invocation fails outside a TTY. Home reports the supervised tunnel's health from the local state file (up and reconnect ages, or a caution when its supervisor is gone). |
chalupa setup [--inference] [--no-console] [--no-reaper-token] [--provider chalupa|digitalocean|hetzner] [--force] [--json] |
Interactive setup asks what to do first: Managed GPU, or Test my Docker Compose stack (BYOC), with the Compose choice preselected when a Compose file sits next to the config. Managed is the default for --json and for --inference without --provider; BYOC needs --provider. Managed flow: local key, account login, starter, balance and next command. --provider chalupa skips selection and implies inference. It signs you in with an emailed code and stores the session that billing, balance, shares and managed launches use. BYOC adds provider credentials and an SSH allowlist. Inference offers to arm the console reaper using a separate DigitalOcean token with only droplet:read and droplet:delete; --provider hetzner offers the same arming once linked (no --inference needed for it) using a Read & Write token from a Hetzner project dedicated to Chalupa — Hetzner tokens are project-wide and cannot be scoped further. Plain DigitalOcean BYOC (no --inference) gets the same reaper offer. --no-reaper-token skips arming for every BYOC provider; --no-console skips linking too. JSON mode submits only when CHALUPA_SETUP_REAPER_TOKEN is set and an account is linked. |
chalupa exec [--config PATH] -- COMMAND [ARGS...] |
Runs a local command through managed tunnels; closes tunnels on exit and retains compute. |
chalupa up [--config PATH] [--wait] [--fresh | --reuse-only] [--keep-on-bootstrap-failure] |
BYOC: delegates to Task, asks for the launch <environment> confirmation, and after provisioning opens a temporary tunnel and waits for the forwarded ports and compute.health. --wait also waits for the compute.readiness probes through a supervised tunnel. With session.keepFor or session.reuse: auto a live, unchanged box is reused instead of launched; a changed config is refused unless --fresh. --reuse-only (needs --config) reuses a live, unchanged box or refuses with exit 1 and a reason code; it never launches, so it needs no --confirm and no terminal. Managed up shows price, estimate and balance, rejects insufficient credit before queueing and asks yes/no on a TTY; --yes, --json, --model, --tier and --region launch with optional model/tier/region overrides for this run; validates VRAM fit and saves choices in the managed record without editing YAML. Checks capacity before queueing; offers alternatives or a 60-second poll for up to 20 minutes. Non-TTY/JSON needs --yes or CHALUPA_YES=1; no capacity prints alternatives and exits 1. |
chalupa down [--yes] [--config PATH] |
Managed: asks yes/no (--yes for scripts), stops compute and retains the cache; --confirm "down <slug>" queues the teardown non-interactively and removes the local record after success. BYOC scripts use an exact --confirm "sink <environment>" phrase and an explicit config. |
chalupa launch [opencode|omp|crush|local-agent|sonar|vecai] [--config PATH] [--context auto|native|TOKENS] |
Uses inference.agents.default; context defaults to auto. Opens and closes its own tunnel. |
chalupa tunnel [--config PATH] |
Holds a standalone SSH tunnel until interrupted (Ctrl-C closes it). With a lazy leased tunnel (the default for tunnel.local: leased) it instead attaches to the one background supervisor, starting it if needed: Ctrl-C only detaches, and chalupa tunnel stop closes it. Managed configs use the pinned host key in the local record and forward Ollama to port 11435 by default. |
chalupa tunnel keep|stop|status|watch [--config PATH] [--json] |
keep opens a supervised tunnel in the background, stop closes it, status reports it and watch runs it in the foreground. --json works for keep, stop and status. |
chalupa tunnel ls [--json] |
Lists every environment on this machine with tunnel leases or a supervised tunnel: mode, supervisor state, pid, local-to-remote ports and the last reconnect. Reads local files only. |
chalupa tunnel stop --all |
Stops every supervised tunnel recorded on this machine, each through the same stop as chalupa tunnel stop --config, using the config path its supervisor recorded. A tunnel started by an older version has no recorded path and is listed with the command to run by hand. Exit 1 when any needs that. |
chalupa tunnel gc [ENV...] [--dry-run] [--json] |
Releases leases (the stable local ports of tunnel.local: leased) for environments with no running tunnel whose recorded config file no longer exists, plus any you name. A lease with a running tunnel is never released. Local files only. |
chalupa urls [--config PATH | --name ENV] [--json] |
Where each forwarded service is reachable from this machine: http://127.0.0.1:<port> for web services, 127.0.0.1:<port> for tcp ones (<scheme>://127.0.0.1:<port> when expose declares a scheme), openPath when it declares an open path, a route (http://<service>.<environment>.localhost:7355) for web services of a leased environment while chalupa proxy runs (for browsers, not agents), plus the console link and the OpenAI base URL of a GPU environment. Offline; --json is the contract for agents (the MCP tool chalupa_urls returns the same document; in leased mode either may write the local lease file to reserve the ports). chalupa connect --format env and chalupa exec --format env export the same addresses as CHALUPA_<SERVICE>_URL (CHALUPA_<SERVICE>_ADDR, host:port, for tcp services), _HOST and _PORT, and CHALUPA_CONSOLE_URL. |
chalupa wait [--config PATH] [--probe NAME] [--timeout SECONDS] [--json | --events ndjson] |
Waits for every declared compute.readiness probe through the tunnel and prints when each became ready. Open a tunnel first with chalupa tunnel keep. |
chalupa session status [--config PATH] [--json] |
BYOC, read-only: one reconciled deadline (local registration against what the console was told, and the lifetime cap) with the extensions left. |
chalupa session extend|renew|release [--config PATH] |
Extend a live session, re-lease an expired one whose server still runs, or release a warm box for session.keepFor (--keep-for 45m, or --sink for the confirmed down). |
chalupa apps build|up [--config PATH] [--ssh USER@HOST] [--identity FILE] [--json] |
Print the app-image build script and the app compose up. They do not run it. |
chalupa apps swap SERVICE [--from REF|HEAD | --use-tag TAG] [--confirm "swap <environment>"] [--keep N] [--no-ready] [--dry-run] [--json] |
Replaces one running app service without rebuilding it: a derived image from the one on the box plus a clean export of the git ref, restarting only that service and keeping the previous tag. |
chalupa apps ls [--config PATH] [--json] |
Lists the swap tags kept on the box. |
chalupa data load <archive> --dataset DATASET [--config PATH] [--confirm "load <environment>"] |
Uploads a checksummed archive once to the running box's protected volume (sha256 verified on the box); restore it per case with a cleanupRecipes entry and chalupa reset --dataset DATASET. --name DATASET still works here as a deprecated spelling of --dataset. |
chalupa cache-up|cache-nuke [--config PATH] [--confirm PHRASE] |
Creates (cache <environment>) or deletes (drop cache <environment>) the disposable <env>-cache volume for Docker images and build cache. It is billed separately and never touches the protected data volume. |
chalupa explain [--json] |
Returns the whole agent-facing surface as data: every action with its risk tier and confirmation phrase. |
chalupa docs [TOPIC] [--json] |
Prints focused documentation offline. Topics: inference, overview, actions, non-interactive, config, safety. |
chalupa box refresh [--config PATH] |
Re-delivers what Chalupa runs on a live box (heartbeat agent, Monitor forwarder, crash-capture service) over SSH, verified by digest, without relaunching it. Not billable; no phrase, terminal or cloud.url needed. Same action as chalupa runtime deliver. |
chalupa preview [--config PATH | --demo] |
Shows the project configuration and estimate offline. Needs a chalupa.yml (here, above, or --config); --demo previews the bundled demo-harbor fixture. |
chalupa ACTION [--config PATH] |
Delegates one allowlisted public action to Task from the Chalupa repository root. |
chalupa ci arm|follow|cancel|report|artifacts|secrets|collect [--config PATH] |
Delegates a namespaced ci: action. ci follow --json streams the run's events as NDJSON with no terminal; ci secrets reads NAME=value lines from stdin (never a terminal); ci collect brings a settled run's evidence home. |
chalupa ci status [--config PATH] [--json] |
Reads bounded CI run state from the environment, the ci: sibling of chalupa status. A run armed a moment ago whose engine has not yet taken its lock is reported with phase starting, not as the previous run. |
chalupa teardown register [--config PATH] |
Delegates the namespaced teardown:register action. |
chalupa account [--json] |
Reads a redacted hosted-account snapshot from local files only. |
chalupa session allow [--config PATH] |
Managed only: detect the current IPv4 /32 and update SSH access. Managed session extension is not available yet. |
chalupa balance [--top-up 10|25|50] [--json] |
Shows the Managed GPU prepaid balance and rates, or opens Stripe Checkout for a top-up; needs a linked account. |
chalupa audit [--json] --provider digitalocean|hetzner (or run it where a chalupa.yml names the provider) |
Read-only provider inventory: Chalupa droplets, volumes, snapshots, firewalls and keys with project membership (DigitalOcean), or chalupa-labeled servers and volumes (Hetzner), with estimated cost and leftovers. Never changes anything. |
chalupa gc [--json] --provider digitalocean|hetzner (or run it where a chalupa.yml names the provider) [--delete NAME --confirm "reclaim NAME"] |
Dry run of compute no local stack tracks (with $/h). --delete reclaims one leftover after the literal confirmation and verifies the provider no longer lists it, on DigitalOcean and Hetzner alike. Nothing is proposed while any local stack is unreadable, and a golden-image build (either provider) started less than 2 h ago is never proposed. Storage stays. |
chalupa snapshot build [--config PATH] [--with-verifiers [--toolchain onbox --cairntrace VERSION|/abs/path.tgz [--node-version V]] [--recipe-sha256 HEX]] [--confirm "bake <env>"] |
Bakes a golden image (DigitalOcean or Hetzner) on a temporary billable host and records it in ~/.chalupa/goldens.json. Prints the estimate (about 10 minutes of the configured size) and, with --with-verifiers, exactly which tool versions it would install plus a recipe sha256; it does nothing without --confirm. --toolchain onbox is the on-box CI toolchain: Node 22.22.0 (exact, checksum-pinned), cairntrace at an exact npm version or a local .tgz for pre-release testing, Playwright and playwright-core 1.61.1 (exact) with Chromium as the only browser (no agent-browser), mongosh, the temporal CLI, jq and rsync; the bake asserts each pinned version and records the observed ones in /etc/chalupa/toolchain.json and in the image stamp, and the pins in ~/.chalupa/goldens.toolchain.json (snapshot status shows them). --recipe-sha256 carries the digest the dry run printed: the baker refuses any other recipe, and a local .tgz bake requires it. Ctrl-C deletes the build host before the command exits; the setup run is capped at 90 minutes. The build host gets only the project's SSH key, is tagged chalupa, and its host key is pinned for the setup run. With no ssh.identityFile / CHALUPA_TASK_SSH_IDENTITY, the ssh-agent must hold a key matching one of the selected account keys (ssh-add -L); otherwise the bake is refused before the host is created. |
chalupa snapshot status [--config PATH] [--json] |
Lists the environment's golden images with age, the Chalupa and Monitor versions that baked them, and which one compute.image uses; flags stale or behind-the-pin images. Read-only. |
chalupa snapshot prune --keep N [--config PATH] [--confirm "prune goldens <env>"] |
Dry run by default. With the literal confirmation, deletes the environment's goldens beyond the newest N (at least 1), never the one compute.image uses and never another environment's images or the protected data volume's snapshots. |
chalupa storage sweep [--config PATH]... [--rate USD] [--apply | --confirm "retire storage <env>"] |
Warm-day storage. For an environment that declares persist.onDemand and/or cache.retireAfterIdleHours, prints what is idle on this machine's session ledger and what retiring it would free; read-only (no tvault, no provider call) without --apply or --confirm. Applying deletes the idle cache and snapshots the data volume, verifies the snapshot at the provider, then destroys the volume; a failed snapshot destroys nothing. It never retires while a compute box is recorded, never without a ledger, and the data step needs --rate (or SNAPSHOT_RATE_USD_PER_GIB_MONTH). The next chalupa up restores what it retired. See Warm-day storage. |
chalupa login [--url ORIGIN] [--config PATH] |
Legacy operator-only device authorization; an administrator must approve the terminal. |
chalupa open [console|billing] [--url ORIGIN] |
Opens a hosted view through a short-lived, one-use browser grant. |
chalupa open <service> [--route] [--config PATH | --name ENV] |
Opens a forwarded web service's local URL in the browser, plus the path its expose entry declares as open. Needs no grant and no terminal. The service name may come before or after the flags. Use --service NAME for a service called console or billing. --route opens the .localhost route instead of 127.0.0.1:<port> and starts the proxy if it is not running; it is refused for a canonical environment, which has no routes. |
chalupa proxy start|stop|status [--json] |
The local reverse proxy behind routes, for people in a browser. start runs it in the background, stop ends it, status lists every route and its tunnel. See Local routes. |
chalupa logout |
Revokes hosted sessions and removes both local credential files. |
chalupa monitor VERB [ARGS...] [--config PATH] |
Read-only: runs one Monitor read verb (issues, snapshot, processes, diff, hot and the others listed under observability) on the box over SSH and prints Monitor's output and exit code verbatim. A mutating verb is refused locally with exit 64. After --, everything goes to Monitor (chalupa monitor -- issues --help). |
chalupa monitor serve (--config PATH | --name ENV) |
Read-only stdio door to the box's Monitor for Monitor Desktop and other monitor.app.v1 clients. See Performance telemetry. |
chalupa logs [SERVICE...] [--since T] [--until T] [--grep RE] [--level L] [--tail N] [--box] [--follow] [--json] |
Read-only: a running box's logs over a fixed SSH allowlist. See Logs, diagnose and evidence. |
chalupa diagnose [--since-up] [--recipe NAME] [--no-recipes] [--bundle DIR] [--json] |
Read-only: containers, memory, disk, cloud-init, failed units and your declared diagnostics: recipes. |
chalupa evidence (--last-failed | --run-dir DIR) [--live | --snapshot] [--json | --md] [--out FILE] |
Read-only: a failed test run joined with the box for that run's time window. |
chalupa mcp [--config PATH] |
Read-only MCP server over stdio. See Chalupa for agents. |
chalupa run ACTION [--config PATH] |
Compatibility form of the same actions, spelled with the exact Taskfile name. |
An action whose Taskfile name contains a colon is typed as two words, so
chalupa ci arm delegates to the ci:arm action and chalupa teardown register
delegates to the teardown:register action. Both spellings resolve to the same
allowlist entry, risk classification, confirmation phrase, and TTY rule;
chalupa run ci:arm remains accepted for scripts written against the earlier
surface.
The CLI passes only the canonical config path to Task. Other Taskfile inputs
are read from the environment, so a dedicated key is selected with
export SSH_IDENTITY=/absolute/path/to/private-key before the command.