CLI automation and CI

Overview

Provision a verified Linux installation, then run design work as an ordinary job user against fresh workspaces. Keep installation privileges separate from source processing. This page uses the CLI 0.1.9 installation contract; select an actual available release through Downloads.

Preparation Gate

1. Pin the exact version, archive name, and signed catalog your workflow accepts.

2. Follow Verify Downloads to authenticate the public-key DER pin, signed checksum manifest, archive signature, and catalog signature before executing any downloaded binary.

3. Use Install on Linux. The embedded bootstrap creates the signed layout and fixed Tcl component without a repository checkout, build, or network access. Install only during the administrator-controlled step.

4. Run the exact installed PREFIX/bin/alti and retain its version and capability report. Do not substitute a development binary or an unverified PATH runner.

Archive presence and help output do not prove installed readiness. Check alti capabilities and the capability response for the operation you intend to run. A failed check should stop that operation rather than enable a fallback.

Offline CI Recipe

Prepare job.json and its owner-only source using CLI First Success. Set ALTI_BIN to the exact verified installation and ALTI_WORKSPACE to this job’s prepared workspace:

set -euo pipefail
ALTI_BIN="${ALTI_BIN:?set the verified absolute installed alti path}"
ALTI_WORKSPACE="${ALTI_WORKSPACE:?set the private prepared workspace}"
case "$ALTI_BIN" in /*) ;; *) exit 1 ;; esac
EVIDENCE="$(mktemp -d)"

"$ALTI_BIN" version > "$EVIDENCE/version.txt"
"$ALTI_BIN" capabilities > "$EVIDENCE/capabilities.json"
"$ALTI_BIN" commands > "$EVIDENCE/commands.json"
"$ALTI_BIN" --json job validate \
  --job "$ALTI_WORKSPACE/job.json" \
  --workspace-root "$ALTI_WORKSPACE" \
  --source rtl/top.sv \
  > "$EVIDENCE/preflight.json" 2> "$EVIDENCE/preflight-error.json"

jq -e 'length == 25' "$EVIDENCE/commands.json" >/dev/null
jq -e '
  .receipt_schema == "altifigence.cli.engine-job-preflight.v1" and
  .status == "client_preflight_valid" and
  .submitted == false and
  .server_authority_verified == false
' "$EVIDENCE/preflight.json" >/dev/null

This checks preflight, not RTL execution. Add an explicit CPU XLS evaluation or another bounded local engine operation when your workflow needs an execution result. No Cloud credentials are needed for these local checks.

Capability and Output Rules

• Check process exit status before parsing the expected command-specific schema.

• Keep stdout and stderr separate. With --json, parse engine output from the envelope’s stdout; for DDS plan/apply piping, save the raw native result.

• Use a fresh workspace/run directory. Review a complete authoring plan before applying it, and regenerate after a conflict rather than replacing its hashes.

• Use explicit cpu/cuda or Evolve cpu-reference/cuda policies. XLS and packed RTL do not silently fall back. PX auto is a separate opt-in policy whose actual backend and fallback must be read from its receipt.

• Schedule GPU qualification separately with the required driver and Icarus tools. Require actual accepted CUDA work and stored hardware provenance; discovery alone is insufficient. Do not infer performance from functional tests.

• Cloud writes need account/project permission and the operation’s explicit upload consent. Legacy HTTP replacement needs a fresh hash from that service; a 409 is a conflict, not permission to retry with weaker checks.

Preserve Evidence

Keep the verified catalog/signatures, installed binary digests, CLI version, redacted arguments, input digests, exit status, and bounded result/diagnostic streams. GPU records also need the actual device/driver and external tool identities. Treat development/debug evidence separately from signed-package qualification. Avoid retaining credentials or project source unnecessarily.

Keep CI repeatable

1. Pin the verified release and external toolchain versions in runner provisioning.

2. Use a fresh user-owned source directory and new output paths for each job.

3. Run capability checks and a small actual execution suitable for the requested operation.

4. Fail the pipeline on nonzero exit, malformed output, stale source identity or missing required artifacts.

5. Retain bounded diagnostics and digests; rotate credentials through the CI secret store rather than saved logs.

Cache verified installation inputs or immutable toolchains by version and digest. Keep project results, session files and provider credentials out of shared caches. Remote work needs its own explicit authorization and job tracking; a local CI pass does not mean Cloud work ran.