CLI command reference#

Parse CLI command output, receipts, structured errors, and exit statuses correctly.

Overview#

Start with two read-only commands: action-manifest inspection and offline job preflight. The engine reference pages describe commands that run included local binaries.

Action Manifest#

On success, stdout is one JSON array and stderr is empty. Each array element has this shape:

Field	Type	Meaning
`name`	string	Stable action identifier from the embedded manifest
`description`	string	Human-readable purpose
`inputSchema`	object	JSON Schema for the action input
`executes`	boolean	Whether the action is defined as executable rather than plan-only
`class`	string	Customer-callability class

The current public manifest contains 25 actions. Twenty-two have executes: true. altifigence.analyze.run, altifigence.evolve.launch, and altifigence.verify.run have executes: false and are plan-only.

./alti commands

Offline Job Preflight#

Use the complete preparation and command in CLI First Success. The only success object is an altifigence.cli.engine-job-preflight.v1 receipt.

The receipt binds the locally calculated source hash and size to the validated job identity. These two booleans are essential:

submitted is false;
server_authority_verified is false.

The envelope’s execution_placement: "cloud" is a requested placement field. It does not contradict the offline behavior and does not show that a server was contacted.

./alti --json job validate \
  --job "$ALTI_WORKSPACE/job.json" \
  --workspace-root "$ALTI_WORKSPACE" \
  --source rtl/top.sv

JSON Error Contract#

When --json job validate reaches validation and fails, stdout contains no success receipt and stderr contains one object:

The code and message vary by failure. Do not parse a human message when the structured schema, error.code, and error.retryable fields are present. The validator does not echo the invalid job body or source bytes in this error.

{
  "schema": "altifigence.cli.error.v1",
  "error": {
    "code": "ENGINE_JOB_JSON_INVALID",
    "message": "The engine job JSON is invalid.",
    "retryable": false
  }
}

Exit Status#

alti has two dispatch paths with different exit-status contracts, so a script that only handles 0, 1, and 2 will misread real results. Which path runs is decided by the first word of the command line — a leading --json is skipped — before argument parsing. These are handled locally:

capabilities, rtl, sv, verification, trace, labs, tcl, eda, eidb, reports, physical, px, isa, ide, job, plus the exact forms analyze run and evolve run. mcp serve is intercepted ahead of both paths and starts the stdio MCP server.

Everything else is matched against the embedded action manifest. Note that only the run subcommand of analyze and evolve reaches the local path — other evolve subcommands fall through to the manifest, which defines evolve as a one-word action, so the extra word is reported as an unexpected argument with status 2.

The two workflows on this page do not share a path. alti commands is manifest-matched. alti --json job validate begins with job, so it is handled locally and follows the second table below — which is why a validation failure exits 1 rather than 2.

Manifest-matched commands:

Status	Interpretation
`0`	Manifest serialization succeeded, or the request was dispatched and a response was serialized
`1`	Registry, configuration, serialization, or dispatch failure
`2`	Unknown command, unexpected trailing argument, unknown flag, wrong value type, or a missing required option
`3`	`CLASS_NOT_ALLOWED` — the matched entry’s class is not callable by an external customer. Every entry in the current 25-action manifest is class `action`, so this status is reserved rather than currently reachable
`4`	The request was refused before dispatch. `alti whoami` returns `IDENTITY_NOT_VERIFIED`, `alti login` returns `AUTH_FLOW_UNAVAILABLE`, and the three source-bearing actions — `analyze`, `evolve`, `verify` — are denied unless `--allow-source-upload` is passed. `alti logout` is the exception: it exits `0` and reports that nothing was removed

Locally handled commands run through argument parsing and, where applicable, a packaged engine binary:

Status	Interpretation
`0`	The command, and any engine it invoked, completed successfully
`1`	A CLI-side runtime error, including the JSON error contract above. `alti capabilities` exits `1` from an extracted archive because the installed layout is absent
`2`	Argument-parsing failure, or a pre-launch rejection such as a missing engine operation or an out-of-range stdin payload
`126`	The engine binary was found beside `alti` but could not be started, is not a regular file, or is not executable
`127`	The engine binary was not found beside `alti` or on `PATH`
other	The engine’s own exit status, passed through unchanged

Because engine statuses pass through, any small integer — including 3 and 4 — can reach your script from an engine-backed command and does not carry the manifest-path meaning above. Branch on the command you ran, not on the number alone.

Always check the process exit status before parsing stdout. Keep stderr separate. An empty or partial file is not success, and a preflight receipt is not an engine, submission, or completion receipt.

$ alti job status --runner local job-123
ALTIFIGENCE_LOCAL_ENGINE_JOB_URL must be set to a non-empty value
[failed] job.status runner=local engine=alti-engine-job executable=alti-engine-job resolution=unresolved exit=2

Engine Commands: What Actually Runs#

The release ships the engine binaries next to alti, and alti runs them. For an engine-backed command, alti looks for the engine binary as a sibling of its own executable, falls back to PATH, and then executes it with the operation and arguments the subcommand builds. The receipt line on stderr names the binary, the resolution (sibling or path), and the exit status, so you can see exactly what was launched. This is the default: --runner defaults to local.

Five subcommands are compatibility paths that accept --runner: rtl compile, rtl synthesize, physical run, px analyze, and isa run. With --runner cloud or --runner private these print a [scaffold] dispatch line instead of running anything, because no runner adapter is connected; if you also pass engine arguments after --, they are rejected with status 1, since passthrough arguments are accepted only by --runner local. Every other engine-backed subcommand runs locally unconditionally and has no --runner flag.

Two commands genuinely require the signed installed layout rather than a flat extracted archive, and fail from an extracted archive alone:

alti capabilities, which resolves PREFIX/bin/alti and the receipt-backed release payload before it will report anything, and exits 1 otherwise;
alti tcl evaluate, which requires alti-tcl-local-runner as a strict sibling with no PATH fallback and additionally checks it against the installed trust chain. It reports TCL_INSTALLED_RUNNER_UNAVAILABLE and exits 127 when the sibling is absent, and TCL_INSTALLED_RUNNER_UNTRUSTED and exits 126 when it is present but fails release authentication.

Current Limitations

Manifest-backed remote actions do not have an available Cloud or Public API service in this release. A [scaffold] line and a plan-only manifest entry both stop before execution.
A locally executed engine command is a real run on your machine. Review its diagnostics and outputs before using them in a project.
CLI environment authentication and the packaged stdio MCP process are not needed for the offline preflight.

$ alti --json rtl fanout-free-committed-identities list
{
  "schema": "altifigence.local-engine-execution.v1",
  "status": "unavailable",
  "domain": "rtl",
  "operation": "fanout-free-committed-identities-list",
  "runner": "local",
  "binary": "alti-rtl-runner"
}