CLI First Success#

Evaluate a small XLS request on CPU, then optionally validate an offline job envelope and source boundary.

Overview#

Complete verification and installation first. The commands below use alti from the installed PREFIX/bin directory. Run them as your ordinary user, not as root.

Run a Small CPU XLS Evaluation#

This request adds two 8-bit values. It uses the bounded native XLS engine, requires no Google toolchain, GPU, or Cloud session, and makes overflow visible in the result.

alti capabilities
alti xls eval --request - <<'JSON'
{
  "schema": "altifigence.xls.operation-request.v1",
  "operation": "eval",
  "input_kind": "xls-ir",
  "source": "package demo\ntop fn compute(x: bits[8], y: bits[8]) -> bits[8] { ret sum: bits[8] = add(x, y) }",
  "top": "compute",
  "backend": "cpu",
  "vectors": [["255", "1"], ["0x10", "0b11"]]
}
JSON

Require exit 0 and the engine result for both vectors: bits[8]:0x0 and bits[8]:0x13. This proves only these inputs were evaluated. For broader DSLX language support, use the separate Google XLS path.

Optional Offline Job Preflight#

The following workflow reads the action manifest and validates a job envelope plus one local source file. It does not read credentials, contact a server, upload source, submit work, or run an RTL engine. Its receipt describes local validation only; submission and server authority remain false.

1. Inspect the Shipped Action Manifest#

alti commands

A successful command writes one JSON array to stdout and nothing to stderr. Each entry contains name, description, inputSchema, executes, and class. The current public CLI returns 25 entries. The value of executes describes the dispatch contract; the command can still require a local engine, account permission, or hosted service.

2. Prepare a Private Local Source#

Create a private workspace in your current user-owned working directory:

ALTI_WORKSPACE="$(mktemp -d -p "$PWD" alti-first-success.XXXXXX)"
mkdir -p "$ALTI_WORKSPACE/inputs/rtl"

Save this harmless source as $ALTI_WORKSPACE/inputs/rtl/top.sv:

module top(input logic clock, output logic value);
    always_ff @(posedge clock) value <= ~value;
endmodule

Make the source readable and writable only by its owner:

chmod 600 "$ALTI_WORKSPACE/inputs/rtl/top.sv"

The preflight rejects a source that is outside the workspace, linked more than once, not owned by the current user, or writable by a group or other users. Do not relax the permission check.

Save the following as $ALTI_WORKSPACE/job.json:

{
  "schema": "altifigence.engine.job.v1",
  "job_id": "offline-job-1",
  "operation": {
    "engine_id": "rtl-engine",
    "operation_id": "analyze",
    "contract_id": "rtl-analysis-request.v1"
  },
  "execution_placement": "cloud",
  "device_preference": {
    "selection": { "mode": "class", "value": "cpu" },
    "fallback": "deny"
  },
  "resources": {
    "cpu_slots": 1,
    "memory_bytes": 536870912,
    "device_slots": 0,
    "device_memory_bytes": 0,
    "max_wall_time_ms": 30000
  },
  "inputs": [
    {
      "artifact_id": "rtl-source-bundle",
      "role": "source_bundle",
      "artifact_schema": "rtl-source-bundle.v1",
      "uri": "workspace://inputs/placeholder",
      "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "cancellation": { "cancellation_id": "cancel-offline-job-1" }
}

The client replaces the placeholder URI and digest in its in-memory validation copy with the selected workspace-relative source and calculated SHA-256.

3. Produce the Offline Receipt#

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

A successful result is one JSON object on stdout with this contract:

Field	Required interpretation
`receipt_schema`	`altifigence.cli.engine-job-preflight.v1`
`status`	`client_preflight_valid`
`submitted`	Must be `false`
`server_authority_verified`	Must be `false`
`job_schema`, `job_id`, `operation`	The locally validated envelope identity
`execution_placement`	The requested placement in the envelope, not evidence of a submission
`source.workspace_uri`	The normalized workspace-relative source URI
`source.sha256`, `source.size_bytes`	The locally calculated source evidence

Exit status 0 means only that this client preflight passed. It does not mean the source compiled, a server accepted the job, or any work ran.

Failure Output and Exit Status#

With --json, a validation failure writes no success receipt to stdout and writes one altifigence.cli.error.v1 object to stderr. For example, malformed job JSON produces ENGINE_JOB_JSON_INVALID with retryable: false and exits with status 1.

For manifest inspection and offline preflight:

Exit status	Meaning
`0`	The manifest was printed, or the offline client preflight passed
`1`	Registry, I/O, source-boundary, or job-validation failure
`2`	Command-line syntax or argument parsing failure

Other alti commands use exit statuses this table does not list. 3 is CLASS_NOT_ALLOWED; 4 marks a request refused before dispatch, and both alti whoami and alti login exit 4 in this release; an engine-backed command passes the engine’s own exit status through, plus 126 when the engine cannot be started and 127 when it is not found. If your script will ever run more than the two commands above, use the full contract in Command Reference and treat every non-zero status as failure by default.

Keep stdout and stderr separate and check the exit status before parsing a receipt. Use the engine and Cloud command pages for explicit execution or submission; neither happens as a side effect of offline preflight.