Skip to content

CLI reference

Version 0.9.4 exposes three top-level commands (version, doctor, status) and three command groups (auth, gateway, forge). Every command form in the sections that follow is accepted by the installed CLI. Forms listed under Not in 0.9.4 are refused as unknown commands.

Diagnostics

aegis version
aegis version --json
aegis doctor
aegis doctor --json
aegis status
aegis status --json

version prints the product name followed by the version 0.9.4. The JSON form prints {"version":"0.9.4"}.

doctor and status report value-free product diagnostics. In 0.9.4 they are wired to scaffold values: the human form prints the fixed line "aegis product scaffold: auth, gateway, and Forge are unavailable", and the JSON form returns product, status, journeys, active_profile and profiles. Both exit 0. A later release corrects the reported values while keeping these keys and this schema; they are not a live health check in either version.

Account

aegis auth login
aegis auth login --no-browser
aegis auth status
aegis auth logout

auth login prints aegis: sign-in URL: <url> and opens the browser unless --no-browser is given. The no-browser URL must be opened on the same host because the callback is a loopback address. auth status is human-readable and has no JSON form. auth logout prints local_authority: and remote_revocation: lines. See Account setup.

Gateway

aegis gateway enable --agent codex
aegis gateway status --agent claude
aegis gateway disable --agent codex

--agent is required and accepts codex or claude. enable requires a signed-in account, writes that agent's managed settings and prints aegis: gateway <agent> <outcome>. disable restores the changes the gateway owns and refuses when the user edited a managed value. status reports the recorded state. See Run agents.

Forge

aegis forge init
aegis forge init --json
aegis forge deploy
aegis forge deploy --repo OWNER/REPO --sha COMMIT --json

forge init validates or writes mithran.yaml in the current directory and uses no network. forge deploy resolves committed source from the current Git repository and requires a signed-in account. The default source is the GitHub origin and committed HEAD; --repo, --ref or --sha override it, and --ref and --sha cannot be combined. Success prints aegis: forge deploy accepted <deployment_ref>. See Configure your app and Deploy.

There is no forge status, forge versions or forge rollback command in 0.9.4, and no command that returns a deployment URL.

Global options

These are accepted by every command:

Option Meaning
--connection <name> Select a named connection profile.
--config <path> Select a different user-owned config file.
--agent-home <dir> Use an existing private alternate home for defaults and agent targets.
--state-dir <dir> Select the private state root explicitly. It never selects a profile.

The alternate home and explicit state root must be absolute, existing, effective-user-owned private directories with mode 0700 and trusted ancestry. --agent-home must also be disjoint from your account home. The config path must name a regular, effective-user-owned file with mode 0600, without symlinks and with trusted ancestry; it is not a directory. Ordinary use needs none of these options. See Account setup for the defaults and the state-path derivation.

Output and exit codes

Human-readable output goes to stdout; diagnostics and refusals go to stderr. --json is available on version, doctor, status, forge init and forge deploy. With forge deploy --json, typed structured source and deployment refusals print a value-free envelope on stdout and exit nonzero. Configuration, account and Auth failures instead use stderr with empty stdout. Invalid forge init requests also use stderr, including with --json. Human-readable refusals use stderr.

Exit Meaning
0 Success.
1 Launcher refusal, or most Forge service refusals.
2 The command line was refused by the parser.
64 Configuration or usage refusal, including unsafe paths, drifted settings, forge_intent_invalid and forge_source_unavailable.
66 A required input is missing, such as a bound account.
69 A journey or capability is unavailable in this build.
75 Temporary failure; retry after correcting the local condition.
77 Permission refused.

Most Forge refusals exit 1: forge_intent_drift, forge_preflight_unsupported, forge_preflight_refused, forge_preflight_stale, forge_result_unsupported and forge_result_binding_mismatch. Read the printed code, not the number alone. See Troubleshooting.

The npm launcher exits 1 with an aegis: <reason> line when the host, platform package or payload does not verify.

Not in 0.9.4

Do not use auth signin, auth status --json, a codex command group, a Nexus model flag, or any environment, tenant, account, installation or app selector. These forms were documented for an earlier surface and are refused by 0.9.4.