CLI reference¶

Use aegis for account setup and local readiness checks. Use map for Forge repo onboarding, deploy requests, deploy status, evidence, publishing, and app access. This page covers the customer-facing command surface and the behavior you need when operating a deploy.

Terminology note: Forge is the product name. map is the deploy-related command namespace. Keep using the command names shown here; see the Glossary for the Forge/MAP naming split.

Command map¶

Goal	Command	Control-plane request?	Notes
Save map-control login	`map login save --map-control-endpoint <url> --access-token <token>`	no	Writes local CLI login state.
Print saved token	`map login print-token --audience <audience>`	no	Prints the saved bearer token only when the saved audience or scopes allow that audience.
Inspect saved login	`map whoami`	no	Prints the saved endpoint and principal metadata.
Create a starter manifest	`map init`	no	Writes a starter `mithran.yaml` only if the target file does not exist.
Register a repo	`map onboard --installation-ref <ref> <owner/repo> --repo-dir .`	yes	Writes starter files locally only when needed.
Validate target flags	`map validate --repo <owner/repo> --ref <git-ref>`	no	Checks target shape before a request.
Request a deploy directly	`map deploy --repo <owner/repo> --env production --ref <git-ref> --installation-ref <installation-ref>`	yes	Use webhooks for built-in deploy refs.
Check readiness	`map doctor --app <owner/repo>`	yes	Reads control-plane config and route status.
Watch a deploy	`map watch <deployment-ref>`	yes	Exits non-zero for terminal failure states.
Read evidence	`map --json evidence <deployment-ref>`	yes	Use when status alone does not explain a failure.
List versions	`map versions <app>`	yes	Shows internal versions, aliases, and the published clean URL.
Publish a version	`map publish <app> --version <version> --expected-sha <sha>`	yes	Moves the clean public URL only when the reviewed SHA still matches.
Start a canary	`map canary start <app> --deployment-ref <ref> --weight <1-99>`	yes	Splits the target deployment's app-environment alias between current and canary deployments.
Promote or roll back a canary	`map canary promote <app> --deployment-ref <ref>` / `map canary rollback <app> --deployment-ref <ref>`	yes	Clears the active canary split by promoting or rolling back.
Plan access	`map access plan --repo-dir .`	no	Resolves `access.yaml` and CLI overrides.
Apply access	`map access apply --repo-dir .`	yes	Writes the resolved app access policy.
Print CLI version	`map version`	no	Prints the installed `map-cli` version.

Output and exit behavior¶

Generic control-plane read/write commands print a returned deployment_ref when the response includes one. Use that ref with map --json status, map watch, and map --json evidence.

Add --json when automation needs the full response body. Without --json, commands print compact text such as ok, a deployment ref, a version list, or the published hostname.

map watch prints each observed deploy phase. It exits successfully only when the deploy reaches Succeeded. It exits non-zero when the deploy reaches ReviewBlocked, BuildFailed, RuntimeFailed, RouteFailed, Failed, RolledBack, or Superseded, when the control plane returns a non-success HTTP response, or when the watch times out.

Saves or reads the local map-control login state used by map commands.

map login save --map-control-endpoint <url> --access-token <token>
map login print-token --audience <audience>

Flag	Meaning
`--map-control-endpoint <url>`	Control-plane endpoint to save.
`--access-token <token>`	Bearer token to save.
`--jason-controller-endpoint <url>`	Optional Jason controller endpoint.
`--audience <audience>`	Saved token audience; defaults to `map-control` for `save` and is required for `print-token`.
`--scope <scope[,scope]>`	Optional comma-separated saved scopes.
`--expires-at <timestamp>`	Optional token expiry timestamp.
`--email <email>`	Optional principal email to record.
`--name <name>`	Optional principal display name to record.

map login print-token writes the saved bearer token to stdout. It succeeds only when the saved login audience matches --audience, the saved scopes include map:*, or the saved scopes include audience:<audience>. Treat the output as a secret and use it only for local automation that cannot call map directly.

map whoami¶

Prints the saved control-plane endpoint, token audience, scopes, and principal metadata. It does not call the control plane.

map whoami
map --json whoami

map init¶

Creates a starter mithran.yaml only when the target file does not already exist.

map init
map init --manifest path/to/mithran.yaml

The generated file is a map.mithran/v1 MithranApp skeleton for a basic HTTP service. It uses metadata.app_id: example, identity.project_ref: app:example, runtime: nodejs22, and startup.command: npm start.

Treat it as a starting point. Review the app ID, project/app ref, runtime, startup command, exposure, and app-environment policy before deploying.

aegis setup¶

Signs you into Mithran and prepares local profile state (managed hooks and config). Protected-worker launch requires signed-in Mithran access, the codex CLI, Lima with limactl, and completed aegis setup. GitHub access is not required to run an agent. Run setup once per machine; it is safe to re-run.

aegis setup

GitHub is requested reactively when you deploy or push, not by setup. Use aegis github status --project-repo <owner/repo> --require --json when you need repo-scoped grant evidence at deploy time.

Run agents (aegis codex / aegis claude)¶

Run a coding agent inside the protected runtime. The shape is aegis [aegis options] <agent> [agent arguments]: the agent token is a hard boundary, and Aegis adds no sub-commands beneath it. Aegis options — including --method-gates, Aegis's control for the agent — go before the agent token; the agent's own arguments follow and pass through unchanged. See Run agents with Aegis for the full guide.

aegis codex "<task>"                                 # run Codex, protected
aegis claude "<task>"                                # run Claude Code, protected by default
aegis --method-gates enforce claude "<task>"         # enforce the Aegis Method as a gate

--method-gates selects off, advise (guidance), or enforce (deterministic gate). Protected-worker launch requires signed-in Mithran access, the codex CLI, Lima with limactl, and completed aegis setup. GitHub is not needed to run an agent; it remains a separate deploy-time step.

Related commands:

aegis session status|stream|steer|interrupt|stop <id>   # manage a protected session
aegis hooks install --target <codex|claude|git-pre-push>  # install managed hooks
aegis probe-capability --agent <codex|claude> --model <m> --budget <n>  # capability probe

aegis doctor¶

Reports local setup readiness, session state, and the workspace-scoped GitHub App grant when the current directory is a GitHub-backed checkout. Add --json for machine-readable output.

aegis doctor --json

The JSON report contains a version_inventory object with these fields:

Field	Shape and meaning
`schema_version`	Always `aegis.doctor.version_inventory.v0`.
`entry_count`	Number of objects in `entries`.
`status_counts`	Counts grouped by entry status: `installed`, `unknown`, or `not_installed`.
`entries`	Version-inventory entry objects.

Each entry has these base fields: name, display_name, kind, status, version, command, source, and message. Conditional fields are:

command_available for command and dependency entries;
dependency_name for dependency entries;
component for component-manifest entries;
records for the product entry and manifest-backed entries;
record_count, available_record_count, and missing_record_count for manifest-backed entries;
commands for manifest-backed entries.

Entries cover Aegis, Aegis Method, Map, Jason, Codex, and Lima. The version field reports the value discovered at runtime or unknown; this reference does not invent version values.

map onboard¶

Registers a repo and GitHub App installation with the control plane for source access. With --repo-dir, it writes a starter mithran.yaml only when the file is missing. The default path uses GitHub App webhooks and does not add a repo workflow.

map onboard --installation-ref <installation-ref> <owner/repo> [flags]

Flag	Meaning
`--installation-ref <ref>`	Required GitHub App installation ref authorizing the repo.
`--repo-dir <path>`	Where to write starter files (use `.` in a checkout).
`--tenant-ref <ref>`	Tenant the app belongs to.
`--account-ref <ref>`	Account the app belongs to.
`--app-ref <ref>`	Served app ref for the self-service path. Visible alias for `--project-ref`.
`--project-ref <ref>`	Project/app ref. Defaults to `app:<repo-name>`. In the self-service path, use the served app ref you will pass to `map versions` and `map publish`.
`--with-ci-workflow`	Also scaffold the optional GitHub Actions custom-CI workflow.
`--workflow <name>`	Workflow filename used with `--with-ci-workflow`. Defaults to `map-deploy.yml`.

When --with-ci-workflow is set with --repo-dir, the CLI writes .github/workflows/map-deploy.yml and tries to set the non-secret repo Variables it can derive: MAP_INSTALLATION_REF, MAP_APP_REF, MAP_TENANT_REF, and MAP_ACCOUNT_REF when the corresponding refs are available. MAP_APP_REF is the resolved --app-ref or --project-ref value passed as app_ref to the deploy request. The workflow also requires account setup repo Variables for MAP_CONTROL_ENDPOINT and MAP_AUTH_ENDPOINT. MAP_OIDC_AUDIENCE is optional and defaults to map-control. If the GitHub API update cannot run, onboarding still reports the variable names so an admin can set them manually.

In the generated workflow, pushes to release/** branches and tags matching v[0-9]+.[0-9]+.[0-9]+ request the production app environment. Manual workflow_dispatch input env becomes the app environment sent to /v1/map-control/deploy/request. The account context comes from the customer setup endpoint, GitHub App installation, and optional tenant/account refs; it is not derived from the workflow env input.

If onboarding returns an API error, re-check the repo slug, installation ref, setup context, project/app ref, and GitHub App grant before retrying.

map validate¶

Validates a deploy target shape locally. It does not call the control plane. The CLI requires --repo plus either --ref or --sha; --env names the app environment when you need to validate one.

map validate --repo <owner/repo> --env production --ref refs/heads/release/v1

Flag	Meaning
`--repo <owner/repo>`	Required target repo.
`--env <env>`	Optional app environment, such as `preview` or `production`.
`--ref <git-ref>`	Git ref to validate. Required unless `--sha` is provided. Conflicts with `--sha`.
`--sha <40-hex-sha>`	40-character source SHA to validate. Required unless `--ref` is provided. Conflicts with `--ref`.

map validate does not prove that a repo is granted to the Forge GitHub App, onboarded, buildable, or deployable. It only checks that the local target arguments are internally valid.

map deploy¶

Posts a deploy request directly to the control plane. Use the GitHub App webhook path for built-in deploy refs.

map deploy --repo <owner/repo> --env production --ref <git-ref> --installation-ref <installation-ref>

Flag	Meaning
`--repo <owner/repo>`	Required target repo.
`--env <env>`	Target app environment, such as `preview` or `production`. When omitted, the direct deploy request targets `preview`.
`--ref <git-ref>`	Git ref to deploy. Required unless `--sha` is provided. Conflicts with `--sha`.
`--sha <40-hex-sha>`	40-character source SHA to deploy. Required unless `--ref` is provided. Conflicts with `--ref`.
`--installation-ref <ref>`	GitHub App installation ref authorizing source fetch. Provide this for real repo deploys.
`--app-ref <ref>`	App ref, such as `app:inventory-portal`.
`--tenant-ref <ref>`	Tenant ref for the deploy request.
`--account-ref <ref>`	Account ref for the deploy request.
`--deployment-ref <ref>`	Explicit deployment ref. Forge mints one when omitted.
`--evidence-ref <ref>`	Evidence ref to attach to the deploy request.

map deploy-request is the explicit alias for the same direct control-plane request. It is useful from automation that should not rely on GitHub webhook triggers.

--env selects an app environment. It does not change the customer account context, GitHub App, endpoint, or hostname pattern. See Account context and app environments.

If --repo is owner/repo, the CLI sends github://owner/repo to the control plane. If --repo already contains ://, the CLI sends it as provided.

For real repo deploys, pass the GitHub App --installation-ref used during onboarding. Missing or wrong installation refs fail during source fetch.

Successful text output prints the deployment ref when the control plane returns one:

deployment://<account-context>/<app-env>/<id>

With --json, the CLI prints the full response body unchanged. Keep deployment_ref, deployment, evidence, and remote_authority when those fields are present.

map doctor¶

Runs readiness checks against the saved control-plane endpoint. Use --app when you also want app-specific diagnostics.

map doctor
map doctor --app <owner/repo>

Flag	Meaning
`--app <owner/repo>`	Also diagnose a specific app/repo registration and recent deployment state.

map doctor checks whether the control-plane endpoint is configured and reachable, whether source access is configured, and whether source-access records exist. With --app, it also looks for recorded deployments or route aliases that mention the repo/app. The control-plane config endpoint exposes counts, not the full repository list, so a warning can mean the CLI cannot prove repo-specific access from public diagnostics.

map status¶

Fetches status for an ID returned by the control plane.

map --json status <id>

Use the deployment_ref from a direct deploy response, deploy status, or deploy evidence. The command reads /v1/map-control/deploy/status?deployment_ref=<id>.

The JSON response is a saved service deploy record. The deploy status view is under deployment.status, and the phase is deployment.status.status. Without --json, a successful generic status read prints ok.

map watch¶

Polls status for an ID.

map watch <id>

Flag	Meaning
`--interval-seconds <seconds>`	Poll interval. Defaults to `5`.
`--timeout-seconds <seconds>`	Watch timeout. Defaults to `120`.

Use map watch in scripts when a non-zero exit should stop the release path on terminal deploy failure, a control-plane API error, or timeout.

map evidence¶

Fetches evidence for an ID.

map --json evidence <id>

Use evidence when the status phase tells you where the deploy failed but not enough about why. Build, runtime, route, smoke, and review diagnostics are attached to the deploy evidence when available.

Without --json, a successful generic evidence read prints ok.

map logs¶

map logs <deployment-ref> is not the supported investigation source for Forge deploys. Use deploy status and evidence instead.

Use:

map --json status <deployment-ref>
map --json evidence <deployment-ref>

map publish¶

Points an app's clean public URL at a reviewed version that reached Succeeded or Promoted. Deploying a version and publishing it to the public host are separate steps, so you can deploy, check, then publish.

map publish <app> --version <version>

Use map versions <app> to list internal versions, app-environment aliases, and the clean public URL's published record.

Flag	Meaning
`--version <version>`	Internal version label to publish. Pick it from `map versions <app>`.
`--deployment-ref <ref>`	Explicit deployment ref to publish instead of resolving a version label.
`--expected-sha <sha>`	Guardrail: publish only if the version still records this exact source SHA.
`--actor <actor-ref>`	Actor ref to attribute the publish to. Forge defaults one when omitted.

Use --expected-sha when a human reviewed a specific commit. It prevents the clean public URL from moving unless the requested version records that exact source SHA.

Use --deployment-ref when the release evidence names the deployment ref instead of a version label. It skips the map versions label lookup.

For the publish workflow, including moving the clean public URL back to a previous reviewed version, see Versions and publishing.

Publish failures are deliberately specific:

Failure	What it means
Missing `--version` and `--deployment-ref`	Pick one target to publish.
Version label not found	Run `map versions <app>` and copy a label from `internal versions`.
Not publishable	The deployment did not reach `Succeeded` or `Promoted`.
Stale expected SHA	The selected version does not record the SHA passed with `--expected-sha`.

map canary¶

Starts, promotes, or rolls back a weighted canary on the app-environment alias for the named deployment. Canary does not move the clean public URL; use map publish for that.

map canary start <app> --deployment-ref <deployment-ref> --weight 20
map canary promote <app> --deployment-ref <deployment-ref>
map canary rollback <app> --deployment-ref <deployment-ref>

Command	Meaning
`start`	Sends `--weight` percent of the target app-environment alias to the named canary deployment. `--weight` must be 1 through 99.
`promote`	Finds the active canary split for the named deployment's app-environment alias, makes the canary deployment current, and clears the split.
`rollback`	Finds the active canary split for the named deployment's app-environment alias, clears the split, and keeps the current deployment at 100 percent.

<app> can be the short app name, such as inventory-portal, or a literal app: ref. For start, the named canary deployment must have reached Succeeded or Promoted. For promote and rollback, pass a deployment ref from the active canary alias; the canary deployment ref returned by start is the clearest choice. Text output reports the requested app/app ref, returned alias app ref, mismatch status, canary deployment ref, alias or hostname when returned, current deployment ref, active canary, and result. In text mode the CLI exits non-zero when the returned alias app ref does not match the requested app. With --json, the CLI prints the server response unchanged.

Use JSON output for release evidence:

map --json canary start <app> --deployment-ref <deployment-ref> --weight 20

The JSON response includes the action status and the alias object returned by Forge. Treat that alias as the source of truth for the app, app environment, current deployment, canary deployment, and canary weight. When a split is active, the alias contains the canary deployment ref and canary weight. Promote and rollback responses should show the split cleared.

Use map versions <app> to inspect current canary state after the action. Text output should show alias_app_mismatch: no before you treat the canary action as complete. map versions appends an active split to the alias line:

production (CanaryWeight)  ->  <current-deployment-ref>  <alias-hostname>  [canary <canary-deployment-ref> 20%]

With --json, alias entries include canary_deployment_ref and canary_weight_pct when a split is active. Verify canary behavior against the alias hostname returned by map canary or shown by map versions; publish is the separate operation that controls the clean public URL.

map versions¶

Lists an app's internal versions, app-environment aliases, and the version published to the clean public URL.

map versions <app>
map --json versions <app>

<app> can be the short app name, such as inventory-portal, or a literal app: ref. The CLI normalizes the short form to app:<name> and filters route status to that app only.

Use the output to answer three different questions:

Section	What it means	Use it for
`internal versions`	Immutable per-version records for this app. Each line includes the version label, deployment ref, and version hostname.	Pick a `--version` value for `map publish`, or match a version to `map --json status <deployment-ref>`.
`aliases`	App-environment records such as `preview` or `production`. Each line shows the app environment, route update action, deployment ref, alias hostname, and active canary split when present.	Check what the app environment serves after deploy, promote, rollback, route update, or canary action.
`published`	The clean public URL record. It is absent until an operator publishes a reviewed version.	Confirm what end users reach at the clean public hostname.

Text output is shaped like:

app: inventory-portal

internal versions:
  <label>  <deployment-ref>  <version-hostname>

aliases:
  production (ProductionPromote)  ->  <deployment-ref>  <alias-hostname>
  production (CanaryWeight)  ->  <current-deployment-ref>  <alias-hostname>  [canary <canary-deployment-ref> <weight>%]

published: <deployment-ref>  https://<app-hostname>

When no clean public URL has been pinned, the published line is:

published: (not published)

With --json, the response includes:

Field	Meaning
`app`	Short app name after normalization.
`app_ref`	Normalized app ref, such as `app:inventory-portal`.
`versions[]`	Internal version entries with `label`, `deployment_ref`, `hostname`, `app_env`, the API account-context field `platform_env`, and `route_pointer_ref`.
`aliases[]`	App-environment records with `app_env`, `updated_from_action`, `deployment_ref`, `hostname`, `pinned`, and `route_pointer_ref`.
`aliases[].canary_deployment_ref`	Present when an alias has an active canary split.
`aliases[].canary_weight_pct`	Present when an alias has an active canary split.
`published`	Published clean-public-URL record with `deployment_ref`, `hostname`, and `route_pointer_ref`, or `null` when the app has not been published.

map publish --version <label> resolves the label from internal versions. If release evidence already names the deployment ref, pass map publish <app> --deployment-ref <deployment-ref> instead of relying on the label lookup.

map rollback¶

Runs rollback for an ID, with optional evidence ref.

map rollback <id>

Flag	Meaning
`--evidence-ref <ref>`	Evidence ref to attach to the rollback request.

map version¶

Prints the installed map-cli package version.

map version
map --json version

map access¶

Plans or applies app access configuration. By default, the command reads access.yaml from the current directory; use --repo-dir or --file when the file is elsewhere.

map access plan
map access apply

access.yaml supports app_ref, tenant_ref, account_ref, exposure, allowed_domains, and share. app_ref is required unless passed with --app-ref; exposure defaults to protected and must be public or protected. CLI flags override the file for app, tenant, account, and exposure. map access plan prints the resolved policy without calling the control plane. Use map --json access plan when you need the exact request body for review. map access apply writes the resolved policy. The apply response includes effective: next-deploy-route-push; the served route receives the policy on the next route push or reconcile.

Unknown fields in access.yaml are rejected. A typo such as allowed_domain fails instead of silently applying a different policy.

Flag	Meaning
`--repo-dir <path>`	Directory containing `access.yaml`; defaults to the current directory.
`--file <path>`	Explicit access policy file; overrides `--repo-dir`.
`--app-ref <ref>`	App ref override; required when the file omits `app_ref`.
`--tenant-ref <ref>`	Tenant ref override.
`--account-ref <ref>`	Account ref override.
`--exposure <value>`	Access-policy exposure override; must be `public` or `protected`.

Global flags¶

Flag	Meaning
`--endpoint <url>`	Control-plane endpoint (overrides the saved login).
`--token <token>`	Bearer token (use with `--endpoint`).
`--login-state <path>`	Path to the saved login file.
`--json`	Machine-readable output.