X4 CLI Command Reference

The x4 CLI is implemented in src/cli.ts. The current top-level commands are:

Command	Purpose
x4 doctor	Validate local, host, devbox, worker, control, and agent prerequisites.
x4 registry	Generate starter registry files and validate registry files.
x4 bootstrap	Compatibility alias for workspace bootstrap.
x4 status	Show workspace status.
x4 cleanup	Clean generated worktrees, branches, and artifacts.
x4 test	Run registry test commands per repo.
x4 env	Validate and install env bundle contracts.
x4 codex	Codex integration aliases.
x4 workspace	Workspace bootstrap, status, test, commit, cleanup.
x4 agents	Agent integration helpers.
x4 branch	Multi-repo branch helpers.
x4 feature	Feature naming and branch rename helpers.
x4 learn	Learning log helpers.
x4 ai	AI provider checks, sandbox planning prompts, and reviewed sandbox profile generation.
x4 sandbox	Sandbox startup, wait, status, logs, down, destroy, and host-level clear.
x4 preview	Tailnet-only preview preparation and serve routes.
x4 pr	PR plan/create/comment/check-run helpers.
x4 workflow	End-to-end PR and smoke workflows.
x4 issue	Linked issue creation and evidence comments.
x4 infra	Infrastructure plan output.
x4 remote	Remote execution plan and direct remote tests.
x4 control	Control-plane leases, workers, submissions, GC, and tests.
x4 github	GitHub App validation, poller, and /x4 command execution.
x4 changelog	Deployed changelog registry, artifact, backfill, review, polish, and workflow helpers.
x4 orchestration	Repo-local orchestration policy helpers.

Help

Every command supports --help:

x4 --help
x4 workspace --help
x4 control submit test --help

Common Options

Option	Used by	Meaning
--entry <path>	Most workspace commands	Workspace entry repo path.
--registry <path>	Registry/workspace commands	Override registry file.
--repo-set <id>	Bootstrap/poller commands	Select a repo set.
--install <mode>	Bootstrap/remote/control commands	eager or skip.
--git-auth <mode>	Bootstrap/remote commands	none or app.
--github-app-env <path>	GitHub commands	GitHub App credential env file.
--dry-run	Mutating workflows	Print intended actions without applying.
--execute	Remote/GitHub workflows	Perform the planned mutation.

Registry Generation

Generate a starter registry from local Git checkouts:

x4 registry init \
  --repo ~/dev/repos/app \
  --repo ~/dev/repos/api \
  --repo-set current-work \
  --output ~/dev/x4/current-work.registry.yaml \
  --install skip

The generated file is a reviewable starting point. It infers repo ids, remotes, default branches, package-manager setup commands, basic test commands, env allowlists, an env bundle placeholder, and a metadata-only sandbox profile.

Safety Defaults

• Mutating GitHub and remote-control commands usually default to dry-run or planning mode.
• Preview comments refuse local-only URLs.
• Cleanup dry-run is recommended before force cleanup.
• Env commands validate key names without printing secret values.
• x4 sandbox clear requires --all and either --dry-run or --force; it only targets X4-labeled sandbox resources.
• x4 sandbox status reconciles saved service-sandbox state against X4-labeled Docker containers before showing preview links as live.
• x4 sandbox run "<goal>" is the preferred interactive sandbox path: it writes a harness goal under .x4/ai/runs/, asks the selected AI engine to propose a sandbox profile for the current workspace goal, validates the profile, and only then runs deterministic sandbox startup. If startup fails, it retries with AI repair feedback up to --ai-attempts times, defaulting to 3.
• x4 sandbox up --ai is the lower-level experimental shortcut when a script already knows the exact profile to prepare before startup.
• Use AI only where discovery is the hard part, such as inferring sandbox service commands, ports, routes, and health paths. Keep workspace creation, registry validation, env filtering, cleanup, and PR operations deterministic.