CLI reference

Binary: pytxo. This page describes 1.3.6.

Since 1.3 the CLI covers the whole loop: pytxo review and pytxo apply use the same reviewed-Apply path as Desktop, and pytxo land checks branches from any agent tool. pytxo hitl is the Galaxy approval queue, not Apply.

Default behavior

pytxo          # interactive Hypervisor Shell (TUI)
pytxo --help   # subcommand list

Set PYTXO_NO_TUI=1 to print help instead of launching the shell.

Commands

Command	Description
`pytxo land <branch>...`	Check agent branches as one combined change; land it with `--apply` (guide)
`pytxo review <run>`	Show a finished run's prepared change, checks and digest; `--refresh`, `--discard`
`pytxo apply <run>`	Write exactly the reviewed files; refused if anything moved
`pytxo receipts`	List, show and share landing and Apply receipts (receipts)
`pytxo bench`	Pybench: offline benchmarks of the landing gate (method)
`pytxo login` / `logout` / `whoami`	Optional account for perks (account)
`pytxo init`	Create `.pytxo/` dirs and gitignore hint
`pytxo doctor`	Verify git, PTY, approvals persistence, billing/cloud when enabled
`pytxo run`	Schedule and execute agents in isolated copies
`pytxo mission`	Natural-language mission: plan → approve → isolated run → review package
`pytxo agents`	List registered agent CLIs and PATH detection
`pytxo accounts`	Several sign-ins per agent CLI (Claude Code, Codex) and which one new work uses
`pytxo shell`	One-shot shell without the TUI (`--eval`)
`pytxo status`	List runs and agents from SQLite
`pytxo logs --agent <id>`	Tail stored stdout/stderr events
`pytxo stop`	Stop active run or all tracked processes
`pytxo domains`	List registered execution domains
`pytxo project`	Multi-root modular project manifest
`pytxo fleet`	Cross-repo fleet DAG
`pytxo hitl`	Galaxy human-in-the-loop approval queue (risky commands; not Apply)
`pytxo trust [tier]`	Trust repo folder (`orbit`, `galaxy`, ...)
`pytxo providers`	Provider registry + key configured (boolean)
`pytxo models`	List, search, or refresh model catalog

Shared flags

Flag	Commands	Description
`--repo`	most	Git repository root (default: cwd)
`--config`	`run`, `status`, `logs`, `stop`, `shell`	Path to `pytxo.toml`
`--json`	`doctor`, `status`, `domains`, `mission`, `agents`	Machine-readable output

`pytxo review` and `pytxo apply`

pytxo review <run-id>                 # files, checks on the combined change, digest
pytxo apply <run-id> --digest <sha>   # apply exactly that package
pytxo apply <run-id>                  # shows the package and asks before applying
pytxo review <run-id> --refresh       # re-prepare a stale review
pytxo review <run-id> --discard       # drop it; nothing is written

Apply authorizes the digest you were shown, never "whatever is latest". If the project changed after review, Apply refuses; refresh and review again. Every committed Apply writes a receipt.

`pytxo land`

Flag	Description
`-c`, `--check <cmd>`	Command to run on the combined change (repeatable)
`--per-input`	Also run the checks on each input alone
`--apply`	Land a ready result (fast-forward or compare-and-swap)
`--into <branch>`	Target branch (default: checked-out branch)
`--base <rev>`	Check against another commit (shadow mode only)
`--strict`	Block when two inputs changed the same function or type
`--timeout <s>`	Per-check timeout (default 900)
`--json`, `--markdown`	Full receipt, or a pull-request summary

Exit codes: 0 ready or landed, 2 blocked, 3 stale.

`pytxo bench`

Flag	Description
`--suite <name>`	`land`, `overhead`, `signal` or `all` (default)
`--out <file>`	Write the JSON report
`--json`	Print the JSON report
`--submit`	Publish the summary to the Pybench board (account perk)
`--private`	With `--submit`: save the result to your account only, off the board (Pytxo Pro)

`pytxo receipts`

Command	Description
`pytxo receipts`	List this repository's receipts, newest first (`--json` for machine output)
`pytxo receipts show <id>`	Print one receipt (full id or unique prefix) and check its digest
`pytxo receipts share <id>`	Publish counts and outcomes as a page (account perk)
`pytxo receipts share <id> --include-paths`	Also publish the changed file paths
`pytxo receipts share <id> --private`	Only you can open the page, signed in (Pytxo Pro)

`pytxo mission`

pytxo mission "Add input validation in src/api.ts"
pytxo mission "…" --yes          # skip interactive plan approve
pytxo mission "…" --json         # print plan JSON; no dispatch
pytxo mission "…" --ade claude   # preferred ADE id

--plan-file writes plan JSON before the approve step. After a successful Orbit or Galaxy run, review and Apply in Desktop — not with a CLI apply subcommand. See Review and Apply.

`pytxo agents`

Lists ADE CLIs from the registry and whether they are on PATH. --json for scripts.

`pytxo accounts`

Keep more than one sign-in for an agent CLI, such as a work and a personal Claude account. Each account is the CLI's own config folder under ~/.pytxo/agent-accounts/<cli>/<name>/, selected for each launch through the variable the vendor documents (CLAUDE_CONFIG_DIR, CODEX_HOME). Sign-in runs the vendor's own command; Pytxo never reads or copies the credentials it writes. default is the CLI's usual sign-in.

pytxo accounts list            # every account and its sign-in state
pytxo accounts add claude work # creates the folder, opens Claude Code sign-in
pytxo accounts use claude work # new work on Claude Code uses this account
pytxo accounts login codex     # sign the default Codex account in again
pytxo accounts remove claude work

A configured agent can pin an account in pytxo.toml with account = "work". Desktop shows the same accounts under Setup → Agent CLIs. Cursor Agent, Antigravity and Gemini CLI keep one sign-in per OS user, so they have no accounts list.

Every account must be yours. Provider terms forbid sharing an account and working around usage limits, so Pytxo never switches accounts on its own when one reports a limit; it tells you which account hit it.

`pytxo shell`

One-shot command without the Hypervisor Shell:

pytxo shell --eval "/dry-run"

`pytxo run` flags

Flag	Default	Description
`--agents`	`3`	Max parallel agents per wave
`--cmd`	`echo pytxo`	Shell command in each isolated copy
`--dry-run`	off	Print JSON execution plan
`--keep-worktrees`	off	Do not remove isolated copies after run
`--execution`	from config	Override `pty`, `subprocess`, or `cloud`
`--ade`	unset	Registry ADE id (e.g. `cursor`, `claude`)

`pytxo project` subcommands

Subcommand	Description
`init <id>`	Create project manifest under `~/.pytxo/projects/`
`list`	List path roots for a project
`paths --add <path>`	Add a path root
`remove`	Remove a path root (by label or path)
`status`	Recent runs for the project primary domain
`run`	Coordinated run across project roots

`pytxo fleet` subcommands

Subcommand	Description
`init <id>`	Create fleet manifest under `~/.pytxo/fleets/`
`dry-run`	Print fleet execution plan JSON
`run`	Run fleet DAG with barrier sync
`status`	List fleet runs from hypervisor catalog

pytxo fleet run --continue-on-error continues later waves after a node failure.

`pytxo hitl` subcommands

Galaxy's approval queue for risky host actions. Approving a HITL request is not repository Apply.

Subcommand	Description
`list`	Pending approval requests
`approve <id>`	Approve a request
`deny <id>`	Deny a request

See Galaxy approvals and Review and Apply.

`pytxo trust`

pytxo trust orbit
pytxo trust galaxy --repo /path/to/repo

Tiers: deep_space, orbit, galaxy, supernova. See Permission tiers.

Environment variables

Variable	Purpose
`PYTXO_NO_TUI`	Skip Hypervisor Shell; print help or run subcommands only
`PYTXO_REPO`	Default git root (useful for MCP)
`PYTXO_PLANNER`	Enable natural-language mission planner (`1`)
`PYTXO_ULTRA_SESSION`	Bearer token for Ultra / Link reconcile when `billing.mode = ultra`
`PYTXO_CLOUD_SESSION`	Bearer token for cloud execution when enabled
`PYTXO_DEEPSPACE_WFP`	Windows DeepSpace WFP opt-in (`1`)

Provider API keys stay in their usual env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, ...). See Providers & BYOK.

Doctor checklist

pytxo doctor should pass before first real runs. Details: Doctor checks.

Agent IDs

Format: {run_uuid}:agent-N. Use with pytxo logs --agent.

On this page