CLI job and cloud commands

Overview

This page covers job transport, native DDS Cloud sessions and workspace operations, the explicit legacy HTTP service adapter, and the 25 customer manifest actions. Native Evolve operations have separate request contracts.

Read CLI command surface first for the routing rule, the two exit-code sets, and the receipt envelopes. For the locally parsed engine namespaces see CLI engine commands. For current release limitations see CLI command reference, and for how the manifest is meant to be read see Action and capability contract.

The job Namespace

job covers offline client preflight plus job transport against a Job Service. It is handled by the local parser, so -h works and value ranges are checked before anything is contacted.

Six of its eight subcommands take --runner <local|cloud|private>, defaulting to cloud. That flag selects which Job Service to talk to. It is not the engine-runner flag on rtl compile and friends. job readiness and job validate have no --runner at all and never touch a network.

<JOB_ID> and --artifact-id may begin with a hyphen without needing a -- separator; the parser accepts leading-hyphen values on these arguments.

The two range-checked options on job wait are enforced by the parser, not the service:

$ alti job wait --poll-interval-ms 99 job-123
error: invalid value '99' for '--poll-interval-ms <POLL_INTERVAL_MS>': 99 is not in 100..=60000

That exits 2.

job readiness

job readiness answers without credentials or network. In this release it is a fixed, pathless projection: every component reports configured: false and ready: false, and the blockers array is complete.

{
  "schema": "altifigence.engine-product-host-readiness.v1",
  "product_id": "altifigence-cli",
  "authority": { "configured": false, "ready": false },
  "admission": { "configured": false, "ready": false },
  "dispatcher": { "configured": false, "ready": false },
  "executor": { "configured": false, "ready": false },
  "artifact_readback": { "configured": false, "ready": false },
  "ready": false,
  "blockers": [
    "authority_unavailable",
    "admission_unavailable",
    "dispatcher_unavailable",
    "executor_unavailable",
    "artifact_readback_unavailable"
  ]
}

It exits 0. A 0 here means the readiness question was answered, not that anything is ready.

job validate

job validate is the offline preflight documented step by step in CLI first success. It reads an EngineJobV1 document from --job (or stdin when --job is - or omitted), checks it against the exact Cloud CPU RTL client envelope, and hashes one local source file. It resolves no credentials, creates no client, and contacts nothing.

Its receipt schema is altifigence.cli.engine-job-preflight.v1. On success status is client_preflight_valid, submitted is false, server_authority_verified is false, job_schema is altifigence.engine.job.v1, execution_placement is cloud, the operation block is rtl-engine / analyze / rtl-analysis-request.v1, and the source block carries workspace_uri, sha256, and size_bytes.

The job document is read with a hard bound of 8388608 bytes. Above that the command fails with EngineJobV1 JSON exceeds the CLI limit.

Cloud submission requires an explicit source opt-in

With --runner cloud, both job submit and analyze run require all three source-upload options together. There is no way to submit a Cloud CPU RTL job without them in this release:

$ alti job submit --job job.json
error: Cloud Engine Job source upload is disabled; pass --allow-source-upload explicitly.

That exits 1. With --allow-source-upload but no --workspace-root the message is --workspace-root is required with --allow-source-upload., and likewise for --source.

--workspace-root must be absolute. --source is a portable relative path below <workspace-root>/inputs.

Cloud artifact download requires its own opt-in

On job result with --runner cloud, the three artifact options are a group. Passing any of them switches the command into download mode and then requires all three:

• Without --allow-artifact-download: Cloud Engine Job artifact download is disabled; pass --allow-artifact-download explicitly.

• Without --artifact-id: --artifact-id is required with --allow-artifact-download.

• Without --output-dir: --output-dir is required with --allow-artifact-download.

--output-dir must be an absolute directory. --artifact-id comes from the output list of a terminal EngineResultV1.

Runner-scoped refusals

Three option groups are scoped to a runner and refused outside it. Each of these is decided before any process starts or any request is made:

The older local/private path names the retired alti-engine-job adapter, which is not in the 24-runner release inventory. Accepted runner syntax and endpoint variables do not establish a delivered local/private Job Service. Use the built-in Cloud path only where the service and account are enabled, or use a documented direct local engine command.

Machine-readable job errors

job subcommands and analyze run invoked with --json emit a structured error envelope on failure instead of a bare message:

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

The complete code set is:

retryable is false on every one of them in this release. This envelope is emitted for the job namespace and analyze run. Other command families use their own error/receipt contracts; see Command Reference.

analyze run and evolve run

analyze run and the explicit native Evolve subcommands reach the local parser. The one-word customer actions analyze and evolve are separate contracts.

analyze run takes the same option set as job submit and follows the same Cloud source-upload rule. It differs in one way: it accepts --runner but rejects anything except cloud.

$ alti analyze run --runner local --job job.json
error: Local and Private job service adapters are not available; use --runner cloud.

That exits 1.

evolve run has no --runner, no --project, and no passthrough. It reads one request document — --request - reads stdin — and dispatches to the packaged alti-evolve engine, whose exit status passes through:

$ echo '' | alti evolve run --request -
alti-evolve: invalid request JSON: EOF while parsing a value at line 1 column 0

That 2 is alti-evolve’s own exit status passing through, not a CLI argument error. On an installation where the engine cannot be resolved the same command exits 127 with a receipt whose status is unavailable.

evolve capabilities, evolve analyze, evolve cx-search, evolve measured-ppa, and evolve artifact are also routed. For example, evolve analyze SAVED_RTL --top TOP [--project ABS] analyzes saved source. Measured-PPA admission/readiness/preflight does not produce measured PPA.

The public GPU activity operation is compute rtl-evolve --request FILE_OR_DASH. It has a separate native generation envelope and explicit CPU-reference/CUDA policy. See Engine Commands rather than forwarding an evolve run request to it.

Digital Design Studio Cloud

Use ide cloud login, then ide cloud whoami to verify the native session’s identity. refresh and logout manage that session; --session-dir selects a private alternative to the default. See CLI Authentication.

ide cloud contract --request FILE_OR_DASH validates a typed project/member/ source/workspace request offline. ide cloud run --request FILE_OR_DASH sends that request through the native API using the saved session. Source-bearing requests require --allow-source-upload. Contract validation never grants organization access or replaces the service’s current permissions.

alti ide cloud search --org "$ORG_ID" --project "$PROJECT_ID" \
  --query 'module' --limit 80
alti ide cloud terminal --org "$ORG_ID" --project "$PROJECT_ID" \
  --name cli --max-seconds 60

Use real authorized organization/project UUIDs. Search takes --match-case, --whole-word, conservative fixed-width --regex, --limit 1..500, and --timeout-seconds 1..120. It uses existing scoped files/read routes and saved content, with 500 files, 4 MiB/file, 16 MiB total, and 1 MiB output budgets. Manifest/header/generation changes invalidate a mixed snapshot. Returned contentHash hashes the exact UTF-8 text read and, for the current Cloud owner, must equal fileVersion. Retain fileVersion and workspaceRevision as separate CAS fields.

Terminal attachment preserves WebSocket transport and current authorization. It streams stdout bytes; status goes to stderr, even with global --json. Use --cursor to resume, --cols 2..500, --rows 1..200, and --max-seconds 1..300 to bound attachment. Detaching is not a request to kill the persistent PTY. This is Cloud project execution, not a local CLI shell.

Legacy DDS Workspace Service

ide service targets an explicitly configured legacy HTTP workspace owner. Set --endpoint or ALTI_STUDIO_ENDPOINT and its existing ALTI_STUDIO_SERVICE_SECRET in the caller’s private environment. No native Cloud session, browser cookie, or arbitrary URL/body forwarding is substituted. This describes the legacy service adapter, not a claim that the current native desktop UI uses these endpoints or that a public production service is enabled.

Search accepts --match-case, --whole-word, a conservative fixed-width --regex, and --limit 1..1000 (default 80). Regex admission deliberately accepts a subset of the owner’s JavaScript syntax; groups, alternation, and quantifiers are rejected. Backend matching remains the service’s responsibility.

Replacement takes a closed JSON object with required query, replacement, paths: [one portable path], and expectedHashes: {same path: 64 hex digits}. Optional options contains only booleans matchCase, regex, and wholeWord. Optional match contains that same path and one-based integer line/column between 1 and 4194305. Omit match to replace within the selected file, not the whole workspace. Obtain the hash from this same service’s current result.

Requests are at most 64 KiB including JSON encoding and replacement text. Unknown fields, mismatched hash keys/paths, invalid indices, traversal, links outside the server boundary, and protected metadata/search-excluded paths are not supported. The CLI rejects invalid shapes and protected paths before HTTP; filesystem ownership and link checks remain with the service. It never performs local workspace replacement.

Responses are bounded to 8 MiB. --timeout-seconds 1..3600 sets the complete HTTP deadline (default 30); redirects and automatic retries are disabled. The altifigence.dds.service-receipt.v1 retains HTTP status and body, including an empty successful DELETE response. A 409 remains a conflict. Backend CAS and atomicity are not a cross-backend guarantee, and local/Cloud content hashes must not be substituted for that service’s expected hash without its contract.

The Action Manifest

Everything not handled by the local parser goes to the manifest dispatcher, which matches your command path against the embedded customer-tools.v1.json. alti commands prints the whole manifest as one JSON array of twenty-five entries and exits 0 without credentials.

Twenty-two entries are marked executes: true. Three — analyze, evolve, and verify — are executes: false and print a [plan-only] note before dispatching. Those same three are the only ones that carry source bytes, and they are gated behind --allow-source-upload.

Fourteen of the twenty-five also carry the remote_core profile; the rest are local_extended only. What that profile means for availability is covered in Action and capability contract.

Every action below reads ALTI_TOKEN and ALTI_ORG_ID from the process environment before it constructs a client, and fails with exit 1 if either is missing:

$ alti credits
Config error: ALTI_TOKEN is not set (org API key or access token).

Options common to the list actions

Several actions share a paging shape: --limit <INTEGER> in the range 1..=100, and --cursor <STRING>. Both are validated locally before any request:

$ alti project ls --limit 101
Invalid value for --limit: outside allowed range.

That exits 2, as does an unknown flag (Unknown option(s): --limti), a missing required option (Missing required option(s): --projectId), and an out-of-enum value (Invalid value for --visibility: expected one of public, private.).

Workspaces and projects

Conversational RTL

chat models is matched before chat, because the dispatcher prefers the longest matching command path. alti chat is credit-gated and audit-logged server-side.

Estimation and plan-only actions

--rtl and --testbench are inline source strings with a hard limit of 1048576 bytes each, checked locally:

$ alti analyze --target kv260-fpga --rtl "$(cat huge.sv)" --allow-source-upload
Invalid value for --rtl: exceeds size limit.

That exits 2. Without --allow-source-upload any of these three exits 4 before a client is constructed:

Source upload is disabled by default. Re-run with --allow-source-upload only
after reviewing the destination and input.

These three are executes: false, so even with the opt-in they print a [plan-only] note to stderr and the server returns a structured dispatch plan rather than a run.

Artifacts, evidence, runners, and billing

MCP registry

These read the server-advertised MCP tool registry and the per-org allowlist. They are unrelated to alti mcp serve, which is intercepted before either dispatcher and starts the local stdio server. See MCP.

One manifest action is unreachable

The manifest defines a one-word trace action for trace summaries. It cannot be invoked, because trace is claimed by the local parser as an engine namespace. alti trace reaches the local parser, finds no subcommand, and exits 2; alti trace --limit 5 reaches it too and exits 2 on an unknown argument.

The action is still present in alti commands output, which is why the count there is twenty-five while the reachable command count is twenty-four. If you enumerate the manifest programmatically, filter this one out.

Pick the Cloud workflow

Do not reuse an ID, hash or receipt from another workflow unless its contract explicitly accepts it. A reconnecting terminal is still the existing remote session; a lost submission reply is still a potentially existing job. Inspect state before creating a duplicate.