CLIリファレンス

actql は、コマンドラインからプログラムを動かすコマンドです。検査し、計画を見て、実行し、書き込もうとしている内容を承認し、Runが終わるまで追いかけます。このページにはすべてのコマンドを載せています。手順に沿った最初の実行はクイックスタートから始めてください。

npm install -g actql
actql version

基本の流れCopy Anchor Link

actql check churn-risk.aql        # 静的な検査。何も読まない
actql explain churn-risk.aql      # 計画。何も読まない
actql run churn-risk.aql          # 読み、計算し、書く（またはCheckpointで止まる）
actql status run_…                # Runの現在の状態

ポリシーが書き込みの判断を保留すると、run はRunとCheckpointの参照を表示し、Runを waiting_checkpoint の状態にして終了します。approve か reject で判断し、status で追いかけます。

actql approve ckpt_…
actql status run_… --watch

run が入力を求めて止まることはありません。Runが安定した状態、つまり判断待ち、突き合わせ待ち、または終了に達した時点で戻るので、自動化から安全に呼べます。--json を付けると、その状態をデータとして受け取れます。

似た2つのフラグは意味が違います。--json はコマンドの結果（Runの状態、検査の報告、計画）をJSONで出し、--format は sql、aql、result が出すResultのレコードの形式（table、json、jsonl、csv）を選びます。

プロジェクトを始めるCopy Anchor Link

actql init [--template churn-risk-mock] [<directory>]

init はプロジェクトを作ります。actql.config.json、Connectorとmodel taskのファイル、ローカルの署名鍵を持つ .actql のStore、そしてテンプレートを指定すれば、認証情報なしで動くmockのフィクスチャ付きの完全なプログラムです。クイックスタートは actql init --template churn-risk-mock から始まります。

クエリをすぐ実行するCopy Anchor Link

actql sql <query> [--params <file>] [--format <table|json|jsonl|csv>] [--output <file>]
actql aql <query> [--params <file>] [--format <table|json|jsonl|csv>] [--output <file>]

$ actql sql "SELECT id, name FROM crm.accounts WHERE owner = 'kim' LIMIT 3"
id    name
----  -----------
001…  Acme
002…  Globex
003…  Initech

sql は通常の SELECT を、aql はPipe構文（FROM … |> …）を受け取ります。どちらも設定済みのConnectorを通して読み、結果を表示します（既定は table 形式）。ライブラリの sql() と aql() のコマンドライン版で、読み取り専用です。EffectもCheckpointもありません。Effectを含むクエリは拒否されるので、プログラムのファイルに書いて run で実行してください。

設定Copy Anchor Link

CLIは、カレントディレクトリから親へ向かって actql.config.json を探します。ファイル内のパスは、そのファイルからの相対パスです。

{
  "version": "actql-config/0.1",
  "connectors": "./connectors.json",
  "model_tasks": "./model-tasks.json",
  "lock": "./actql.lock.json",
  "state_dir": "./.actql",
  "profile": "mock"
}

誰が何をしてよいか、誰が承認できるか（account_config、effect_policy、signers）はHostの設定です。~/.config/actql/host.json か --host-config で指定したファイルから読み、プロジェクトのファイルからは読みません（ローカルとリモートのHost）。どのコマンドも --config <file> で別のプロジェクトのファイルを指定できます。コマンドのフラグはファイルより優先されます。完全なスキーマは設定リファレンスにあります。

基本コマンドCopy Anchor Link

actql check <program> [--params <file>] [--bindings <file>] [--json] [--redact]
actql explain [<program>] [--params <file>] [--input <name=file>] [--stop-before <boundary>] [--verbose] [--json] [--redact]
actql explain --run <run> [--verbose] [--json] [--redact]
actql run <program> [--params <file>] [--input <name=file>] [--stop-before <boundary>]
                    [--deliver <result=format:file>] [--output <file>] [--receipt <file>] [--json]

check は、Hostが公開している定義に照らしてプログラムを検査します。名前、型、model task、Effectの対象、必要になる権限です。業務データは読まず、プロバイダーも呼びません。プログラムが有効なら終了コード0、無効なら1で終わり、理由をコードと行番号つきで1つずつ表示します（Checkの理由カタログ）。有効であることと、いまここで実行できることは別です。報告には、プログラムが runnable かどうかと、そうでない理由（値がまだ渡されていないパラメーター、このHostにないCapability、登録されていないmodel task）も入ります。run するかどうかは、終了コードではなくこの項目を読んで決めてください。

explain は計画を表示します。演算ごとに使うSiteとEngine、何が読み取り元にプッシュダウンされるか、どこでLLMを呼ぶか、Runがどこで承認のために止まり得るかです。JOINのエンジンのようにデータ次第で決まる選択は、実行時に決まると表示します。Runは作らず、業務データも読まず、LLMも呼びません。run と同じ入力を受け取ります。--verbose を付けると、条件ごとの判断と、保留中の選択の選択肢を追加で表示します。explain --run <run> は、終わったRunや待機中のRunが実際に何を使ったかを、その記録から表示します。詳しくはPlanとプッシュダウンを参照してください。

run は、プログラムを検査してから、永続的なRunとして実行します。オプション：

run はResultを公開してRunの状態を報告するだけで、レコードそのものは出力しません。レコードは result で読むか、ファイルに書き出してください。

3つのコマンドはいずれも、設定したファイルを上書きする --connectors、--model-tasks、--lock と、入力を事前に結び付けた --bindings <file> を受け付けます。

Runに対する操作Copy Anchor Link

actql status <run> [--watch [--until <state>]] [--timeout <duration>] [--json] [--redact]
actql approve <checkpoint> [--signer <id>] [--wait] [--json]
actql reject <checkpoint> [--signer <id>] [--json]
actql cancel <run> [--json]
actql reconcile <run> [--effect <name>] [--json]
actql result <run> [--result <name>] [--format <json|jsonl|csv>] [--output <file>]
                   [--deliver <result=format:file>] [--receipt <file>] [--json]

status は、Runの状態、待っている場合はそのCheckpoint、そしてEffectの項目ごとの結果（出そろってから）を1回読んで表示します。外部システムには何も送りません。--watch は変化を表示し、あなたの対応が必要な次の状態、つまり waiting_checkpoint、needs_reconciliation、または最終状態で戻ります。--watch --until final は承認をまたいで最後まで追いかけ、--timeout はどちらの待ち時間も区切ります。Runが始まる前にポリシーが保留した要求は held として、そのCheckpointとともに表示され、approve で同じように解決できます。

approve と reject は、Checkpointに答えます。Runの中のCheckpointも、Runが始まる前に要求を保留したCheckpointも同じです。答えは、Checkpointが持つプレビューそのものに結び付けられます。signers を設定している場合は --signer（または既定の承認者）で署名されます。承認者を設定していないローカルのHostでは、actql init が作ったローカルの鍵で署名されます。この鍵が示すのはマシンのユーザーであって、本人確認された人ではありません。承認すると、終わった処理をやり直すことなく同じRunが続きます。--wait を付けると続きを追いかけます。却下すると、Runは何も送らずに cancelled で終わります（それ以前の書き込みの結果がまだ不明なら needs_reconciliation）。

cancel は、Runに停止を求めます。停止が確認され、結果が不明なものがなくなった時点で cancelled になります。適用済みの書き込みはそのまま残ります。

reconcile は、不明なEffectの結果を外部システムに確認して確定させるようHostに求めます。確認にはRunに記録されたConnectorと契約を使い、別の接続に向けるフラグはありません。書き込みを再送することはありません。それでも不明なままなら、Runは needs_reconciliation にとどまり、試みたことが記録されます。

result は、終わったRunの名前付きResultを読みます。--format で標準出力に、--output / --deliver でファイルに出します。--receipt は、verify output で照合するための配信の受領記録を保存します。

$ actql result run_… --result updates --format jsonl
{"id":"001Acme","notes":"Evaluating a competitor; usage down since June.","active_users":4,"trend":"down","risk":{"outcome":"ok","value":{"level":"high","reason":"falling usage and a competitor evaluation"}}}

個々の操作Copy Anchor Link

1つのEffectの結果を単独で扱う必要があるときは、次のコマンドを使います。

actql operation status <operation> [--json]
actql operation reconcile <receipt> [--effect <name>] [--output <file>]
actql operation cancel <operation> [--json]

探索Copy Anchor Link

設定したConnectorとmodel taskが公開しているもの：

actql catalog list [--json]
actql catalog show [<connector-id>] [--json]
actql catalog refresh <connector-id> [--json]
actql model-task list [--json]
actql model-task show <model-task-id> [--json]
actql discovery describe [--json]
actql discovery list --snapshot <cid> [--kind <kind>] [--selector <selector>] [--cursor <cursor>] [--page-size <count>] [--json]
actql discovery read --snapshot <cid> --kind <kind> --selector <selector> --content-cid <cid> [--json]

catalog show salesforce は、その接続についてプログラムが頼りにできるものをすべて表示します。列・型・キー付きの読み取り元、リソースごとのEffectとそのプレビューの強さ、入力付きの操作、Capability、読み書きごとに必要な権限です（Connector）。読むのはHostが保存しているCatalogです。catalog refresh <connector-id> は、外部システムに現在のメタデータを問い合わせます。

言語そのものについて：

actql op list [--family <family>] [--output <carrier>] [--json]
actql op show <operation> [--json]
actql op search <words...> [--json]
actql expr list [--category <category>] [--json]
actql expr show <expression> [--json]
actql expr search <words...> [--json]
actql grammar [--json]
actql schema

op はPipeの演算、expr は関数、grammar は受け付ける構文、schema はプログラムモデルのJSONスキーマを表示します。エージェントは、推測せずにこれらを参照します。

整合性Copy Anchor Link

actql lock [--output <file>]
actql verify lock <lock> [--json]
actql verify output <receipt> <output> [--json]
actql doctor [--connect] [--json]
actql version

lock は、プロジェクトが使うすべてのConnectorとmodel taskのバージョンを固定した actql.lock.json を書き出します。verify lock は、インストールされているものがまだそれと一致するかを確かめます。verify output は、書き出したResultのファイルを受領記録と照合します。doctor は、インストール状況、見つかった設定、そのどちらかの問題を、どこにも接続せずに報告します。doctor --connect は、設定された各接続とプロバイダーへの疎通も試します。

プロファイルCopy Anchor Link

--profile mock（または設定の "profile": "mock"）は、mockのConnectorとmockのLLMに対してプログラムを実行します。レコードとLLMの答えは、設定の mock に指定したファイルから来ます。どのmock Connectorも、書き込みはどこにも送らずに記録するだけです。そのため、認証情報なしでプログラムを開発し、CIでテストし、デモできます。Checkpoint、承認、statusの流れは、本物のシステムと同じです。

出力と終了コードCopy Anchor Link

コマンドは、既定では人向けの要約を、--json を付けると安定したJSONを表示します。進捗は標準エラー出力に、結果は標準出力か指定したファイルに出ます。--redact は、システム名、リソース名、パラメーターの値、プレビューの値を安定したプレースホルダーに置き換え、構造、コード、位置は残します。出力を共有するときに付けてください。

エラーには、人向けの出力でもJSONでも、安定した ACTQL_E_* のコードが付きます。未知のコマンド、未知のオプション、余分な引数はエラーです。オプションはプログラムのパスの前でも後ろでも書けます。

次に読むCopy Anchor Link

• プログラムを書く：言語
• Effectと承認：Checkpointが持つものと、誰が答えるか
• Runのライフサイクルと復旧：状態、中断、不明な結果
• 設定リファレンス：CLIが読むすべてのファイル