CLI command reference

Overview

Use the installed binary after verification and installation. This reference distinguishes command discovery, execution results, preflight receipts, and service responses.

Action Manifest

Success writes one JSON array. Each entry has name, description, inputSchema, executes, and class. The embedded customer manifest has 25 actions, of which 22 have executes: true. altifigence.analyze.run, altifigence.evolve.launch, and altifigence.verify.run are plan-only. Native CLI subcommands have their own leaf help beyond this customer manifest. The server response determines whether a service operation is authorized and ready.

Use leaf help for native arguments:

alti commands

alti xls upstream run --help
alti compute rtl-evolve --help
alti ide workspace hierarchy-plan --help
alti ide cloud search --help
alti ide service workspace replace --help

Offline Job Preflight

Prepare the source and envelope in CLI First Success, then run:

The success schema is altifigence.cli.engine-job-preflight.v1. submitted: false and server_authority_verified: false are required: the source hash and job shape were checked locally, but no job was submitted or executed. An envelope’s requested execution_placement does not change this.

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

JSON Error Contract

A failed --json job validate writes no success receipt to stdout and emits an altifigence.cli.error.v1 object to stderr:

Use error.code when available. Other command families have their own error schemas; do not assume this envelope applies to every CLI command.

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

Exit Status

Always check the exit status before parsing stdout, and keep stderr separate. An empty or partial output file is not a successful result. A saved plan is not an applied transaction, and a server acceptance is not job completion.

Engine Commands: What Actually Runs

The XLS, compute, and native DDS adapters use fixed packaged siblings. Installed execution authenticates the relevant runner against its signed release record; adding another executable to PATH cannot repair a missing required sibling. Some older compatibility commands retain their documented resolver behavior. See Command Surface.

Without --json, engine stdout is forwarded so an opaque native plan can be saved directly. With --json, an engine invocation normally produces altifigence.local-engine-execution.v1; its stdout and stderr fields contain the child’s streams as strings. Parse the inner result separately.

For file and hierarchy plans, pass the entire native plan result to the matching apply command. Do not pass the outer CLI envelope or only a plan digest. The native backend validates current file hashes and its transaction conditions.

Service and Streaming Output

ide service returns altifigence.dds.service-receipt.v1 with operation, ok, httpStatus, and the bounded response body. HTTP 409 from replacement remains a conflict and is not retried. An empty successful DELETE response is kept empty; it is not fabricated into a server JSON object.

Native DDS search and Cloud search expose their own match/content evidence. Use the identity supplied by the backend you will write to; a hash computed for another search backend is not automatically a valid CAS token.

ide cloud terminal streams terminal bytes on stdout and connection status on stderr. It is not a single JSON receipt, even with global --json. Bound the attachment duration and preserve the cursor if you intend to reconnect.

--json release install and --json release uninstall emit altifigence.cli.release-bootstrap.v1 with operation, ok, and exitCode. Installer diagnostics go to stderr. Verification or privilege failures can occur before a success envelope exists.

Capture a result for automation

Select a fresh output directory for each invocation. Save stdout and stderr separately, capture the exit status immediately, and parse a success schema only after exit zero. With an engine envelope, parse its stdout string as the native document only when the command contract says it contains JSON.

For a plan/apply workflow, retain the complete raw native plan and use the same project. Review the affected files and current hashes before apply. A conflict calls for a fresh read and reviewed plan; it is not a reason to discard hash checks. See Automation and CI for a reproducible local check.