CLI コマンドリファレンス — Altifigence Documentation

CLI コマンドの出力、実行記録、構造化エラー、終了状態を正しく解釈します。

概要

インストール済みバイナリーは、検証とインストールの後に使います。このリファレンスは、コマンドの検出、実行結果、事前検証の記録、サービスの応答を区別します。

アクションマニフェスト

成功時には、1 つの JSON 配列が出力されます。各項目には、name, description, inputSchema, executes、classがあります。組み込みの顧客向けマニフェストには 25 アクションがあり、そのうち 22 個は executes: trueを持ちます。一方、altifigence.analyze.run, altifigence.evolve.launch、altifigence.verify.runは計画のみです。ネイティブ CLI サブコマンドには、この顧客向けマニフェストとは別に、各末端コマンドのヘルプがあります。サービス操作が認可され、準備できているかは、サーバーの応答で決まります。

ネイティブ引数には、末端コマンドのヘルプを使います：

alti commands

alti xls upstream run --help
alti compute rtl-evolve --help
alti ide workspace hierarchy-plan --help
alti ide cloud search --help
alti ide service workspace replace --help

オフラインのジョブ事前検証

ソースとエンベロープを CLI の最初の成功で準備し、次を実行します：

成功スキーマは altifigence.cli.engine-job-preflight.v1です。submitted: falseとserver_authority_verified: falseが必須です。ソースハッシュとジョブ形式はローカルで確認されましたが、ジョブは送信も実行もされていません。エンベロープが要求する execution_placementで、この事実は変わりません。

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

JSON エラー契約

失敗した --json job validateは、stdout に成功記録を出力せず、stderr に altifigence.cli.error.v1オブジェクトを出力します：

利用できる場合は、error.codeを使います。ほかのコマンド系列には独自のエラースキーマがあり、このエンベロープがすべての CLI コマンドに適用されると考えないでください。

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

終了状態

状態	解釈
`0`	選択したコマンドが完了。結果を読み、準備状態、事前検証、計画、実行のどれを報告しているか判断する
`1`	CLI のランタイム、検証、転送、インストールの失敗。サービスの失敗には HTTP 応答を含む場合がある
`2`	不正な引数、または転送／エンジン起動前に拒否されたリクエスト。エンジンがこの状態を返す場合もある
`3`	顧客向けマニフェスト経路で予約されたクラス拒否。エンジンが同じ番号を別の意味で使う場合がある
`4`	顧客向けマニフェストの拒否。利用できないトップレベルのログイン／ID、またはソースアップロード同意の欠落を含む
`126`	エンジン起動またはインストール済み認証の失敗
`127`	必要なエンジン実行ファイルが利用できない
その他のゼロ以外	子エンジン独自の状態が、そのまま返された可能性がある

stdout を解析する前に、必ず終了状態を確認し、stderr は別に保持してください。空または不完全な出力ファイルは成功結果ではありません。保存した計画は適用済みトランザクションではなく、サーバーの受理はジョブ完了ではありません。

エンジンコマンド：実際に実行される内容

XLS、compute、native DDS アダプターは、固定された同梱の隣接実行ファイルを使います。インストール後の実行では、関連ランナーを署名済みリリース記録に照らして認証します。別の実行ファイルを PATHに追加しても、必須の隣接実行ファイルの欠落は修復できません。古い互換コマンドの一部は、文書化されたリゾルバー動作を保持します。詳しくは、コマンド体系を参照してください。

次を使わない場合：--json。エンジンの stdout が転送されるため、不透明なネイティブ計画を直接保存できます。一方、--jsonを使うと、エンジン呼び出しは通常、altifigence.local-engine-execution.v1を生成し、その stdoutとstderrフィールドは、子プロセスのストリームを文字列として含みます。内部の結果を別途解析してください。

ファイルと階層の計画では、ネイティブ計画の結果全体を、対応する apply コマンドに渡します。外側の CLI エンベロープや計画ダイジェストだけを渡してはいけません。ネイティブバックエンドは、現在のファイルハッシュとトランザクション条件を検証します。

サービスとストリーム出力

ide serviceは、altifigence.dds.service-receipt.v1を、operation, ok, httpStatusと上限付きレスポンスの bodyとともに返します。置換からの HTTP 409は競合のままで、再試行されません。成功した DELETE の空レスポンスは空のまま保持し、架空のサーバー JSON オブジェクトには変換しません。

ネイティブ DDS 検索と Cloud 検索は、それぞれ独自の一致／内容の証拠を公開します。書き込み先のバックエンドが提供する識別情報を使ってください。別の検索バックエンドで計算したハッシュが、自動的に有効な CAS トークンになるわけではありません。

ide cloud terminalは、ターミナルバイト列を stdout、接続状態を stderr にストリーム出力します。グローバルの --jsonを使っても、単一の JSON 記録にはなりません。接続期間に上限を設け、再接続する予定がある場合はカーソルを保持します。

--json release installと--json release uninstallは、altifigence.cli.release-bootstrap.v1を、operation, ok、exitCodeとともに出力します。インストーラー診断は stderr に出ます。成功エンベロープが生成される前に、検証や権限の失敗が起きる場合があります。

自動化用に結果を取得する

呼び出しごとに、新しい出力ディレクトリを選びます。stdout と stderr を別々に保存し、終了状態を直ちに取得して、終了コードがゼロの後にだけ成功スキーマを解析します。エンジンエンベロープでは、コマンド契約に JSON を含むと記載されている場合にだけ、stdout文字列をネイティブ文書として解析します。

plan／apply のワークフローでは、完全な生のネイティブ計画を保持し、同じプロジェクトを使います。apply 前に、対象ファイルと現在のハッシュを確認してください。競合には、新しい読み取りとレビュー済み計画が必要です。ハッシュチェックを捨てる理由にはなりません。再現可能なローカルチェックは、自動化と CIを参照してください。