CLI automation and CI#

Pin and verify an exact CLI release, then automate only action-manifest inspection and offline client preflight.

Overview#

CI can pin and verify an exact CLI archive, inspect its embedded action manifest, and produce an offline client-preflight receipt. There is no system installation command, successful installed-capability discovery, or complete remote job workflow to automate in this release.

Preparation Gate#

Before a workflow uses the CLI:

  1. Pin one CLI version — the one this workflow verified — together with its exact Linux x86_64 archive filename and published checksum. Pin a literal version; do not resolve a “latest” pointer at run time.

  2. Download through the official release path and verify the checksum and detached signature as documented on Verify Downloads.

  3. Extract into a new, job-owned directory.

  4. Run the exact path from that directory; do not copy individual executables into a shared system location.

  5. Run alti commands from that exact extraction and require a JSON array with 25 entries.

  6. If the workflow needs a job-envelope check, use only the offline validation in CLI First Success.

Pin and verify the archive before asking the binary what it contains. This keeps a workflow from silently switching to a different CLI build.

Do not make local engine execution conditional on filenames in the archive. The plain archive lacks the installed receipt layout needed to prove a trusted local capability.

Offline CI Recipe#

Prepare job.json and an owner-only source exactly as described in CLI First Success. Then run a step equivalent to:

Bash
set -euo pipefail

CLI_VERSION="${CLI_VERSION:?pin the CLI version this workflow verified}"
EXPECTED_CLI_SHA256="${EXPECTED_CLI_SHA256:?pin the published checksum for that version}"

CLI_ARCHIVE="$RUNNER_TEMP/altifigence-cli-v$CLI_VERSION-x86_64-unknown-linux-gnu.tar.gz"
CLI_DIR="$RUNNER_TEMP/altifigence-cli-$CLI_VERSION"
CLI_WORKSPACE="$RUNNER_TEMP/alti-offline-workspace"

test "$(sha256sum "$CLI_ARCHIVE" | awk '{print $1}')" = "$EXPECTED_CLI_SHA256"
test ! -e "$CLI_DIR"
mkdir -m 700 "$CLI_DIR"
tar -xzf "$CLI_ARCHIVE" -C "$CLI_DIR"
chmod 600 "$CLI_WORKSPACE/inputs/rtl/top.sv"

"$CLI_DIR/alti" commands > "$RUNNER_TEMP/alti-commands.json"
"$CLI_DIR/alti" --json job validate \
  --job "$CLI_WORKSPACE/job.json" \
  --workspace-root "$CLI_WORKSPACE" \
  --source rtl/top.sv \
  > "$RUNNER_TEMP/alti-preflight.json" \
  2> "$RUNNER_TEMP/alti-preflight-error.json"

jq -e 'length == 25' "$RUNNER_TEMP/alti-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
' "$RUNNER_TEMP/alti-preflight.json" >/dev/null

Supply CLI_VERSION and EXPECTED_CLI_SHA256 as workflow inputs or repository variables. Set them to the version you verified and to its checksum taken from the verified public trust material, not from the artifact being checked. Both use :?, so a workflow that forgets one fails at that line with the message shown rather than proceeding against an unpinned archive.

Keeping the version in a variable is not the same as leaving it floating. The workflow must still pin one literal value and change it deliberately, after re-verifying the new archive under Verify Downloads. The version moved out of this page because a number printed here goes stale on the next promotion; it did not move out of your workflow.

The runner paths above are examples supplied by the CI platform; adapt them to a job-owned directory. Do not use a shared or privileged system location.

This step needs no ALTI_TOKEN, ALTI_ORG_ID, or network access after the archive and trust material are present. Do not inject credentials into it.

Capability and Output Rules#

  • Check the exit status before reading either JSON file.

  • Require the exact receipt schema and the two false authority booleans.

  • Keep stdout and stderr separate; a JSON error object is not a receipt.

  • Fail if the source is not owned by the runner, is linked more than once, is group/world writable, or escapes the workspace.

  • Do not turn the Cloud placement field in the envelope into a submission step.

  • Add local-engine, source-upload, MCP, or remote API steps only from their own documented command guides.

Preserve Evidence#

Retain the archive filename and verified checksum, action-manifest JSON, redacted command line, exit status, offline preflight receipt, job-envelope revision, and source SHA-256. Do not retain source bytes solely because the preflight calculated their digest.

Redact customer data before uploading logs. A manifest entry, client preflight, submission, accepted job, completed run, and engine evidence are different outcomes and must remain different in retained evidence.