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¶
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.