CLI

Selecting a chassis (--target)

Every command that talks to a chassis takes --target — the single flag for which chassis. It accepts, highest precedence first:

1. a workspace target from txco.yaml (targets: — also carries that env’s ops / mock policy)
2. a profile name — a “named chassis” carrying its own chassis_url and signing key
3. a raw admin URL (--target https://host:8081)

txco apply cloud                          # a profile (or txco.yaml target) named "cloud"
txco status --target staging
txco auth tenant secrets set OPENAI_KEY --target dev
txco apply --target https://chassis:8081  # a raw URL works too

On the deploy verbs (apply, push, status, diff) the target may also be a bare positional — txco apply staging. A path-like arg (., ./x, /x, or anything containing /) or an existing directory is taken as the workspace dir instead, so txco apply ./sub staging sets both. (txco push takes the stack first: txco push api staging.)

The mutating auth / tenant commands accept it as a trailing positional too — txco auth tenant secrets set OPENAI_KEY staging, txco auth tenant grant ACTOR staging. These are stdlib-flag-parsed, so any flags must come before the trailing target (secrets set NAME --tenant t staging, not … staging --tenant t).

--url / --addr (raw URL) and --profile (signing identity) still work as lower-level overrides — --target is just the one spelling unified across the deploy and auth / tenant families. With --target omitted, the active profile (after txco login) supplies the default; otherwise it’s http://localhost:8081.

Write-guard

A command that mutates a non-local chassis first prints the resolved target and asks to confirm — --yes skips it, and a non-interactive shell without --yes fails closed. So a stray secrets set / hostnames add can’t silently land on prod. Local chassis (localhost / loopback / *.localhost) never prompt.

Local dev: no key required

Against a local chassis (localhost / loopback / *.localhost — e.g. the txco dev chassis), auth / tenant commands don’t need an enrolled signing key: they send unsigned and the open dev chassis accepts. So txco auth tenant secrets set OPENAI_KEY just works locally with no bootstrap-local. A remote chassis still requires enrollment; a local chassis running in signed mode returns a clear 401.

To save the repetition, txco dev auto-registers a dev profile pointing at the chassis it just started (with default_tenant: default), so you can use the named selector everywhere instead of spelling out the URL + tenant:

txco apply dev                              # deploy to the dev chassis
txco auth tenant secrets set SHH_KEY dev # set a secret on it (tenant: default)
txco ui dev                                 # open the dev admin UI

Run & develop

Command	What it does
txco serve	Boot the chassis (runtime reference)
txco dev	The dev loop: boots your txco.yaml apps + an ephemeral chassis, watches OPS/*.txcl and compute .js/.ts files, re-applies on save. Registers a keyless dev profile for the chassis. --ui adds the admin-UI Vite server; --tcp / --dns add those heads
txco demo	Ephemeral chassis + browser playground with a guided curriculum (build/web/mail/async/mcp tracks)
txco init <stack>	Scaffold OPS/<stack>/…; --from github:…\|oci:…\|dir:… scaffolds from a template
txco doctor	Diagnose local setup: home dir, profile, keys, chassis reachability, version sync (--offline skips remote checks)

Deploy & versions

Stacks change through versioned drafts (admin-api). The CLI verbs map onto that flow:

Command	What it does
txco apply [dir]	Deploy the whole OPS/ tree: draft + activate per changed stack; resolves op:// refs; uploads computes
txco push <stack>	Like apply, one stack
txco pull <stack>	Materialize a stack’s active version (or --version N) into local OPS/<stack>/ — the inverse of push
txco draft <stack>	Upload a draft without activating (stage for review); --activate flips it too
txco activate <stack>	Flip the active-version pointer (defaults to newest draft). Activating an older version = rollback
txco versions <stack>	List a stack’s versions, active one marked
txco diff [dir]	Compare local OPS/ against the running chassis
txco lint [dir]	Validate the OPS/ tree offline (no chassis): name collisions, mis-placed files, txcl parse, unconditional-loop warnings; --list prints the op graph; exit 1 on errors (CI-friendly)
txco status [dir]	Per-stack drift summary; exit 1 on divergence (CI-friendly)
txco edit <stack> <path>	$EDITOR one file of a draft, PATCH it back

Nano-ops

Command	What it does
txco op init <path>	Scaffold a .js/.ts compute next to its rule
txco op build <path>	Bundle + compile to wasm (auto-fetches the pinned javy)
txco op run <path> --input <json\|@file>	Execute locally on the same engine production uses
txco op test <path>	Run against the scope’s mock-request.json, diff vs mock-response.json

Packages

txco install <ref> --as <stack>, txco package {init,validate,inspect,pull,publish,key,list,upgrade,remove} — see packages.

Identity & access

Command	What it does
txco auth bootstrap-local	First-run: generate a key + enroll it (admin-api)
txco auth init / enroll / rotate-key / revoke-key / revoke-actor	Key lifecycle
txco auth whoami (alias txco whoami)	What the chassis thinks you are
txco auth invite / invitations / revoke-invitation / accept --token …	Teammate onboarding
txco auth profiles / profile {use,show,remove} (alias txco use <profile>)	Named identities; also aliased under txco config
txco auth tenants / tenant {create,members,grant,revoke}	Tenant management
txco auth tenant hostnames {add,attach,verify,challenge,list,remove}	Hostname bindings (ingress)
txco auth tenant secrets {set,generate,list,show,describe,rotate,revoke}	(Secret store)
txco auth login (alias txco ui)	Mint a signed browser session, open the admin UI
txco auth sessions {list,revoke} / logout	Browser sessions / stop signing
txco login / logout / cloud {…}	Cloud account OAuth — distinct from auth login, which targets your own chassis

Diagnose

Command	What it does
txco trace [rid\|last]	Step-by-step trace explorer (trace); bare txco trace is interactive
txco mcp doctor <url>	Probe an MCP server: handshake + tool list (mcp)

Operator & misc

Command	What it does
txco admin resync --tenant <slug>	Re-emit control-plane state to the fleet (super-admin)
txco admin tenant {suspend,resume}	Tenant kill switch (super-admin)
txco snapshot {export,restore,publish}	Runtime-DB snapshots for fleet bootstrap
txco dns {zone,record,config,render}	Delegated DNS zones (requires the dns personality)
txco cron config {show,set}	The tenant’s cron timezone — set timezone <IANA zone> localizes @cron.* (default UTC)
txco version / update check / upgrade	Version info / check / self-update
txco completion <shell>	bash/zsh/fish completion script
txco plugin	List external txco-<name> plugins (kubectl convention)