CLI engine commands

Overview

This page covers local design engine commands, their principal arguments, and their execution boundaries. Use the installed command’s leaf --help for its complete option and value-enum list. Read the result’s own limits before using it as engineering evidence.

Read CLI command surface first. It defines the routing, the exit codes, the receipt envelopes, and the sibling-resolution rule that every command below depends on. The job namespace, analyze run, and evolve run are on CLI job and cloud commands.

Conventions used in the tables:

• <ANGLE> is a positional argument; [ANGLE]... is a repeatable optional one.

• Options in the Required column must be present, or the command exits 2 before anything is launched.

• Every subcommand also accepts --json and -h/--help. Those are not repeated per row.

• --project is --project <PROJECT>, an optional working directory for relative input and output paths, unless a row says otherwise. It must resolve to a real directory; an unresolvable value exits 2.

capabilities

alti capabilities inspects the authenticated installed layout and reports its operation surface. Complete Install on Linux first; the 0.1.9 embedded bootstrap supplies the previously missing receipt and payload layout. A capability response is not evidence of an executed kernel or design.

rtl

Twenty-eight subcommands. rtl compile and rtl synthesize are the two --runner-carrying compatibility paths; every other rtl subcommand runs locally and unconditionally.

Unlike physical run and px analyze, those two do launch their engine with no passthrough arguments, because each supplies a fixed engine operation. The engine then reports its own missing-argument error and its exit status passes through unchanged. Give them the arguments they need after --.

--schematic on the three rtl artifact subcommands selects the fixed schematic receipt store instead of the RTL operation-result store.

--entry-id on the committed-identity leaves must be exactly 64 lowercase hexadecimal characters. Anything else exits 2 with entry id must be exactly 64 lowercase hexadecimal characters.

rtl schematic bounds

rtl schematic validates its paths before launching anything. Each source file, include directory, and define is rejected at admission if it breaks one of these:

Paths must be relative to the selected project, must not start with -, must not contain control bytes, and must not contain ... --top and a define name must be a SystemVerilog identifier of 1 to 128 bytes; a define may carry a value after = up to 4096 bytes in total.

rtl target-analysis options

admit and preflight read canonical source-bundle JSON from stdin and both require the same eleven options: --module <NAME>, --top <NAME>, --targets <CSV>, --primary-target <ID>, --tools <CSV>, --report-detail <LEVEL>, --profile <ID>, --cpu-slots <N>, --memory-bytes <N>, --max-wall-time-ms <N>, and --deadline-unix-ms <N>. --cell-decomposition is an optional boolean flag.

--cpu-slots is a 32-bit unsigned integer; --memory-bytes, --max-wall-time-ms, and --deadline-unix-ms are 64-bit unsigned integers.

A duplicate or unlisted value in either CSV is refused at parse time, for example targets must be a comma-separated subset of: generic-asic, sky130-asic, xc7-fpga.

The simulation request envelope

<REQUEST_JSON> is a project-relative path to a file the CLI reads and checks before it launches anything. The path must be normalized and relative, must not cross a symbolic link at any component, and must resolve inside the project root. The file must be a regular file no larger than 260 MiB.

Its JSON must be an object with exactly four keys:

{
  "schema": "altifigence.rtl.operation-request.v1",
  "version": 1,
  "operationId": "altifigence.rtl.simulate.v1",
  "request": {}
}

operationId must be altifigence.rtl.simulate.v1 for rtl simulate and altifigence.rtl.simulate.v2 for rtl simulate-v2. A mismatch is refused before launch with RTL simulation request must be the exact <id> envelope.

The committed-identity subcommands cannot run

The eight rtl *-committed-identities list and read leaves dispatch to an engine named alti-rtl-runner. That binary is not one of the 24 engine binaries the release builds and ships, so it can be resolved neither as a sibling of alti nor on PATH from a correct installation. Invoking one produces a local-engine receipt with status: "unavailable" and exitCode: 127:

$ 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",
  ...
}

Do not build automation on these eight commands.

sv

Twenty-three subcommands, all local and unconditional. None accepts --runner.

Positional value rules:

• <LINE> and <COLUMN> are 1-based non-zero integers. 0 exits 2.

• <REPLACEMENT> must be a SystemVerilog identifier: the first character is a letter, _, or $, and the rest are alphanumeric, _, or $.

• <REVIEWED_PLAN_SHA256> must be 64 lowercase hexadecimal characters.

• <STABLE_ID> must be 1 to 128 characters drawn from lowercase letters, digits, and hyphens.

• --filter must be 1 to 128 non-control bytes; --limit must be an integer from 1 to 64, and --limit 65 exits 2.

sv frontend rename-apply is the only sv subcommand that requires --project, and the value must be an absolute path to a real directory that is not a symbolic link. Without it the command exits 1 with SV rename apply requires --project <absolute-workspace>.

sv review immediate and sv review interprocess read SystemVerilog source from stdin. They are the only sv subcommands backed by their own engines, alti-sv-immediate-review and alti-sv-interprocess-review; everything else in the namespace uses alti-sv-frontend.

sv uvm simulation admit requires thirteen options: --bundle-id, --bundle-sha256, --source-count, --source-bytes, --test, --top, --clock, --period-ps, --cycles, --max-wall-time-ms, --max-cpu-cores, --max-memory-bytes, and --max-artifact-bytes. sv uvm simulation preflight requires those thirteen plus --attempt-id, --observed-at-unix-ms, and --deadline-unix-ms, and additionally accepts the boolean --cancellation-requested (default false). --source-count is a 32-bit unsigned integer, --max-cpu-cores is a 16-bit unsigned integer, and the remaining numeric options are 64-bit unsigned integers.

verification

--tolerance-pct must be a finite non-negative number; a negative or non-numeric value exits 2 with tolerance-pct must be a finite non-negative number.

--format here selects the engine’s own output format and is independent of the CLI-level --json envelope flag. Both may be used together.

trace

<FORMAT> on trace export is a positional value enum, not a flag, and it comes before the input path. Its values are vcd and chrome.

--reference may be repeated to name additional reference artifacts. <TRACE_ARTIFACT_ID>, the reference ids, and <PACKAGE_ID> may begin with a hyphen without needing --.

Note that alti trace with no subcommand reaches the local parser and exits 2 asking for a subcommand. The one-word trace action in the embedded action manifest is therefore not reachable from the command line in this release; see CLI job and cloud commands.

labs

Read-only descriptors and validation. Workflow execution is not exposed by the CLI.

labs validate is strict about its two inputs, and every rule below is checked before the engine starts:

• --project must be an absolute path to a real directory, not a symbolic link.

• <DESCRIPTOR> must be workspace-relative, must contain no .. or root component, and must be at most 4096 bytes.

• It must use the .json extension.

• It must resolve to a real regular file of at most 1048576 bytes, and the resolved path must still be inside the project.

tcl

The first four answer from descriptors through the packaged alti-tcl engine and emit the standard local-engine envelope.

tcl evaluate is different in three ways. It reads the script from stdin, with a bound of 4194304 bytes; empty input is refused. It requires alti-tcl-local-runner as a strict sibling of alti with no PATH fallback, and checks it against the installed trust chain. The 0.1.9 bootstrap installs the fixed signed Tcl component needed for this path; use the installed binary. And it emits its own receipt schema, altifigence.cli.tcl-evaluation.v1, with its own exit codes — both are in CLI command surface.

eidb

eidb capabilities, eidb readback, and eidb semantic-readback take no --project; they are pathless with respect to the CLI.

physical

Forty-two subcommands. physical run is the --runner-carrying compatibility path; the rest run locally and unconditionally, and each one passes its own subcommand name straight through to alti-physical-runner as the engine operation. The CLI’s role in this namespace is argument admission and receipt framing, so the surface is regular enough to give as two groups.

Every entry-scoped follow-up reads a persisted entry produced by an earlier project-scoped operation. Omitting --entry-id exits 2 before anything is launched. That is thirty-six of the forty-two. The remaining six are:

physical route-evidence-closure read is a two-step command: the CLI first lists the committed identities, requires that your --identity-key-sha256 appears in that list, then rereads exactly that one. A key that is not 64 lowercase hexadecimal characters, or that is not in the current list, is refused with exit 1 before the second step. The list step is pathless and does not take --project.

physical run will not launch without an engine operation after --:

$ alti physical run
error: legacy local engine operation is required after `--`

That exits 1. The accepted legacy operations are --capabilities-json, capabilities, and execute; anything else exits 1 with legacy local engine operation ... is not in the public allowlist.

px

px analyze is the --runner-carrying compatibility path. Where a positional argument is named <INPUTS_RELATIVE_...>, it is resolved below the project’s inputs/ directory, not against your working directory.

Three of these state their own limits in their own help text, and those limits are part of the contract: px static-timing is explicitly non-signoff, px spef-summary explicitly carries no analysis authority, and px fdtd2d preflight reports a readiness blocker rather than a result. Treat their output accordingly.

Like physical run, px analyze requires a legacy operation after -- and otherwise exits 1. Its allowlist is capabilities and execute.

PX CPU and CUDA operations

These commands accept --project; the first two also accept --timeout-ms 1..300000. Explicit cuda requires usable CUDA execution. auto separately permits the engine’s recorded CPU fallback; inspect the reported backend. These bounded numerical operations do not establish general physical signoff or GPU acceleration of every PX operation.

isa

Four of the six subcommands read CX source exclusively from stdin. isa run is the --runner-carrying compatibility path.

--check accepts exactly elaboration, static-semantics, encoding-uniqueness, and decode-determinism. --bit-len is a 32-bit unsigned integer. --text and --bits must not be empty or whitespace-only.

Unlike physical run and px analyze, isa run carries a fixed engine operation, so it launches with no passthrough arguments and the engine reports its own requirements:

$ alti isa run
cx run: run requires --program <path> or --program-text
[failed] isa.run runner=local engine=alti-cx/run executable=alti-cx resolution=path exit=1 project=.

ide

Desktop host operations. Computation stays in the engine namespaces above.

ide open launches the separately installed desktop application. The native workspace, Cloud, service, and project-creation commands below work through their own explicit backends.

--project must be a canonical absolute directory: absolute, an existing directory, not a symbolic link, and equal to its own canonical form. A path that resolves through a symlink is refused rather than silently followed.

ide open does not use an engine binary. It resolves an executable named altifigence-ide as a sibling of alti and then on PATH, spawns it with --project <canonical-dir>, and emits an altifigence.ide-launcher-receipt.v1 receipt:

The exit status is 0 for spawned and 1 otherwise. altifigence-ide ships with Digital Design Studio, not with the CLI archive, so ide open reports unavailable from a CLI-only installation.

Native project and workspace operations

ide init --parent ABSOLUTE_DIR --name NAME creates a new scaffold below a canonical, caller-owned parent. It does not overwrite an existing project. ide workspace operates on saved local files without opening the UI:

The native plan result is an opaque complete apply input. Save raw engine output without global --json, review it, then pass the same document to its matching apply command. For example, with your existing absolute project and typed hierarchy request:

alti ide workspace hierarchy-plan --project "$PROJECT" \
  --request "$HIERARCHY_REQUEST" > "$PLAN_FILE"
# Review the complete plan and changed source before the next command.
alti ide workspace hierarchy-apply --project "$PROJECT" --request "$PLAN_FILE"

Do not pipe a failed command’s output into apply. Choose a new plan file and check each exit status. File authoring uses durable, serialized transactions and current source hashes; it is not filesystem-wide instantaneous atomicity against unrelated writers. Conflicts require a new review. Hierarchy authoring is bounded source selection and scaffolding, not full SystemVerilog semantic refactoring or an equivalence proof.

Settings retain the DDS .alti/ide-settings.json format, unknown keys, and literal null values. The patch is recursive merge, not RFC 7396 deletion. The request/result budget is 256 KiB and depth 8; the native UI and CLI use the same .alti/.ide-settings.lock. The CLI addresses the current project format, not a second independent desktop-global settings scope.

Native transactions and Git require the Linux contract. Current recovery reads both V1 and V2 journals. After an interrupted create/delete or hierarchy apply, run the new CLI’s health before opening an older V1-only DDS backend. An older backend refuses a pending V2 journal without clearing it. Normally completed transactions clear their active journal; a transparent-recovery backend upgrade is recommended, not a prerequisite to every completed CLI edit.

Git

Under ide workspace git, all commands take --project ABS:

These operations recover and serialize against native workspace transactions. They do not expose arbitrary Git arguments, hooks, or remote push credentials.

Saved-source search

alti ide workspace search --project "$PROJECT" --query 'module' --limit 80

Native search supports --match-case, --whole-word, a conservative fixed-width --regex, limits of 1–500 matches, and --timeout-seconds 1..120. It reads saved text through the native files/read boundary, with budgets of 500 files, 4 MiB per file, 16 MiB total, and 1 MiB output. Check truncation and content evidence. Unsaved editor buffers are not searched. Cloud search and legacy HTTP search/replace are separate service operations.

xls

The native path supports bounded DSLX and XLS IR functions with 1–64-bit values, constant folding/dead-code removal, and combinational RTL or RTL with 1–16 output-register stages. The request selects cpu, or explicit cuda for supported batch evaluation. An unavailable CUDA backend is an error, not an automatic CPU run. Start with the CPU example.

The separate upstream path installs a pinned public Google XLS Linux toolchain, verifies its archive and tool/stdlib inventory, and preserves licence files. It supports imports, parametrics, structs, enums, aggregate and arbitrary-width types, and procs where the selected upstream tool supports the requested operation. It does not use the bounded bits64 parser or accelerate the full Google toolchain with CUDA.

Upstream requests select check, eval, convert, optimize, or codegen. DSLX eval without explicit vectors/ticks runs actual module tests; zero executed unit tests is not success. The base archive does not contain the standalone IR/proc evaluator executables. Explicit vectors or channel ticks require an additional verified evaluator bundle admitted during install with --evaluator-bundle and --evaluator-manifest-sha256. Inspect capabilities before requesting those operations. Upstream pipeline codegen supports 1–64 stages; its unit-delay schedule is not characterized silicon timing.

compute

The request commands accept --project. Simulation/Evolve input is bounded to 4 MiB; verify input to 16 MiB. The packaged alti-rtl-cuda owns this path. compute rtl-evolve takes altifigence.rtl.evolve-request.v1, with the existing native generation request nested under request; it is not an evolve run operation envelope.

Evolve CUDA computes bounded combinational activity diagnostics. Candidate generation, correctness checks, synthesis, and objective evaluation remain on the CPU. Actual Icarus iverilog and vvp must be available through host tool configuration. cpu-reference requires cuda_timeout_ms: 0 and device_memory_bytes: 0; cuda refuses unavailable execution instead of falling back. Use a fresh request.run_dir with an existing parent.

The request bounds generations and children to 1–16, islands to 1–4, total planned evaluations to 256, and LLM children to zero. Device memory is a bounded worker buffer budget, not a limit on total driver memory. The optional local cancel_file and deadlines support cooperative cancellation; native tool calls retain their own limits. A successful CUDA result needs actual accepted candidate activity and stored hardware provenance, not merely device discovery or an initial probe. Functional CPU/CUDA agreement is not a speedup claim.

Commands Missing from the Current Download

The previously omitted eda and reports namespaces are now routed:

These are bounded inspection, parsing, or binding operations, not general EDA tool execution. ide init and the explicit native Evolve commands are also available. The unshipped alti-rtl-runner compatibility path described above remains a separate limitation; do not infer support from help alone.

Prepare an engine workflow

1. Choose the operation and read its installed capability response and leaf help.

2. Create a small saved input inside the selected project and identify its top/module or entry point.

3. Provide required external tools and use an explicit backend when the request supports CPU/CUDA selection.

4. Run once with bounded resources and keep diagnostics plus the complete native result.

5. Inspect actual backend, inputs, output artifacts and unsupported metrics before building a larger workflow.

Use DDS analysis for the graphical workflow and Evolve for candidate comparison. CLI engine support, a desktop panel and a Cloud route are separate integrations; check the workflow you will actually use.