Local CLI and operator UI

The Chalupa CLI is the operator entrypoint for your environments. It can inspect a configuration, read bounded local state, and delegate approved actions to the public Taskfile actions bundled with it. It does not implement a second Pulumi lifecycle. With provider: chalupa, GPU commands instead call the console queue using the local account session; no provider token is needed.

Everything an operator does to a specific environment is a chalupa command: chalupa up, chalupa tunnel, chalupa seed, chalupa down, and the rest of the allowlist. The CLI never replaces the Taskfile; it selects one of its public actions and passes a canonical config path for BYOC. Managed GPU uses the console API and a pinned local SSH record.

Opening the interface does not contact DigitalOcean, read tvault, select a Pulumi stack, start Docker, or open SSH. An external process runs only after you explicitly request an action or refresh local status.

Install

curl -fsSL https://chalupa.run/install.sh | bash
chalupa --version

chalupa -V and chalupa version print the same thing.

The installer puts checksum-verified Bun and go-task on your PATH and installs or upgrades @thelacanians/chalupa-cli from the npm registry, with no sudo. If Bun and go-task are already installed, bun add -g @thelacanians/chalupa-cli installs or upgrades only the CLI. After that, operator commands work from your own project directory. go-task is required for any action that reaches the cloud, because the CLI delegates to it; chalupa doctor reports that separately.

Use the project in your current directory

Interactive commands find chalupa.yml in the current directory or an ancestor, stopping at the Git root. Explicit --config and the existing configuration environment variables take precedence. No billable operation falls back to the bundled demo. Scripts using --confirm still need --config on the same command line so the target and authorization remain explicit.

chalupa up
chalupa exec -- bun run dev
chalupa down

up checks local port availability before provisioning, then opens temporary tunnels to check the configured health endpoint. Without compute.health, it reports tunnel availability and leaves application readiness unverified. GPU inference also checks installed model metadata; a real turn is needed to observe loaded GPU placement. Readiness failures can leave compute running.

exec runs the supplied command locally, in your working directory, using the existing environment. It opens the Taskfile-owned tunnels and closes them on exit. It never creates or destroys compute, never rewrites .env, and never infers database passwords or URLs. Existing app connection settings should use the local ports shown in the connection output. The child also receives CHALUPA_ENVIRONMENT and CHALUPA_PORT_<remote-port> values.

For inference, chalupa launch (using inference.agents.default) configures the endpoint for your agent's process. See Agent harnesses for supported tools and chalupa exec -- my-agent for other commands. The command's stdout stays available for output or JSON receipts; Chalupa's connection messages go to stderr. Ctrl-C cancels the session, and a lost tunnel stops the local process. Compute remains running.

For a remote shell, use chalupa ssh. Image builds and live file synchronization are not provided by exec; selected Compose services require pre-built images.

Check the workstation

Run the executable check before operating an environment:

chalupa doctor
chalupa doctor --json

doctor reports offlineReady separately from operatorReady. The offline inspection path is ready when the CLI itself is running. Full operation also requires Task, Pulumi, tvault, SSH, and nc to be discoverable on PATH. doctor does not run those tools or query credentials, Docker, the network, local stacks, or a cloud provider; the one local program it does run is Python, to check validation readiness. Add --verbose to print a footnote that says exactly what was and was not queried. A missing operator requirement produces a non-zero exit while the report still identifies offline inspection as available.

Inspect safely first

With no config, inspect uses the repository's examples/demo-harbor fixture:

chalupa inspect
chalupa inspect --json

This is synthetic offline mode. It runs the same Compose inference as the Pulumi program and reports services, inferred roles, tunnel ports, named volumes, persistence, diagnostics, and the complete redacted remote Compose document. It does not run Task or any external process.

Redacted output is still operator information. Absolute paths, service names, topology, port numbers, images, and non-secret metadata can remain visible. Do not publish the output or treat it as a general data-loss-prevention scan.

Select a real configuration explicitly:

export DEMO_CONFIG="/absolute/path/to/project/chalupa.yml"
chalupa inspect --config "$DEMO_CONFIG"
chalupa tui --config "$DEMO_CONFIG"

Prefer --config in scripts and operator notes so the selected environment is visible at the call site.

Commands find ./chalupa.yml, then CHALUPA_CONFIG, then parent configs. --config PATH is an optional override. Legacy Taskfile config variables retain precedence. Managed up and down ask yes/no; use --yes for scripts.

Help and exit codes

chalupa --help lists the commands in groups (Start, Work on a box, Sessions and cost, CI and tests, Images and cache, Managed GPU and account). chalupa help <command> prints the flags of one command, for example chalupa help data or chalupa help session extend, and chalupa help --all prints every form of every command. chalupa <command> --help works too.

A usage error exits 64: an unknown command, an unknown flag, a missing argument, or a missing config. The message names the problem and points back to chalupa --help. A Taskfile action keeps the exit code of the action itself. Managed environments are chosen with --name ENV; --env is an alias of it.

Command reference

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.

Logs, diagnose and evidence

Three read-only verbs answer "what happened on the box?" without a hand-written SSH session. They need a running BYOC environment (managed GPU hosts have no Compose stack) and read it over SSH with the same identity and address as the tunnel. SSH never prompts here, so the box's host key must already be in your known_hosts (running chalupa tunnel once records it); otherwise the read fails with Host key verification failed instead of hanging.

There is no passthrough: each verb builds a fixed command from a short allowlist (journalctl -o json, docker compose logs, docker ps and an inspect limited to lifecycle facts, free, df, cloud-init status, failed units, Monitor's issues --json, and the recipes you declared). Nothing that changes the box can be expressed, container environments are never read, and lines are redacted best-effort before they reach your terminal or a file.

chalupa logs api worker --since 15m --level error
chalupa logs --box --since 1h --grep 'out of memory'
chalupa logs api --follow
chalupa logs box --since 20m

chalupa logs reads the box. It is not chalupa test logs, which prints this machine's own transcripts of a chalupa test run (provisioning, tunnel, results). T is 10m, 2h, now, an ISO 8601 instant or @epoch seconds; a time without a zone is UTC. Services that log to journald are read with journalctl; the rest with docker compose logs. --level is exact for the former and a text heuristic for the latter. --box adds the whole box's journal (warnings and above unless you pass --level). The service name box is not a Compose service: it reads the box's own systemd units (cloud-init's stages, chalupa-compose, chalupa-health, the image-cache mount and reset, overlays and replica-set units) with journalctl -u, at every severity unless you pass --level; it is the place to see why a boot was slow.

chalupa diagnose
chalupa diagnose --since-up --bundle ./diagnose-2026-10-01

diagnose is one bounded read: every container with markers for an OOM kill, restarts and non-zero exits, memory and swap, disk usage, cloud-init status, failed units, Monitor issues when observability.monitor is declared, and every recipe in diagnostics:. --since-up adds this boot's warnings and errors. --bundle DIR writes the report and the latest log lines to a new directory (mode 0700, files 0600) that stays on your machine.

chalupa evidence --last-failed --live
chalupa evidence --run-dir ~/.cairntrace/runs/2026-10-01T14-02-11-000Z_checkout_a1b2c3 --md --out evidence.md

evidence is the box side of a failed test run. It reads a cairn run directory without changing it (only run.json and events.ndjson are opened, so screenshots, network captures and traces never enter the brief), derives the window the run was alive plus or minus 30 seconds, and joins it with the box: containers with OOM and restart markers inside that window, error-first logs from every service and the box, host facts and your diagnostics. Markdown is the default, shaped like cairn's own agent context and kept under 16 KB; --json is the full document. --last-failed looks in the artifact root named by the cairn config in test.config, then ./runs beside chalupa.yml, then ~/.cairntrace/runs; --runs-root DIR overrides that.

By default evidence reads the box live when it answers and otherwise falls back, with a note, to the snapshot that chalupa down takes just before the sink. --live insists on a live read; --snapshot (or --no-live) stays offline. The snapshot is a bounded read (30 seconds at most, and it never delays the destroy) of containers, error-first logs and diagnostics, saved under ~/.local/state/chalupa/evidence/<environment>/. That is what lets you explain a failed round after the box is gone. The snapshot records which session took it, and evidence only joins a snapshot to a run from that same session, so a later box that reused the environment name is never presented as the box of an earlier run. Evidence stays local by default; nothing is uploaded.

Exit codes: 0 on success, 64 for a usage or config refusal, 69 when the box could not be reached.

Verbosity

Every action honours one verbosity control, spelled the same way on the CLI and on the bundled Taskfile:

A flag always wins over the environment; omitting both leaves the readable default. Verbose is exactly the historical firehose: Pulumi's own preview table and per-resource progress on data-up/up/down, and ci follow's raw chalupa-ci {...} NDJSON line per engine event. The default level captures Pulumi's transcript and prints resource counts, duration, warnings, and (for up/data-up) the ip/priceHourly/providerId or volumeName/volumeId outputs, instead of the whole thing; it renders ci follow's journal as one line per step — verdict, duration, and a running tally — instead of raw JSON. Quiet shortens a clean success further (a single line for Pulumi; passing steps go unprinted on ci follow, though the tally still counts them).

None of this changes what a failure shows: at every level, a failed pulumi up/down prints the complete transcript it always printed, in full, before the task exits non-zero. A diagnostic is never harder to reach than it was before this control existed.

status reports what the local Pulumi backend knows about two exact stack names. Compute is absent, empty, or present. Protected data is not-configured, absent, present, or unknown; configured states include the expected size from chalupa.yml, while a present state also includes the bounded local volume name and ID. The expected size is not a live provider capacity reading.

The read path does not select a stack, load a provider credential, or query DigitalOcean. An unexpected data stack, invalid outputs, inconsistent config, or failed read becomes unknown instead of being treated as absent. Local state can still be stale; the provider console and invoice remain authoritative.

Actions and confirmations

Only these public actions are accepted, whether they are typed directly or through chalupa run. The Actions screen shows the same set plus the bounded local-status and CI-status refreshes:

<environment> is the exact resolved environment name. Interactive up and down use a yes/no prompt, defaulting to No; select Yes or press y to continue. Escape, Ctrl-C, a closed terminal or No cancels. Other changing actions retain their exact typed phrase. For non-interactive use, the table lists the case-sensitive --confirm phrase; a mismatch refuses before Task.

Before each confirmation, Chalupa prints a target summary with the redacted canonical config path, exact compute stack, region, and size. data-up also shows the exact <environment>-data stack and configured expected GiB. down shows the protected-data stack and states that it survives.

For example:

chalupa up --config "$DEMO_CONFIG"

Every changing or long-running action requires an interactive terminal. preview and validate are the only actions available in synthetic mode and the only actions accepted outside a TTY. status --json remains available to non-interactive consumers when they supply an explicit config.

chalupa validate runs the full gate (typecheck, the test suite, preview and the CI plan). chalupa up and chalupa data-up run a lighter offline launch gate first: the config's Compose preview and CI plan. They skip Chalupa's own test suite. Set CHALUPA_STRICT_GATE=1 to make them run the full gate as well.

What --confirm actually is

chalupa ACTION --config PATH --confirm "<phrase>" supplies exact environment-bound authorization as a literal command-line argument — so a script, cron job, or another tool can run a billable or destructive action without a terminal attached. Be honest about what this buys you: it is friction against a human running the wrong command against the wrong environment, not authentication. The phrase is not a secret — it is deterministically derived from the resolved config's own name field ("launch " + config.name, "sink " + config.name, and so on), so anyone who can read chalupa.yml can compute it, and src/cli/chalupa.ts prints the exact expected phrase back on a mismatch (The supplied --confirm phrase does not match; expected exactly "...") — deliberately, because hiding it would only turn a typo into a support question instead of a stopped command. What --confirm actually enforces is that the target and the authorization are stated together, explicitly, in the one invocation that uses them (--confirm requires --config on the same command line; an inherited CONFIG does not count), so an automation's own config carries a phrase written once on purpose rather than a credential that could leak or be replayed against a different environment. See chalupa docs non-interactive for the complete rule set.

Sign in to the console

chalupa setup, chalupa login, chalupa open, and chalupa logout are the commands in this flow that reach the network; every other command stays offline until it delegates to Task. They link this workstation to the hosted control plane rather than to any specific environment.

For an ordinary customer account, use setup. It signs in or creates the tenant account used by billing and organization views:

chalupa setup
chalupa account --json                 # offline, with session tokens redacted
chalupa open
chalupa open billing
chalupa logout

The web sign-in form takes your email. Add your password if you have one; without a password, it emails a single-use code and asks you to enter it on the same form.

chalupa login is not the customer sign-in command. It is the separate, legacy operator-only device flow and requires an administrator to approve the displayed code on the console's Terminals page:

chalupa login --config ./chalupa.yml   # or --url https://chalupa.example

setup writes the verified tenant-account session to ~/.config/chalupa/account.json; this is the account used by chalupa account and chalupa open. login is a separate, legacy operator-only device flow. It writes a revocable terminal credential to session.json only after an administrator approves the displayed code. A tenant session in account.json never auto-approves that device flow or grants operator access. Both files have owner-only (0600) permissions. When the tenant account session is still valid, open exchanges it directly for a short-lived, one-use browser grant. open billing requests the billing destination from the same allowlisted endpoint. A stored credential is never sent to an origin different from the one that issued it.

account and the TUI's Hosted screen merge those files into a local, redacted status view without contacting Chalupa. The view can include cached plan and managed-hour fields, always marked fresh or stale; the hosted billing view is authoritative. Session tokens are deliberately absent from both text and JSON output. logout attempts to revoke both sessions and removes the local copies even when the control plane cannot be reached.

The stored credentials are scoped to hosted access, not to Chalupa's provider access: neither is the DigitalOcean token, neither is printed, both expire, and the terminal credential can be revoked early from Terminals in the console. --url selects the control-plane origin directly; without it, Chalupa falls back in order to CHALUPA_CLOUD_URL, then the selected config's cloud.url, then the origin from a valid setup account or a previous chalupa login on this machine (even if that terminal credential has expired — the origin it named is still meaningful), and finally to https://chalupa.run, the one production control plane, so a bare chalupa login on a fresh machine has somewhere to go. chalupa login prints which of the last two it used, since both are a guess rather than something you told it. Nothing about login changes what the Taskfile allowlist can do — it only lets open skip a manual sign-in.

Provider-bound sinking

Both surfaces bind down to the provider ID of the compute they most recently observed, and pass it to the Taskfile as a typed EXPECTED_PROVIDER_ID argument. The provider-scoped destroy task compares the current stack output with that value immediately before destruction and refuses a mismatch. Where they differ is what happens without a fresh binding.

The operator UI requires the operator to refresh status first: press r immediately before selecting Sink compute. The UI accepts only a present compute status observed within the last two minutes with a valid provider ID, and shows that ID in the target summary. Without that fresh observation, sinking stays disabled — the UI refuses rather than proceeding unbound. Chalupa also revalidates the same two-minute observation immediately after the confirmation; a prompt left open past the deadline is cancelled before Task starts and requires another status review.

Direct chalupa down captures its own fresh status immediately before running, with no separate refresh step required, and binds to the reported provider ID exactly as the UI does. When that capture fails, or the reported compute carries no provider ID, chalupa down proceeds anyway, bound only by the configured local stack identity, and prints a warning (Provider binding unavailable; down stays bound to the stack name only.) before it runs. It still requires interactive yes/no confirmation or the exact --confirm "sink <environment>" phrase and uses the normal compute-only Taskfile path. Prefer the UI when you want a missing binding to block the destroy instead of just being warned about it.

data-nuke is intentionally unavailable in the CLI and operator UI. Permanent data deletion remains an independent, explicitly confirmed Taskfile operation documented in Lifecycle. The one automated route is chalupa storage sweep for an environment that opted in with persist.onDemand, which destroys the data volume only after a snapshot is verified at the provider. Never reproduce it with direct Pulumi commands.

Navigate the operator UI

The interface follows the same deep-green and teal visual language as chalupa.run. It adapts to light and dark terminals, uses a bounded 256-color fallback, and returns to terminal-default styling when theme or color support cannot be established safely. Set NO_COLOR=1 to disable styling. Status, risk, selection, and availability always retain text markers, so color is never the only signal.

The full-screen interface requires a capable interactive terminal. When TERM=dumb, use the linear chalupa inspect and chalupa status commands and the direct actions instead; Chalupa will not force an alternate-screen UI onto that terminal.

The landing screen is Home, and it shows a session rather than a parsed configuration. A session is four separate observations, in order:

Each state carries its own observation and its own age. A state this laptop has not observed reads UNKNOWN; it is never inferred from a neighbouring one, and an observation older than two minutes reads STALE rather than as fact. Home also names exactly one next action — "Launch GPU to start a session", "Open agent", "Launch an agent", "Sink to stop billing" — so the interface has an answer to "what do I press now".

Which screens exist depends on what the configuration declares. An inference environment shows Home, Model, Actions, and Help. A Compose or CI environment shows Home, Preview, Status, CI, Actions, Hosted, and Help.

• Home — session state, cost, expiry, the endpoint an agent uses, and the primary actions.
• Model — the tunnelled endpoint: daemon version against the pin, installed or loaded state, digest, quantization, declared and loaded context, model ceiling, GPU placement, weight size, and the endpoint URLs an agent needs.
• Preview — the complete redacted remote Compose document.
• Status — independent compute and protected-data state from the local Pulumi backend.
• CI — the declared suite, bounded run state, connection state, and budget.
• Actions — the Taskfile allowlist, narrowed to the blocks this configuration declares, with risk classification.
• Hosted — the redacted local account/session cache and usage freshness; opening it never makes a network request.
• Help — safety boundaries, what each session state means, and the keyboard reference.

Home's primary actions are Launch GPU (up), Open agent, and Sink (down), plus Install expiry and Register expiry when the config declares a session: block. Open agent asks which agent to run and then runs exactly what chalupa launch runs: the UI suspends, the managed tunnel opens, the agent takes the terminal, and the agent's own settings are never modified. When the agent exits, the UI says what is true: the GPU is still running and still billed.

Every screen of an inference session carries the same chrome line: elapsed time, the hourly rate, the estimated cost so far, and how much of the declared session budget is left. Elapsed time is measured from the first moment this window observed the box — status:json carries no creation time — and it is labelled as an observation, not as uptime. Whether the local teardown scheduler actually holds this deployment is not something the UI reads, so it says armed state unknown and keeps a banner up: "Expiry is not armed. This GPU runs until you sink it."

Use these keys:

Long prose wraps at word boundaries, while long Compose values wrap by terminal cell width so the complete redacted plan remains inspectable. A ↳ marker identifies a visual Compose continuation and is not part of the source document. Scroll is bounded to real content. Narrow terminals use short tab labels and a focused action detail view; Page Up and Page Down reveal any remaining details. Terminals smaller than 40 columns by 12 rows show only a resize instruction instead of hiding controls or presenting a partial action.

The UI starts from local inspection only, so it opens offline and instantly. For a real configuration it then re-reads the session about every twenty seconds on its own: the bounded status:json read, and — when compute is present and the config declares inference: — one bounded loopback read of the forwarded Ollama. Automatic reads are quiet: they never move the screen, never claim the UI is busy, and a read that fails never replaces what is on screen, because a failed read is not evidence that anything changed. r remains available and refreshes immediately. In synthetic mode the UI displays SYNTHETIC OFFLINE DEMO, performs no automatic reads, disables status refresh, and disables every action except Preview and Validate.

The Actions screen lists only what the configuration can actually run: data-up without a persist: block, seed without a seed: command, ci: actions without a ci: block, and expiry registration without a session: block are hidden rather than shown as refusals. For everything still listed it explains why an operation is disabled before anything is delegated. Control-plane bootstrap and tunnels are available only when their corresponding declarative config exists. If a loaded local status proves compute is absent, bootstrap, tunnel, shell, seed, and expiry registration remain disabled; without a status observation, the UI labels them config-eligible and leaves runtime verification to the Taskfile. Provider actions require an explicit chalupa.yml; down additionally requires a fresh provider-bound status as described above. Compact mode keeps the selected action, risk, availability, and exact confirmation phrase in the focused view.

For an explicit config, the Status screen presents compute and protected data separately. An unknown data state remains visible with its bounded reason; the UI never collapses it into absent. A fresh present compute status with a provider ID also enables provider-bound sinking for two minutes.

For confirmations and foreground Task output, the UI temporarily returns terminal ownership to the command. A tunnel keeps ownership until its Task or SSH process exits. After a completed Task, press Enter to return to the UI. Starting a status refresh clears the previous observation immediately, and a failed refresh leaves it unknown. Running data-up, up, or down also invalidates the displayed observation, even when the Task fails, so a stale provider identity cannot keep a lifecycle action enabled. The status view shows the safe-down freshness deadline and repaints when it expires.

Recover from unknown state

If data-up, up, or down fails or is interrupted, do not immediately repeat it or assume that rollback succeeded. Resource state and billing may be unknown.

1. Run chalupa status --config "$DEMO_CONFIG" to inspect bounded local compute and protected-data state.
2. Verify the exact resource in the DigitalOcean console and check billing.
3. Re-run chalupa inspect --config "$DEMO_CONFIG" before choosing the next lifecycle action.

An absent local stack is not proof that the provider has no resource. A present protected-data state identifies bounded local outputs and the configured expected size, not live provider capacity or billing. Do not use data-nuke as recovery.

Taskfile and secret boundaries

The CLI passes a canonical config path to a fixed public Taskfile action. The Taskfile continues to own validation, the local Pulumi backend, tvault profiles, SSH, reporting, and separation of compute from persistent data. Do not call underscore-prefixed tasks or Pulumi lifecycle commands directly.

The CLI does not cache config history, persist secret values, or create a credential store. Tasks resolve their existing least-privilege tvault profiles only when the selected action needs them. The redacted preview and local Pulumi state can still contain private operational metadata; protect the workstation and state directory.

Continue with Quickstart, Lifecycle, Secrets with tvault, and Troubleshooting.

Remote inference

See Remote GPU inference for the experimental host-Ollama workflow. chalupa exec --format env --config PATH prints endpoint exports without changing files. See Agent harnesses for launch commands and configuration. setup --inference links the hosted account and writes a GPU starter with console heartbeats, then offers to arm the organization's console reaper so it can stop reported GPU deployments even when the laptop sleeps. --no-reaper-token skips arming. --no-console skips linking and omits cloud:, warning that expiry depends on this machine staying awake and unlocked.

Context per inference session

Use chalupa launch opencode --context auto to negotiate context on the existing remote GPU. --context 64k, 128k or native request a specific size or the model ceiling. See Inference for fit checks and limitations. The YAML and teardown identity are unchanged.

Managed telemetry bootstrap

chalupa up arms console telemetry after the managed host is ready. The success line is Telemetry armed: heartbeats, GPU samples and inference runs will appear in the console. Use chalupa session bootstrap [--config PATH] [--json] to retry delivery or rotate the environment's ingest key. tunnel and launch retry automatically when the managed record has bootstrapped: false (including older records without that field). JSON reports bootstrap state and the public key ID, never key material. See Managed GPU for signals and receipt limitations.