CLI ジョブと Cloud コマンド

概要

このページでは、ジョブの転送、ネイティブ DDS Cloud セッションとワークスペース操作、明示的な従来の HTTP サービスアダプター、および顧客マニフェストの 25 アクションを説明します。ネイティブ Evolve 操作には別の要求契約があります。

まず CLI コマンド体系 を読み、ルーティング規則、2 系統の終了コード、レシートエンベロープを確認してください。ローカルで解析されるエンジン名前空間については CLI エンジンコマンド、現在のリリースの制限については CLI コマンドリファレンス、マニフェストの読み方については アクションと機能の契約 を参照してください。

job 名前空間

job は、オフラインのクライアント事前検査と Job Service に対するジョブ転送を扱います。ローカルパーサが処理するため、-h が使用でき、どこにも接続する前に値の範囲を検査します。

8 個中 6 個のサブコマンドは --runner <local|cloud|private> を取り、既定値は cloud です。このフラグは 通信先の Job Service を選びます。rtl compile などのエンジンランナーフラグとは異なります。job readiness と job validate は --runner を一切持たず、ネットワークに接続しません。

<JOB_ID> と --artifact-id は、区切りの -- なしでハイフンで始められます。パーサはこれらの引数で先頭がハイフンの値を受け付けます。

次のコマンドの 2 つの範囲検査付きオプション：job wait。これらはサービスではなくパーサが検証します：

テキスト

$ 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

この場合の終了コードは 2 です。

job readiness

job readiness は認証情報やネットワークなしで応答します。このリリースでは固定された、パスを含まない投影です。すべてのコンポーネントが configured: false と ready: false を報告し、blockers 配列は完全です。

{
  "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"
  ]
}

終了コードは 0 です。ここで 0 は、準備状況への問いに回答したという意味であり、何かが準備できていることを意味しません。

job validate

job validate は、CLI で最初の成功を確認する に段階的に記載されたオフライン事前検査です。EngineJobV1 文書を --job から読み取ります（--job が - または省略の場合は標準入力）。正確な Cloud CPU RTL クライアントエンベロープに照らして検査し、ローカルソースファイル 1 件をハッシュ化します。認証情報を解決せず、クライアントを作成せず、どこにも接続しません。

レシートスキーマは altifigence.cli.engine-job-preflight.v1 です。成功時は status が client_preflight_valid、submitted が false, server_authority_verified が false, job_schema が altifigence.engine.job.v1, execution_placement が cloud、operation ブロックが rtl-engine / analyze / rtl-analysis-request.v1、source ブロックが workspace_uri, sha256 と size_bytes を持ちます。

ジョブ文書の読み取り上限は厳密に 8388608 バイトです。これを超えると次のエラーで失敗します：EngineJobV1 JSON exceeds the CLI limit.

Cloud への送信にはソースの明示的なオプトインが必要

次を指定する場合：--runner cloud。job submit と analyze run は、ソースアップロードの 3 オプションすべてを一緒に指定する必要があります。このリリースでは、これらなしで Cloud CPU RTL ジョブを送信する方法はありません：

テキスト

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

終了コードは 1 です。--allow-source-upload があって --workspace-root がない場合のメッセージは --workspace-root is required with --allow-source-upload. です。--source も同様です。

--workspace-root は絶対パスでなければなりません。--source は <workspace-root>/inputs 配下のポータブルな相対パスです。

Cloud アーティファクトのダウンロードには別のオプトインが必要

コマンド job result で --runner cloud を指定する場合、3 つのアーティファクトオプションは 1 組です。1 つでも指定するとダウンロードモードになり、3 つすべてが必須になります：

• 次を指定しない場合：--allow-artifact-download：Cloud Engine Job artifact download is disabled; pass --allow-artifact-download explicitly.

• 次を指定しない場合：--artifact-id: --artifact-id is required with --allow-artifact-download.

• 次を指定しない場合：--output-dir: --output-dir is required with --allow-artifact-download.

--output-dir は絶対ディレクトリでなければなりません。--artifact-id は終端状態の EngineResultV1 の出力一覧から取得します。

ランナーごとの拒否

3 組のオプションは特定のランナーに限定され、それ以外では拒否されます。いずれも、プロセス開始や要求送信の前に判定されます。

古い local/private 経路は、廃止された alti-engine-job アダプターを指定しますが、これはリリースの 24 ランナー一覧に含まれません。受け付けられるランナー構文やエンドポイント変数があっても、local/private Job Service が提供されている証拠にはなりません。サービスとアカウントが有効な場合に限って組み込み Cloud 経路を使用するか、文書化された直接のローカルエンジンコマンドを使用してください。

機械可読のジョブエラー

job サブコマンドと、analyze run に --json を指定した呼び出しは、失敗時に単独のメッセージの代わりに構造化されたエラーエンベロープを出力します：

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

コード一覧は次のとおりです。

retryable は false で、このリリースの全コードに共通です。このエンベロープは job 名前空間と analyze run で出力されます。他のコマンド群は固有のエラー・レシート契約を使用します。コマンドリファレンス を参照してください。

analyze run と evolve run

analyze run と、明示的なネイティブ Evolve サブコマンドはローカルパーサに到達します。単語 1 つの顧客アクション analyze と evolve は別の契約です。

analyze run は job submit と同じオプション群を取り、同じ Cloud ソースアップロード規則に従います。違いは 1 つだけで、--runner を受け付けますが、cloud 以外はすべて拒否します。

テキスト

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

終了コードは 1 です。

evolve run は --runner も --project も引数の引き渡しも持ちません。要求文書 1 件を読み取り（--request - は標準入力）、同梱の alti-evolve エンジンに処理を渡します。エンジンの終了状態はそのまま返されます：

テキスト

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

この 2 は alti-evolve 自身の終了状態がそのまま返ったもので、CLI 引数エラーではありません。エンジンを解決できないインストールでは、同じコマンドは終了コード 127 と、status が unavailable のレシートを返します。

evolve capabilities, evolve analyze, evolve cx-search, evolve measured-ppa と evolve artifact もルーティングされています。例えば evolve analyze SAVED_RTL --top TOP [--project ABS] は保存済みソースを解析します。測定 PPA の受付・準備状況・事前検査は、測定 PPA を生成しません。

公開の GPU アクティビティ操作は compute rtl-evolve --request FILE_OR_DASH です。独自のネイティブ生成エンベロープと、明示的な CPU 参照・CUDA 方針を持ちます。エンジンコマンド を参照し、evolve run 要求をこの操作に転送しないでください。

Digital Design Studio Cloud

まず ide cloud login、次に ide cloud whoami を使用してネイティブセッションの ID を検証してください。refresh と logout はそのセッションを管理し、--session-dir は既定の代わりにプライベートなセッションを選択します。CLI 認証 を参照してください。

ide cloud contract --request FILE_OR_DASH は、型付きのプロジェクト・メンバー・ソース・ワークスペース要求をオフラインで検証します。ide cloud run --request FILE_OR_DASH は保存済みセッションを使い、ネイティブ API を通してその要求を送信します。ソースを含む要求には --allow-source-upload が必要です。契約検証は組織アクセスを与えず、サービスの現在の権限を置き換えることもありません。

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

実際の、許可された組織・プロジェクト UUID を使用してください。検索は --match-case, --whole-word、保守的な固定幅の --regex, --limit 1..500 と --timeout-seconds 1..120 を取ります。既存のスコープ付き files/read ルートと保存済み内容を使用し、上限は 500 ファイル、各 4 MiB、合計 16 MiB、出力 1 MiB です。マニフェスト・ヘッダー・世代の変更は、混在したスナップショットを無効にします。返される contentHash は読み取った正確な UTF-8 テキストをハッシュ化し、現在の Cloud 所有者では fileVersion と一致する必要があります。fileVersion と workspaceRevision は別々の CAS フィールドとして保持してください。

ターミナルへの接続は WebSocket 転送と現在の認可を保持します。stdout のバイトをストリーム配信し、状態はグローバルの --json を指定していても stderr に出力します。再開には --cursor を使用し、--cols 2..500, --rows 1..200 と --max-seconds 1..300 で接続を制限します。切断は、永続 PTY の終了要求ではありません。これは Cloud プロジェクトの実行であり、ローカル CLI シェルではありません。

従来の DDS Workspace Service

ide service は、明示的に設定された従来の HTTP ワークスペース所有者を対象とします。--endpoint または ALTI_STUDIO_ENDPOINT と既存の ALTI_STUDIO_SERVICE_SECRET を、呼び出し側の非公開環境に設定してください。ネイティブ Cloud セッション、ブラウザ Cookie、任意 URL・本文の転送で代替することはありません。この説明は従来のサービスアダプターについてのもので、現在のネイティブデスクトップ UI がこれらのエンドポイントを使う、あるいは公開本番サービスが有効だという主張ではありません。

検索は --match-case, --whole-word、保守的な固定幅の --regex と --limit 1..1000（既定値 80）を受け付けます。正規表現の受付は、所有者の JavaScript 構文の一部を意図的に受け付け、グループ、選択、量指定子を拒否します。バックエンドでの一致処理はサービスの責任です。

置換は、必須の query, replacement, paths: [one portable path] と expectedHashes: {same path: 64 hex digits} を持つ閉じた JSON オブジェクトを取ります。任意の options には、ブール値の matchCase, regex と wholeWord だけを含められます。任意の match は、同じ path と、1 始まりの整数 line/column（1～4194305）を含みます。match を省略すると、ワークスペース全体ではなく選択したファイル内で置換します。この同じサービスの現在の結果からハッシュを取得してください。

要求は、JSON エンコードと置換テキストを含めて最大 64 KiB です。未知のフィールド、ハッシュキー・パスの不一致、無効な索引、トラバーサル、サーバー境界外のリンク、保護されたメタデータや検索対象外パスには対応しません。CLI は HTTP 通信前に無効な形式と保護パスを拒否し、ファイルシステムの所有権とリンク検査はサービスが担当します。ローカルワークスペースの置換は行いません。

応答は最大 8 MiB です。--timeout-seconds 1..3600 は HTTP 全体の期限を設定します（既定値 30）。リダイレクトと自動再試行は無効です。altifigence.dds.service-receipt.v1 は、成功した DELETE の空の応答も含めて HTTP 状態と本文を保持します。409 は競合のままです。バックエンドの CAS と原子性は、複数バックエンドにまたがる保証ではありません。そのサービスの契約なしに、期待するハッシュをローカルや Cloud の内容ハッシュで代用してはなりません。

アクションマニフェスト

ローカルパーサが処理しないものはすべてマニフェストディスパッチャーに渡され、コマンドパスを組み込みの customer-tools.v1.json と照合します。alti commands はマニフェスト全体を 25 エントリの JSON 配列 1 つとして表示し、認証情報なしで終了コード 0 で終了します。

22 エントリは executes: true と記されています。3 つの analyze, evolve と verify は executes: false で、処理を渡す前に [plan-only] の注記を表示します。この同じ 3 アクションだけがソースバイトを持ち、--allow-source-upload によって制限されます。

25 アクション中 14 個は remote_core プロファイルも持ち、残りは local_extended のみです。このプロファイルが利用可否にとって何を意味するかは アクションと機能の契約 に記載されています。

以下のすべてのアクションは、クライアントを構築する前にプロセス環境から ALTI_TOKEN と ALTI_ORG_ID を読み取り、どちらかがなければ終了コード 1 で失敗します：

テキスト

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

一覧アクションに共通のオプション

複数のアクションで共通のページング形式を使用します：--limit <INTEGER> は範囲 1..=100、加えて --cursor <STRING> です。どちらも要求前にローカルで検証します：

テキスト

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

この場合の終了コードは 2 です。未知のフラグ（Unknown option(s): --limti）、必須オプションの欠落（Missing required option(s): --projectId）、列挙値以外の値（Invalid value for --visibility: expected one of public, private.）でも同じです。

ワークスペースとプロジェクト

対話型 RTL

chat models は chat より先に照合されます。ディスパッチャーは、最長の一致コマンドパスを優先するためです。alti chat はサーバー側でクレジットにより制限され、監査ログに記録されます。

見積もりと計画のみのアクション

--rtl と --testbench はインラインのソース文字列で、それぞれ厳密に 1048576 バイトまでとし、ローカルで検査します：

テキスト

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

終了コードは 2 です。--allow-source-upload がなければ、これら 3 アクションはいずれも終了コード 4 で、クライアント構築前に終了します：

テキスト

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

これら 3 アクションは executes: false なので、オプトインしても [plan-only] の注記を stderr に表示し、サーバーは実行ではなく構造化された処理計画を返します。

アーティファクト、根拠、ランナー、請求

MCP レジストリ

これらはサーバーが通知する MCP ツールレジストリと組織ごとの許可リストを読み取ります。alti mcp serve とは無関係です。このコマンドは、どちらのディスパッチャーよりも前で捕捉され、ローカル stdio サーバーを起動します。MCP を参照してください。

マニフェスト内の 1 アクションには到達できません

マニフェストには、単語 1 つの trace アクションがトレース要約用に定義されていますが、呼び出せません。trace はローカルパーサがエンジン名前空間として処理するためです。alti trace はローカルパーサに到達し、サブコマンドがないため終了コード 2 で終了します。alti trace --limit 5 も到達しますが、未知の引数により終了コード 2 で終了します。

このアクションは alti commands の出力には残るため、表示上の数は 25、到達可能なコマンド数は 24 です。プログラムでマニフェストを列挙する場合は、このアクションを除外してください。

Cloud ワークフローを選ぶ

契約が明示的に受け付けない限り、別のワークフローの ID、ハッシュ、レシートを再利用しないでください。再接続中のターミナルは既存のリモートセッションであり、送信応答を失ったジョブは存在している可能性があります。重複を作る前に状態を確認してください。