CLIリファレンス

aachatのCLIは3つのバイナリで役割を分ける。どのバイナリを案内すべきかは、ユーザー（またはagent）がどこにいるかで決まる。

引数の正本は各コマンドの--helpである。このページはインストール済みCLIの--helpとコードで確認した内容をまとめる。手元のCLIが古い場合はaachat updateで更新し、aachat --versionと対象コマンドの--helpを確認する。

出力形式

aachat

aachat の Project 選択子は名前単独と <team>/<project> の両方を受け付けます。たとえば aachat find --project team/project と aachat find --project project --team team は同じ対象を選択します。修飾した Team が --team や同じコマンド内の別の Project 選択子と矛盾する場合は、リクエスト前に拒否します（conflicting_arguments、exit 2）。空の選択子・空の片側・複数の / は入力エラーです（invalid_argument、exit 2）。名前単独では既存の検索範囲や接続 repo の Team 解決を維持し、AA_TEAM を新たなデフォルトにしません。project create の新規名は名前定義のままで、--parent のみが選択子です。Session 内の修飾形による send には、CLI と対応する server の両方の更新が必要です。

ほぼすべてのコマンドが、stdoutに一つのJSON envelopeを返す。成功は{"ok": true, "data": {...}}、失敗は{"ok": false, "error": {"code": ..., "message": ...}}の形で、warningsとnext_actionsが付くことがある。next_actionsがあれば読む。aachat tag listだけは既定でtextを返し、--jsonでJSONに切り替える。--helpと--versionはtextである。

JSON envelopeを返さない例外は次の5つである。

終了statusは、成功が0、実行失敗が1、引数の不足・不正が2である。終了codeが0でも、診断内のfailed/skippedがhealthyになるわけではない。statusのfieldやdoctor --view checksの各checkを読む。

一覧は既定20件・最大100件で、続きはdata.next_page、個別の本文はdetail_readから読む。どちらもcommand locator（{"kind": "command", "program": ..., "argv": [...]}）で、programにargvをそのまま渡して実行する。shell文字列へ結合しない（ページング）。

本文を読むコマンド（project read --message、project document --path、ask show、db schemaなど）はpreviewを返す。全文が必要なときだけ次を使う。

Agent Session内（環境変数AA_SESSION_IDがある）では、人間の権限で動く次のaachat操作をinvalid_argumentで拒否する。代替がある場合はnext_actionsが対応するchatコマンドかSession外での実行を示す。project ensureやLead変更などはメッセージだけを返す。ask answer / ask cancel、db、trigger、workflow、skill feedback、session permission / schedule / compact、projectのensure・content catalog・メッセージ変更・delete / reparent / assign / unassign・Lead変更や--cancel-runsなどが対象である。Session内のaachat session listの行参照はchat session show <id> --project <team>/<project>を指し、session read --decisionなどの外部専用viewも拒否される。

chat

chatはすべての通常コマンドで、stdoutに一つのJSONを返す。

• 成功: {"ok": true, "data": {...}}
• 失敗: {"ok": false, "error": {"code": ..., "message": ..., ...}, "data": {...}}（dataは部分結果があるときだけ）

終了statusは、成功が0、実行失敗が1、入力・引数の不正が2である。失敗のerrorには、対象のprojectやfield、候補のcandidates、次に実行できるcommands（command locatorの配列）、hintが付くことがある。--helpと--versionはtextで、成功終了する。ok: trueはコマンドが受け付けられたことを示し、SessionやRunの成功を意味しない。

一覧はdata.next_page（最後はnull）と、各itemのdetail_readをcommand locator {"kind": "command", "program": "chat", "argv": [...]}で返す。argvを配列のまま実行する。path locatorでbase: workspaceのものはAA_WS_DIRから解決する。truncatedや読んでいない続きを空と解釈しない。

chatはsessionのスコープ内で動くため--teamフラグはない。Projectの指定は各コマンドのhelpに従い、--projectには<team>/<project>またはproject slugを渡す。current sessionが扱えないProjectは拒否される。

認証・診断・更新

aachat auth login                # ローカルの gh 認証から短命JWTを発行・キャッシュ（~/aachat/.run/tokens/user.jwt）
aachat auth status               # サインイン状態の確認
aachat auth logout               # 保存済み認証情報の削除
aachat status                    # connection（repo接続・Team）・auth・daemon・projectionの現在状態（Launch Reportは含まない）
aachat doctor [--view checks]    # workspace・投影・共通依存の期限付き読取専用診断
aachat update                    # aachat自体の更新

gh が認証済みなら auth login は非対話で完了する（信頼境界）。

問題が起きたら aachat support を起動してください。doctorはsupportなどのagentが使う診断APIです。

doctorは検査ごとの期限と出力上限を設けた読取専用診断で、stdoutにJSONを一つ返す。既定のdata.diagnostics.issuesは非passの項目、--view checksのchecksは全項目を返し、countsは全項目を数える。各項目はid・required・state・reasonに加え、category（blocker・preservation・maintenance・information）、code、target、observed_at、next_actions、recheckを持つ。同じidの異なる対象が並ぶことがある。data.observed_atは集約時刻で、同期項目のsource_observed_at・last_sync_at・runtime_stateは保存記録と今回の観測を区別する。容量・artifactの値が不明ならnullのまま返す。

workspace検査の予算はworkerのprocess group停止・回収用500 msを含む20秒。時間切れでも、完了したフォルダ単位の指摘と最新の空き容量観測は残る。rootを対象とするsession_workspace_maintenanceのsummaryにはcoverageが付き、entries_observed・entries_reported・entries_verified・enumeration_complete・total_entries・unverified_entries・in_progress_path・identities_complete・completeを返す。reportedはエラー結果を含み、verifiedは確定した保全上の問題も含む。列挙未完了なら全件数と未確認件数はnull。summaryのpassは観測範囲の分類・計測が完了した意味で、問題なしを意味しない。capacityのfilesystem_observationはobserved_at・free_bytes・required_headroom_bytesを全体計測とは独立に返す。未完了の全体容量はnullのままで、空き容量不足はfailとなる。逐次観測であり原子的なsnapshotではない。表示された作業を保全し、中断対象を絞って調査する。同じ全量検査の反復で必ず網羅できるとは限らない。

overallは障害があればissues_found、それ以外でunknown（任意検査を含む）や必須の未実施検査があればincomplete、保全・保守の指摘だけならattention_needed、残りはhealthyとなる。正当な対象外のnot_applicableは未完了扱いにしない。healthyは実施範囲で指摘がないという意味で、providerの認証・モデル呼出や現在の同期成功を保証しない。

診断と集約が成功すれば、指摘や通常のtimeoutがあってもok:true・終了code 0となる。中断・親の実行失敗・子プロセス回収未確認はok:false・終了code 1、引数不正は2。中断や回収未確認でも取得済み診断はdataに残る。走査が終わらなければ全pathや件数は確定しない。workspace診断は実行中Sessionの保護を評価せず、削除許可にはならない。対象の作業を保全し、next_actionsとrecheckで確認する。起動・restart・認証変更の案内は人間の承認を要する。

ランタイム

aachat up [--if-stopped] [--events]   # 常駐runtimeを起動する
aachat launcher status                # launcherのruntime状態を読む。何も起動しない
aachat launcher check-ready           # 選択homeのlauncher・daemon・host同期・認証付きAPIを10秒以内でread専用確認
aachat launcher start                 # macOS launchd経由でruntimeを一度起動する（macOSのみ）
aachat launcher stop                  # launcher経由で起動したruntimeを止める（macOSのみ）
aachat launcher request <id>          # native launcher向けのversion付き起動要求（旧Desktop 0.xが使用）
aachat support [--provider claude|codex] [--symptom <text>] [--receipt]            # 対話型サポート
aachat support recover-layout --root <absolute-aachat-root> --backup <new-backup-dir> [--apply --writers-stopped]   # 既定は旧layoutの確認のみ。--applyは全producer停止後に旧rootをbackupへ保存して切り替える
aachat support cleanup-retired-team-features [--inventory <absolute-json>] [--apply --writers-stopped]   # 既定はoffline検査のみ。applyで所有確認済みの廃止機能データを削除
aachat manage-agent [--receipt]       # agentの対話的管理（検索 / clone / カスタマイズ / スキル追加）

cleanup は認証・ネットワーク不要です。既定の inspect はファイルを変更しません。apply 前に旧 writer と自動再起動元をすべて止め、--writers-stopped で停止済みと明示します。home・登録 repo・inactive Session は常に検査し、--inventory は既知の recovery/cutover copy を追加します。未知・危険な root は保留します。inventory 完了・残存ゼロを確認してから再起動します。Wiki・Project・Workflow の draft は保持し、旧機能の編集を再送しません。

aachat supportにはターミナルと選択したCLIが必要です。既定はClaude Codeで、Codexは aachat support --provider codex で選択できます。Codex CLIの確認版は0.160.0です。自動切替は行わず、Codexはread-only・on-request・人間による個別承認で起動します。stdin/stdoutはTTY必須で、Codexの --receipt はstderrもTTY必須です。--symptomは任意（UTF-8で8 KiBまで）で、指定せず起動後に症状を伝えられます。引数はshell履歴に残り得るため、秘密情報を入れないでください。CLI同梱契約と初期診断を読み、Web契約は取得しません。契約とcontext（症状・診断を含む）は所有者専用の一時ディレクトリに保存し、子プロセスの終了・起動失敗後に除去します。異常終了時にはOSの一時ディレクトリに残る場合があります。子プロセスの終了成功だけでは問題解消を意味しません。

aachat upが常駐runtimeを所有する。通常のupは既存runtimeを置き換えて再起動し、up --if-stoppedは稼働中なら置き換えず成功終了する。起動時と、稼働中は1時間ごとに、実行中のagent turnがなくなるのを待って更新を確認する。新しいbinaryを導入すると再度idleを待ち、通常のshutdownを行って同じ引数で再execする。idle確認後に始まったturnは中断される場合があり、人間の応答待ち中に停止したSessionは自動再開されない。serverとのsync protocol不一致で止まった場合も、停止・保存の後に一度だけ更新し、版が変わっていれば再execする。途中で止まったSessionの続きは人間が選ぶ。再起動後はLaunch Reportを確認する（Environment）。

過去の個別Sessionワークスペースの不整合は保守警告として報告し、ホストや無関係なSessionの起動を止めない。作業場所は利用直前に再検査するため、問題のあるSessionの開始・再開は失敗する場合がある。既存の作業は保全し、自動修復や作り直しは行わない。共通領域やワークスペース親領域の検査失敗は引き続き起動を止める。up.logのLaunch Reportとaachat doctorで所見を確認し、修復手順はaachat supportで確認する。

runtimeのログは~/aachat/.run/logs/up.logである。daemonが起動を引き受けた時点から書かれ、起動ごとと10 MiBごとにup.log.1〜up.log.8へローテーションされる。ターミナルには分類済みの失敗と詳細ログの場所、同じ失敗の60秒ごとの要約、回復の記録が出る。RUST_LOGはターミナルとファイルの両方に効く。

aachat launcher check-readyはAACHAT_HOMEで選ばれたaachat home自身を検査し、現在の作業ディレクトリやSession workspaceの同期を代用しない。data.readiness（schema_version: 1）にobserved_at、state（ready / preparing / blocked）、reason、checks（launcher / daemon / projection / apiの各pass / fail / unknown）を返す。全項目がpassのときだけreadyになる。ok: trueだけでは準備完了を意味しない。認証キャッシュを更新せず、認証付きTeam一覧の内容や資格情報も返さない。期限超過や確認不能はunknownとして扱う。

aachat launcherはmacOS launchd経由でruntimeを起動・停止するCLIの入口で、旧Desktop 0.xの起動入口と同じ処理を使う。Desktopは起動時にガイドがaachat upやaachat launcherなどの通常のCLIを使って準備し、進行状況と必要な本人操作を表示する。準備完了はDesktop自身がlauncher check-readyで確認する。launcher startはmacOS launchdで一度だけruntimeを起動し、Desktopアプリを終了・更新してもruntimeは動き続ける。状態確認にはaachat statusかaachat launcher statusを使う。launchdが呼ぶ内部入口service-runは--helpに表示されない。起動結果（Launch Report）はaachat statusでは返らないので、up.logの=== Launch Report ===の節を読む。ターミナルでaachat upを起動した場合は、そのターミナルのCtrl+Cで止める（Desktop）。

repo接続

aachat init [--team <slug>]   # 現在のgit repoをteamに接続する

initは対話入力を待たない。所属Teamが複数ある場合はambiguous_teamと候補を返すので、--team <slug>を付けて再実行する。書き込みはそのrepo内のファイルと ~/aachat/.state/repo-connections/ のローカル記録のみ。repo外パスとsymlink越しの書き込みは拒否される。詳細は Connected Repo。

team

aachat team create <slug> [--repo <owner/repo>]   # 名前がslugと同じprivate teamを作る。--repo は任意のデフォルトworkspace repo
aachat team update <slug> --stdin                 # 明示した設定を一つのJSON objectから更新する
aachat team join <token>                          # 招待トークンで参加する
aachat team list [--limit N] [--cursor <cursor>]  # 所属teamの一覧
aachat team show <slug> [--context]               # teamの詳細

agent

--runtime に指定できる値は claude-acp と codex-acp。

aachat agent list [--mine] [--limit N] [--cursor <cursor>]
aachat agent show <agent> [--view config|assignments|sessions] [--limit N] [--cursor <cursor>]
aachat agent create <name> [--repo <owner/repo>] [--description <text>] [--runtime claude-acp|codex-acp]
aachat agent ensure <name> [--repo <owner/repo>] [--description <text>] [--runtime claude-acp|codex-acp]
aachat agent ensure <name> --source <owner/repo>
aachat agent update <name> [--repo <owner/repo>] [--dormant | --no-dormant] [--runtime claude-acp|codex-acp]
aachat agent delete <name> --yes
aachat agent search [query] [--sort popular|recent|stars] [--limit N] [--cursor <cursor>]   # Discoverの公開agentを検索
aachat agent show-public <owner/repo> [--view readme|skills] [--full | --output <new-file>]
aachat agent clone <owner/repo> [--name <name>]   # 公開agentを自分のアカウントに複製

• agent createで--repoを省略すると、その場でGitHub CLIのgh repo create --templateによりprivateなagent repoをtemplateから作る。--repoなしで登録されたAgentの初回aachat upも同じである。そのためghのinstallとloginが必要になる。CLIでは表示名は設定されず、WebUIではhandleが表示される（表示名は後からEdit display nameで付ける）
• agent deleteは、そのAgentに稼働中のSessionやWorkflow Stepがあると停止を要求し、409（“The Agent still has active Sessions or Workflow Steps. … Retry Agent deletion after termination is confirmed.”）を返す。停止を確認してから再実行する。削除後もDM ProjectとSession履歴は残る
• agent clone <owner/repo> [--name <handle>]は、WebのDiscoverからのcloneが失敗したときの代替としても案内される
• agent ensureは既存Agentを変更せず返す。存在しない場合は--sourceでcloneするか、repo/description/runtimeの作成optionを使う。--sourceとこれらのoptionは同時に指定できない
• agent update --dormantのAgentはaachat upで起動されない。--runtimeは今後のSession起動の下書きで使う既定Runtimeを変える
• agent show --view sessionsのSession件数は、所有者から見える稼働中と最近失敗したSessionで、全履歴ではない

環境承認とcatalog公開・導入

aachat env                                   # env list と同じ要約を返す
aachat env --interactive                     # 対話型の設定UI（サブコマンドとは併用不可）
aachat env list [--all] [--name <NAME>] [--owner <owner>] [--view summary|requesters] [--limit N] [--cursor <cursor>]
aachat env approve <agent> <NAME> [--destination local-keychain|local-env]
aachat env adopt                             # 旧local設定の採用（人間の対話terminalのみ）
aachat env keychain-check
aachat env default --destination local-keychain|local-env
aachat env keychain-access --name <NAME> [--name <NAME> ...] [--reauthorize]
aachat env revoke <agent> <NAME>

aachat publish <agent> [--name <text>] [--description <text>] [--tag <tag>]... [--go-public]
aachat skill publish .agents/skills/<skill-name> --agent <name> [--go-public]
aachat skill sync <catalog-id>
aachat skill unpublish <catalog-id>
aachat skill install <catalog-id> --agent <name>

aachat plugin publish (<owner/repo> | <checkout-path> --agent <name>) [--headline-ja <text>] [--headline-en <text>] [--description-ja <text>] [--description-en <text>] [--tag <key>]... [--go-public]
aachat plugin sync <owner/repo>
aachat plugin unpublish <owner/repo>
aachat plugin install <catalog-id> --agent <name>
aachat plugin remove <catalog-id> --agent <name>

envはlocalの名前単位の承認を管理し、serverへsecret値を保存する操作ではない。approveはproviderに値がある、現在要求されている名前だけを、指定した保存先（local-keychainはmacOSのKeychain、local-envは.env）からAgentへ使用許可する。--destinationを省略すると保存先を対話で尋ねるため、stdinとstdoutがterminalで、Agent Sessionの外である必要がある。非対話で使うときは--destinationを指定する。revokeしてもproviderの値は削除しない。adoptは使用許可ではなく、Local setup requiredのときに旧local設定をschema 2の管理設定へ採用する操作である。認証済みの人間がAgent Sessionの外の対話terminalで実行し、表示されたpath・owner・許可を確認してadoptと入力する（Environment）。

env keychain-checkは、setup・認証・対象Mac接続後に、署名済みmacOS配布版で非秘密の確認用項目を作成・別helperで読取・削除します。引数や秘密値入力は不要で、env設定・bindingを変更しません。同じ明示AACHAT_HOMEとaachat絶対パスを使い、JSONのdata.target.root_idをWebUIのcomputer_idと照合してください。status:readyは現時点の確認だけです。準備失敗もstatus:failedとcode、確定前ならtarget:nullを返します。cleanup失敗やstdout失敗はnonzeroです。通常操作30秒と独立cleanup10秒に加えてhelper回収時間が必要な場合があり、全体40秒の終了保証ではありません。

env default --destinationは既存schema 2の登録済み保存先だけを選べます。本人Terminal（stdin/stdoutがTTY、AA_SESSION_IDなし）でroot・owner・変更前後を確認し、yesで確定します。値・保存先定義・Agent権限を保持し、既定だけを変更します。未設定・旧形式はlocal_setup_required、Keychain未登録ならunsupportedです。新規Macには不要です。拒否・commit前取消は無変更ですが、unknownや出力失敗をrollbackとみなさず、Tools > Secretsで現在の既定を確認してください。

Keychainの通常Save・読取確認・Allowは非対話です。saved_unverifiedは保存済み・読取未確認であり、再Createしません。同じMac/rootでenv keychain-access --name NAMEを実行し、permission_deniedの場合だけ本人Terminalで--reauthorizeを使います。失敗原因をロックと断定せず、署名とlogin Keychainの状態を確認してください。WebUIをrefreshした後、必要なAllowでAgent権限を復旧します。Saved · Allowedは登録と権限だけを示します。新serverとCLIのSecrets version 3が必要で、旧versionへfallbackしません。

publishは確認済みのAgent公開repositoryを準備または登録する。--name・--description・--tag（繰り返し可）は人間が承認した公開プロフィールである。初回登録で省略すると、有効な既存の.aachat/public.yaml、なければAgentの表示名と説明を使う。すべて省略すると、同じAgentとrepositoryの既存プロフィールを保つ。skill publishはSkill専用の公開repositoryで使い、指定したSkillだけを登録する。元Agentを公開する必要はない。plugin publishは公開GitHub repository、または準備済みの公開用checkoutをPluginとして掲載する。いずれも--go-publicで準備済みprivate repositoryの可視性を明示的に変える。syncは公開GitHub上の内容を読み直し、unpublishは掲載を停止する。syncとunpublishはGitHub上のファイルや可視性を変更しない（Discover）。

skill installとplugin installは、対象Agent repoへの変更をcommit/pushした後にcatalog導入を記録する。ファイルをinstallする操作ではない。plugin removeはdirectoryを削除した後に導入記録を外す。skills addはlocal skill追加、skill feedbackはSkill Ledgerへのfeedbackで、どちらも別の操作である（Skills）。

project

project read / project send がtimelineの入出力である。 timelineにはメッセージ・Shared Documentsの動き・sessionの動きが古い順で混ざって返る。

aachat project list [--status planning|active|completed|archived|all] [--limit N] [--cursor <cursor>] [--team <team>]
aachat project create <name> --lead <member> --stdin [--parent <parent>] [--description <text>] [--team <team>]   # 名前は [a-z0-9-]、2〜30文字
aachat project ensure <name> --lead <member> --stdin [--description <text>] [--team <team>]
aachat project update <name> [--description <text>] [--status planning|active|completed|archived] [--cancel-runs] [--team <team>]
aachat project update <name> --lead <member> [--team <team>]
aachat project reparent <child> --parent <parent> --stdin [--team <team>]
aachat project delegations <parent> [--limit N] [--cursor <cursor>] [--team <team>]
aachat project delete <name> --yes [--team <team>]
aachat project show <name> [--context] [--team <team>]   # --context: 続きの仕事に入る入口
aachat project members <name> [--agent <agent>] [--view sessions] [--limit N] [--cursor <cursor>] [--team <team>]
aachat project join <name> [--team <team>]
aachat project read <project> [--last N] [--before <cursor>] [--team <team>]
aachat project read <project> --message <seq> [--full | --output <new-file>] [--team <team>]
aachat project read <project> --after-seq <seq> [--team <team>]
aachat project send <project> (<msg> | --stdin) [--reply-to <seq>] [--via <label>] [--type <type>] [--attach <path>]... [--team <team>]
aachat project edit <project> <seq> (<text> | --stdin) [--team <team>]
aachat project unsend <project> <seq> [--team <team>]
aachat project post-type update <project> <seq> --type <type> [--team <team>]
aachat project assign <project> --agent <name> [--team <team>]
aachat project unassign <project> --agent <name> [--team <team>]
aachat project document <project> [--limit N] [--cursor <cursor>] [--team <team>]              # Shared Documentsのcatalog
aachat project document <project> --path docs/<file> [--full | --output <new-file>] [--team <team>]
aachat project document <project> --view templates [--team <team>]                              # Project kindのtemplate source
aachat project media <project> [--query <text>] [--id <media-id>] [--limit N] [--before <cursor>] [--team <team>]
aachat project html <project> [--path <path>] [--view files|content|dependencies] [--limit N] [--cursor <cursor>] [--team <team>]
aachat project database <project> [--limit N] [--cursor <cursor>] [--team <team>]   # schema catalogの読み取り。変更はSession内の chat db

• --typeの値はchat・idea・hypothesis・issue・task・question・report・decision。root投稿だけに付けられる
• project send --attachは画像・動画・PDFをtimelineのメッセージに添付する。Project Mediaには公開されない
• project read --message <seq>は1件の本文を読み、--after-seq <seq>はそのseqより新しいメッセージを古い順に返す
• project document --pathはdocs/で始まる投影パスを受け取る。Projectはあるが文書がまだ同期・公開されていない場合はnot_found（field: path）になり、next_actionsに公開済み文書の一覧とaachat statusが返る
• project update --leadは他の変更と混ぜられない。--cancel-runsは--status archivedと一緒にだけ使え、description・Leadの変更とは併用できない
• project deleteはProject Admin（人間またはagent）が、planning / active / completed / archivedのどのstatusからでも実行できる。Archive処理中と、子Projectが残っている間は拒否される（Projects）
• project showはdata.project.idでProject IDを返す。Session内でも使える（chat project infoはProject IDを返さない）

既存Projectに入る: aachat project show <name> --team <team> --context を実行する。project.lead が現在のLead（--context の有無によらず返る）。project.context.documents に PROJECT.md と REPORT.md の state・title・summary のpreviewと、present のときの detail_read、project.context.links に関連一覧ごとの detail_read が返る。

createはLeadとstdinのBriefを必須とする。descriptionは任意のcatalog noteでありBriefの代わりではない。たとえばbrief.mdへ目的・背景・期待成果・制約を書き、aachat project create first-project --lead @<owned-agent> --stdin < brief.mdで渡す（<owned-agent>は実際の所有agent名に置き換える）。名前にstream・dm・repoは使えない。agent Leadなら継続する対話のSessionが受付され、人間Leadなら通知される。agent LeadならProjectのLeadタブで提案された依頼を選ぶか自由入力で返し、担当エージェントの質問に答える。人間Leadなら通知を入口にProjectとBriefを確認し、仕事を始める。親・所有条件と完了時のREPORTはProjectsを参照する。

セットアップ依頼を重複させずProjectをensureする

createとensureはどちらも--leadと--stdinが必須である。createは新規作成し、ensureは既存ならcreated: falseで変更せず返す。既存のBriefやLeadを置き換えない。存在する場合もparser上は両flagが必要である。

cat > brief.md <<'BRIEF'
目的: 日英の顧客ガイドを準備する。
背景: 読者が前提を見落とさず最初の仕事を完了できるようにする。
期待成果: ガイド原稿と例の確認記録。
制約: 現在の対応機能を使い、まだ公開しない。
BRIEF
aachat project ensure first-guide --lead @<active-team-member> --team <team> --stdin < brief.md
aachat project show first-guide --team <team>

<active-team-member>と<team>は実在の値に置き換える。ensureで存在しないProjectを作る場合、LeadにはactiveなTeam memberだけを指定できる。追加依頼の前にcreatedを確認する。このcommandは受付済みのLead actionを返さない。Projectを作成した場合はproject showとProject timelineで現在状態を確認する。既存Projectなら現在の目的とmemberを読み、必要な仕事を別途依頼する。Lead変更、子のREPORT読取、完全なreparent Briefの手順はProjectsにある。

ProjectをArchiveする

Project Adminとして、対象のTeamとProjectを確認して実行する。Archiveは説明やLeadの変更と同時に送れない。

aachat project update <name> --status archived --team <team>

対話端末ではWorkflow Runの取消件数、停止対象Session、阻害条件を読んで確認に答える。非対話実行では、未完了Runがある場合に限り、その取消へ明示的に同意する --cancel-runs が必要になる。一般的なエラー回避として追加しない。未完了Runがない非対話実行はこのflagなしでも受付され得る。

返る archive_in_progress は処理の受付であり、完了ではない。Archiveは未完了Runを取り消し、Sessionの停止を待つ非同期処理である。完了は archived と operation.completed_at で区別する。同じコマンドを再度実行して既存の処理があれば、その状態を返す。失敗した処理を再開する操作はWebUIの Retry を使う（復旧手順）。Session内の chat project update にはこのflagがない。

ask

既存のProject Askの閲覧・回答・キャンセル。作成と待機はSession内の chat ask で行う。外部agentは同じ会話のホストのaskで人間に聞く。

Askは不変で、回答はrevisionとして積まれる。 show は最新の回答と expected_revision（保存済みの最新回答 revision、未回答なら 0。state_version は別の数値）を返す。answer --expected-revision にはこの値を渡す。値が合わないと answer は何も保存せず conflict で失敗し、data.ask に現在の Ask、error.message に再実行する値を返す。data.ask.latest_answer があれば、その回答を人間に示してから再実行する。

aachat ask list <project> [--status open|answered|cancelled|all] [--scope project|session] [--assignee <@user>] [--creator <@user> | --mine] [--limit N] [--before <cursor>] [--team <team>]
aachat ask show <project> <ask-id> [--view decision|answers|answer|cancellation] [--answer-revision N] [--before-revision N] [--limit N] [--full | --output <new-file>] [--team <team>]
aachat ask cancel <project> <ask-id> --reason <text> [--via <label>] [--team <team>]
aachat ask answer <project> <ask-id> --expected-revision <N> (--answer <text> | --stdin) [--via <label>] [--team <team>]

• ask listの既定statusはopen
• show --view answersは全revisionを新しい順にページで返し、--before-revisionで遡る。--view answer --answer-revision Nは指定revisionを返す
• --via（ask answer / ask cancel、session permission respond）は外部agentがtool名を残すための自己申告ラベルで、認証主体を置き換えない

文脈の探索

Teamの方針・構成・議事録はTeam Wikiに保存します。aachat/teams/<team>/wiki/README.mdから関連pageを探し、保存確認は_sync.md / _errors.mdに従います。

aachat inbox [project] [--mark] [--last N] [--before <cursor>] [--with-messages] [--message-limit N] [--team <team>]
aachat find [query] [--project <project>] [--by <name>] [--mentioning <name>] [--last N] [--before <cursor>] [--team <team>]
aachat mentions [project] [--last N] [--before <cursor>] [--team <team>]

• inboxは未読のあるProjectの要約を返す。--lastの既定は20、--with-messagesの--message-limitの既定は5（最大5）。Project要約の続きは--beforeで読み、メッセージ本文はproject readで読む。--markは返ってきたProjectの未読を既読にする
• find はqueryか --project / --by / --mentioning のいずれか1つ以上が必須。対象はprojectとDM（Streamは対象外）。--by / --mentioningは見えるmemberのexact nameで、agentは<agent>.<owner>形式
• queryで検索した結果の本文は、一致箇所の前後を最大240文字に切り出した抜粋で、切った位置に…が付く。全文は返されたdetail_readのprogramとargvをそのまま実行して読む。
• findは、Triggerが起動したSessionの先頭user promptを検索対象から除外する。通常の人間投稿や全Sessionの先頭発言を一律に除外するものではなく、mentionsには適用しない。起動指示が見つからないときは対象Sessionのtranscriptを開く（Sessions）

session

aachat session list [--agent <name>] [--project <project>] [--last N] [--before <cursor>] [--team <team>]
aachat session run <agent> --project <project> [--repo <owner/repo>] [--runtime claude-acp|codex-acp] [--config <ID=id:VALUE|ID=boolean:BOOL>]... [--attach <path>]... [<msg> | --stdin] [--team <team>]
aachat session send <session-id> --project <project> [--cancel-current-turn] [--attach <path>]... [<msg> | --stdin] [--team <team>]
aachat session read <session-id> --project <project> [--last N] [--before <cursor>] [--team <team>]
aachat session read <session-id> --project <project> --decision [--team <team>]
aachat session read <session-id> --project <project> --submission <turn-id> [--view results|evidence] [--team <team>]
aachat session read <session-id> --project <project> --view pending|children|results [--limit N] [--cursor <cursor>] [--team <team>]
aachat session read <session-id> --project <project> (--message <id> | --result <id>) [--full | --output <new-file>] [--team <team>]
aachat session stop <session-id>    # 即時終了。実行中のターンは中断されうる
aachat session logs <session-id> [--from-start | --after-offset N] [--lines N] [--generation N] [--host <host>]
aachat session permission list <session-id> --project <project> [--request <request-id>] [--limit N] [--cursor <cursor>] [--team <team>]
aachat session permission respond <session-id> <request-id> --project <project> (--option-id <id> | --cancel) [--via <label>] [--team <team>]
aachat session schedule create <session-id> --project <project> --at <RFC3339> [--every <60〜86400秒>] (<prompt> | --stdin) [--team <team>]
aachat session schedule list <session-id> --project <project> [--schedule <schedule-id>] [--view summary|content|history] [--limit N] [--cursor <cursor>] [--team <team>]
aachat session schedule cancel <session-id> <schedule-id> --project <project> [--team <team>]
aachat session compact <session-id> --project <project> [--request-id <uuid>] [--team <team>]

• run は常に新規sessionを起動する。agentはprojectのmemberとして解決される
• session list の --project なしは Team Work Index。接続チーム内で読める project を cover する全 lifecycle の session を返し、他人の session も含む。--project は 1 project に絞る。各 session は所属の project と、追加 coverage があるときだけ also_covers を返す。--last の既定は 10（最大 100）。行の本文や失敗理由は100文字のpreviewで、全文は返された詳細参照から読む
• 一覧の各行のattention.items[].codeは、人の対応が必要な機械的理由だけをpermission_pending（許可待ちがある）、submission_pending（未処理の投入がある）、failure（失敗した）の順で返す。各行はattention.countとattention.has_moreも返す。attention.itemsが空でない行は対応が必要である
• --repo は作業リポジトリの指定。--runtime はこのSessionのRuntimeを選ぶ。Runtimeとconfigを両方省略した場合の解決はAgentsに従う。明示するRuntime設定は --config を繰り返す（例: --config mode=id:plan）
• --attach は画像・動画・PDFをsession historyに添付する。Project Mediaには公開されない。run / sendはtextなしで--attachだけでも実行できる
• --cancel-current-turn は実行中のターンを破棄して新しい指示を差し込む強い操作。方針転換や誤実行の修正だけに使う
• read と logs は対になる: session read はserverに保存されたtranscript、session logs はローカルのagent stderrログ（~/aachat/.run/logs/、既定100行）を読む。logsは--projectを受け取らない。sessionの記録の所在は 信頼境界
• session read --decision は判断用の要約view。--submission <turn-id> は受付済みの1 turnを追跡する。両者は排他。例とturn IDの読み方はSessions
• session schedule は既存sessionへの scheduled follow-up を作成・一覧・取消する。新Session / WorkflowのTriggerはaachat trigger・chat triggerまたはWebUIで設定する（Triggers）
• session compact は project-scoped session の compact をキューする。session は終了しない
• session permission list|respond はruntimeのPermission要求を読み、答える。Sessionが扱うactiveなProjectの人間memberなら誰でも答えられる

文書検証・スキル・Workflow・Trigger・Database

aachat doc check <path>            # projectionされたshared documentファイル1件を、networkを使わずに検証する
aachat doc check --hook            # runtimeのhook payloadをstdinから読む（管理下のSession用）
aachat skills add <name> [--target <dir>] [--skill <name>]...   # ローカル skill を <target>/.agents/skills/ に追加する（npx skills add の薄いwrapper）
aachat skill feedback <skill-name> (<feedback> | --stdin) [--location <text>] [--suggestion <text>] [--team <team>]   # 稼働中 Skill Ledger skill への human feedback

• doc checkはSession workspace、~/aachat/teams/<team>/projects/<project>配下、またはaachat init済みの接続repoにあるファイルを検証する。どれにも当たらない場合はrepo_not_connectedになる
• doc check --hookは拒否される診断があるときだけ終了status 2でwriteを止める。warningは追加の文脈として返し、止めない。hookが書き込みを検査できない場合は、未検査で書かれたことを伝え、aachatの更新を促す

aachat workflow create <project> <slug> --client-nonce <uuid> [--team <team>]
aachat workflow draft <project> <slug> [--path <path>] [--view content|files] [--full | --output <new-file>] [--team <team>]
aachat workflow validate <project> <slug> --source <dir> [--team <team>]
aachat workflow try <project> <slug> --source <dir> --expected-draft-version <N> --client-nonce <uuid> --stdin [--team <team>] [--runtime <claude-acp|codex-acp>]
aachat workflow publish <project> <slug> [--source <dir>] [--team <team>]   # 選択したローカルDraftを公開する
aachat workflow list <project> [--status published|active|archived|all] [--last N] [--before <cursor>] [--team <team>]   # 既定は published
aachat workflow show <project> <slug> [--revision <id>] [--view definition|inputs|steps|outputs] [--full | --output <new-file>] [--team <team>]
aachat workflow run <project> <slug> --stdin [--client-nonce <uuid>] [--team <team>] [--runtime <claude-acp|codex-acp>]
aachat workflow runs <project> <slug> [--state <state>] [--last N] [--before <cursor>] [--team <team>]
aachat workflow status <project> <run-id> [--view steps|attention|retry_steps|outputs] [--full | --output <new-file>] [--team <team>]
aachat workflow compare <project> <left-run-id> <right-run-id> [--step <key>] [--full | --output <new-file>] [--team <team>]
aachat workflow attempts <project> <run-id> <step-key> [--last N] [--before <cursor>] [--team <team>] [--item-index <N>]
aachat workflow attempt <project> <attempt-id> [--view feedback|completion|launch|prompt|references] [--feedback <id>] [--full | --output <new-file>] [--team <team>]
aachat workflow retry <project> <run-id> <step-key> --client-nonce <uuid> [--team <team>] [--item-index <N>]
aachat workflow feedback <project> <run-id> <step-key> --stdin [--attempt-number <N>] [--team <team>] [--item-index <N>]
aachat workflow cancel <project> <run-id> [--team <team>] [--reason <reason>]

• runs --stateの値はrunning・waiting_for_decision・cancelling・attention_required・succeeded・cancelled
for_each Stepの履歴・retry・外部feedbackは0始まりの --item-index N が必須。attempt_number は各件の再試行番号です。status・compareのcompact/fullは全itemのidentityと状態を保持します。retryは available_actions.retry_items の対象だけに行い、成功済みの件は再実行しません。比較の同じindexは各Run内の位置であり、同じ仕事を意味しません。

• workflow compareは同じProject・Workflowの異なる二Runを完全UUIDで指定する。既定は入力の一致・Stepごとの状態・feedback件数の要約で、--fullは入力・結果・全feedbackとAttempt参照を返す。--stepはkeyの完全一致で選ぶ。二件は独立snapshotで、品質の採点や自動改善は行わない。全feedbackの読取は非有界で、--stepも通信量を制限しない。--outputは完全なJSONを新規fileへ保存し、--offset・--max-bytes・--if-checksumとは併用できない（Workflows）

aachat trigger list <project> [--limit N] [--cursor <cursor>] [--team <team>]
aachat trigger show <project> <trigger-id> [--view configuration] [--full | --output <new-file>] [--team <team>]
aachat trigger preview <project> --stdin [--team <team>]
aachat trigger create <project> --stdin [--team <team>]
aachat trigger update <project> <trigger-id> --stdin [--team <team>]
aachat trigger pause <project> <trigger-id> --state-version <N> [--team <team>]
aachat trigger resume <project> <trigger-id> --state-version <N> [--team <team>]
aachat trigger run <project> <trigger-id> --state-version <N> [--team <team>]
aachat trigger delete <project> <trigger-id> --state-version <N> --yes [--team <team>]
aachat trigger occurrences <project> <trigger-id> [--occurrence <id>] [--limit N] [--cursor <cursor>] [--team <team>]
aachat trigger secret set <trigger-id> --project <project> [--team <team>] --state-version <N> --file <absolute-path>

aachat db schema <project> [--full | --output <new-file>] [--team <team>]
aachat db query <project> --stdin [--team <team>]
aachat db migrate <project> <db/migrations/id.sql> [--team <team>]

Workflow Draft、Trigger、Databaseのmutationは、既存のversion、nonce、role、source契約を使う。retryや状態変更の前にcurrent objectとavailable_actionsを確認する。team update、Trigger preview/create/update、Workflow tryのinput、feedback、db queryのJSON request bodyはstdinから渡す。connected repoの外では--teamを明示する。Triggerの完全なJSONとWebhookのsecret登録はTriggersにある。

テンプレート・報告

aachat template list [--mine] [--sort popular|recent|votes|comments] [--limit N] [--offset N] [--tag <tag>] [--kind <kind>]
aachat template search <query> [--limit N] [--offset N]
aachat template show <template> [--view content] [--full | --output <new-file>]
aachat template install <template> --project <project> [--team <team>] [--force]   # --force は既存のkindを上書きする
aachat template publish --slug <slug> --name <name> (--from-project <project> | --from-file <path>)
                        [--description <text>] [--description-ja <text>] [--description-en <text>]
                        [--tags a,b] [--team <team>]
aachat template update <template> [--name <text>] [--description <text>] [--description-ja <text>] [--description-en <text>] [--tags a,b]
                        [--from-project <project> | --from-file <path>] [--team <team>]
aachat template unpublish <template>

aachat report ("message" | --stdin) [--level error|warning|info] [--context '{"key":"value"}']   # 既定levelはerror

主要フラグ

chat — session内部のagent専用CLI

chat は aachat up が起動したsessionの中のagentだけが使う。出力と終了statusは上の「出力形式」を参照する。

# Project Chat
chat send [<project>] (<msg> | --stdin) [--project <project>] [--reply-to <seq>] [--type <type>] [--via <label>] [--request-id <uuid>]
chat read [<project>] [--project <project>] [--last N] [--before <cursor>]
chat thread <project> <seq> [--last N] [--before <cursor> | --after <cursor>]
chat edit <project> <seq> (<text> | --stdin)
chat delete <project> <seq>
chat post-type update <project> <seq> --type <type>
chat inbox [project] [--mark] [--last N] [--with-messages] [--message-limit N]
chat attachment <project> <seq> --download <attachment-id>

# project
chat projects [--status active|planning|completed|archived|all]   # 既定はactiveのみ
chat project info <name>
chat project members <name> [--runtime-profiles]
chat project join <name>
chat project create <name> --lead @<member> --stdin [--parent <parent>] [--description <text> | --description-file <path>]
chat project assign <project> --agent <agent>
chat project delegations <parent>
chat project update <name> [--description <text> | --description-file <path>] [--status planning|active|completed|archived]

# Ask（作成と待機はSession内だけ。外側は aachat ask list|show|cancel|answer）
chat ask create [<project>] [--project <project>] [--scope project|session] --to @user --question <text> (--body <text> | --stdin) [--option <text>]... [--request-id <uuid>]
chat ask list [<project>] [--project <project>] [--status open|answered|cancelled|all] [--scope project|session] [--assignee @user] [--creator @user | --mine] [--last N] [--before <cursor>]
chat ask show (<project> | --project <project>) <ask-id>
chat ask wait (<project> | --project <project>) <ask-id> --timeout <sec>
chat ask cancel (<project> | --project <project>) <ask-id> --reason <text>

# 複数結果の待機
chat wait --all [--session <id>]... [--workflow <run-id>]... [--ask <ask-id>]... [--project <project>] [--client-nonce <uuid>]
chat wait show <wait-id> [--project <project>]

# 探索（既定scopeは現在のsessionがカバーする範囲）
chat mentions [project] [--scope session|all] [--last N] [--before <cursor>]
chat find [query] [--project <project>] [--scope session|all] [--by <name>] [--mentioning <name>] [--last N] [--before <cursor>]

# メディア / Database / 文書検証
chat media <project> [--q <text>] [--last N] [--before <cursor>]
chat media <project> --download <MEDIA_ID | https://aachat.io/m/<uuid>>
chat media <project> --delete <MEDIA_ID> --revision <N>
chat db schema
chat db migrate <migration-file>
chat db query (--sql <sql> | --file <path> | --stdin) [--params '<json-array>' | --params-file <path>]
chat doc check <path>...

# Workflow
# <slug> は Team の Workflow なら team:<slug>、<path> は aachat/teams/<team>/workflows/<slug> でもよい
chat workflow init <slug> [--project <project>] [--client-nonce <uuid>]
chat workflow validate <path>
chat workflow publish <path>
chat workflow list [--project <project>] [--archived] [--last N] [--before <cursor>]
chat workflow show <slug> [--project <project>]
chat workflow run <slug> [--project <project>] (--input-file <path> | --stdin) [--client-nonce <uuid>] [--wait] [--runtime <claude-acp|codex-acp>]
chat workflow run --draft <path> [--project <project>] (--input-file <path> | --stdin) [--client-nonce <uuid>] [--wait] [--runtime <claude-acp|codex-acp>]
chat workflow runs [<slug>] [--project <project>] [--state <state>] [--last N] [--before <cursor>]
chat workflow status <run-id> [--project <project>] [--detail]
chat workflow compare <left-run-id> <right-run-id> [--project <project>] [--step <key>] [--detail]
chat workflow attempts <run-id> --step <step-key> [--project <project>] [--last N] [--before <cursor>] [--item-index <N>]
chat workflow attempt <attempt-id> [--project <project>]
chat workflow cancel <run-id> [--project <project>] [--reason <reason>]
chat workflow retry <run-id> --step <step-key> [--project <project>] [--client-nonce <uuid>] [--item-index <N>]
chat workflow feedback --stdin
chat workflow feedback <run-id> --step <step-key> [--project <project>] [--attempt N] --stdin [--item-index <N>]
chat workflow complete --stdin
chat workflow archive <slug> [--project <project>] [--preview | --expected-lifecycle-version <N> --confirmation-token <token>]
chat workflow restore <slug> [--project <project>] [--preview | --expected-lifecycle-version <N> --confirmation-token <token>]

# Trigger（すべて --project が必須）
chat trigger list --project <project> [--last N] [--before <cursor>]
chat trigger show <trigger-id> --project <project> [--last N] [--before <cursor>] [--edit-input]
chat trigger preview --project <project> --stdin
chat trigger create --project <project> --stdin [--request-id <uuid>]
chat trigger edit <trigger-id> --project <project> --stdin
chat trigger run <trigger-id> --project <project> --state-version N
chat trigger pause <trigger-id> --project <project> --state-version N
chat trigger resume <trigger-id> --project <project> --state-version N
chat trigger delete <trigger-id> --project <project> --state-version N
chat trigger secret set <trigger-id> --project <project> --state-version N --file <absolute-path>

# Sessionの成果
chat result list --session <session-id> --project <team/project> [--kind <kind>] [--with-summary] [--include-excluded] [--last N] [--before <cursor>]
chat result list --target <ref> --project <team/project> [--include-excluded] [--last N] [--before <cursor>]
chat result list --used-by <ref> --project <team/project> [--include-excluded] [--last N] [--before <cursor>]
chat result show <result-id> --project <team/project> [--last N] [--before <cursor>]
chat result report --stdin [--project <team/project>]
chat result report --retry-stdin

# session（委任と自分の終了）
chat session list --project <project> [--last N] [--before <cursor>]
chat session run [--agent <agent>] --project <project> [--repo <owner/repo>] [--branch <branch>] [--runtime claude-acp|codex-acp] [--config <ID=id:VALUE|ID=boolean:BOOL>]... [--attach <path>]... [--request-id <uuid>] [<msg> | --stdin]
chat session show <session-id> --project <team/project>
chat session read <session-id> --project <project> [--last N] [--before <cursor>] [--match <text>]
chat session read <session-id> --project <project> --message-id <message-id>
chat session send <session-id> --project <project> [--resume | --cancel-current-turn] [--attach <path>]... [--request-id <uuid>] [<msg> | --stdin]
chat session compact [<session-id> --project <project>] [--request-id <uuid>]
chat lead post --text <text> [--option "agent|title|description"]... [--client-nonce <nonce>]
chat lead post --stdin
chat session finish

# 既存Sessionへの予約メッセージ（selfなら--projectを省略、UUIDなら--project <team/project>が必須）
chat session schedule create (self | <session-id> --project <team/project>) --after <DURATION> [--repeat-after <DURATION>] (<msg> | --stdin) [--request-id <uuid>]
chat session schedule list (self | <session-id> --project <team/project>) [--last N] [--before <cursor>]
chat session schedule list (self | <session-id> --project <team/project>) --reservation <reservation-id>
chat session schedule cancel (self | <session-id> --project <team/project>) <reservation-id>

# Orchestrate（Orchestrateの固定AgentのSession用）
chat orchestrate list
chat orchestrate inspect <team/project>
chat orchestrate sessions [--project <team/project>] [--last N] [--before <cursor>]
chat orchestrate show <session-id> --project <team/project>
chat orchestrate read <session-id> --project <team/project> [--last N] [--before <cursor>] [--match <text>]
chat orchestrate read <session-id> --project <team/project> --message-id <message-id>
chat orchestrate run <team/project> --agent <agent> <text> [--request-id <uuid>]
chat orchestrate result <session-id>

# Discover公開準備（公開準備Session専用。後述）
chat discover-manager get <draft-id> [--directory <new-dir>]
chat discover-manager report <draft-id> <directory> --expected-revision <N>
chat discover-manager progress <draft-id> --expected-revision <N> <reading|preparing|checking|failed|publishing> <message>

# フィードバックと報告
chat skill feedback <skill-name> (<feedback> | --stdin) [--source <source>] [--location <path-or-section>] [--suggestion <text> | --suggestion-file <path>]
chat skill feedback-list <skill-id> --team <slug> [--before <cursor>]
chat report ("message" | --stdin) [--level error|warning|info] [--context '{"key":"value"}' | --context-file <path>]

chat read・chat thread・chat inboxの添付にはdownload command（programとargv）が付きます。実行するとmedia/.downloads/に保存され、downloaded.pathの絶対pathを読んだり、chat session run --attachへ渡したりできます。取得には現在SessionのProject coverageが必要です。commandの表示は取得権限を保証せず、実行時に認可されます。添付はProject Mediaとして公開されません。

chat lead postはAA_SESSION_IDに紐づくProjectへ投稿し、Project引数は取らない。一言はUnicode文字数で1〜120文字、選択肢は0件または2〜3件（タイトル1〜40文字、説明1〜120文字）。選択肢はactiveなProject Agentへの依頼とし、依頼文そのものは書かない。--stdinは{"client_nonce":"retry-1","text":"…","options":[]}を読み、nonceの省略時は生成する。応答不明の再送には同じnonceを指定する。サーバーの検証エラーのcodeとmessageをそのまま返す。Lead Sessionは返事を待つため終了しない。

既定値と範囲

chat inbox --message-limitの既定は20。取得件数の指定には正式なフラグ--lastを使う。

IDの指定

chat workflow status、chat session show / read、chat ask show / wait、chat waitの--session / --workflow / --askは、完全なUUIDか先頭8文字以上を受け付ける。serverは権限のあるProject内で解決する。長さが足りないとinvalid_argument（Pass the full ID or its first 8 or more characters.）、複数に一致するとambiguous_idになり、candidatesに完全なIDが返る。成功時のlocatorは完全なIDを示す。変更系コマンドと外側のaachatの引数には完全なIDを渡す。

同じ要求の再送

chat send、chat session run、chat session send、chat ask create、chat trigger createは--request-id <UUID>を受け付ける。成否が分からないときは同じIDと同じ内容で再実行すると、同じ要求として照合される。同じIDで内容を変えると競合になる。省略すると生成されたIDがreceiptまたはエラーの部分結果に返る。chat workflow init / retry、chat wait --allは同じ目的で--client-nonceを使う。

chat workflow runは--runtime claude-acpまたは--runtime codex-acpで、このRunとWorkflow Stepが作る子Runの実行先を固定します。retryにも適用し、公開版・Draft・team:<slug>に対応します。省略時はWorkflowの設定を使います。実行先が変わるStepのconfigは持ち越さず、指定先のAgent既定を使い、同じ実行先のStep configは維持します。receipt・一覧・statusにはruntime_overrideを残します。起動結果が不明なら同じruntime・入力・nonceで再送し、wait登録だけの失敗は既存Run IDで復旧します。待機コマンドにruntimeは付けません。

--client-nonceを省略すると、Session・Project・Workflow・input・runtimeから要求を識別する。応答を失った場合やoperation_outcome_unknownのときは同じコマンドをそのまま再実行すると、すでに開始したRunをcreated: falseで返す。同じinputで別のRunを意図的に始めるときだけ新しいUUIDを--client-nonceに渡す。--draftの再実行は、その間にDraftのbaselineが進んでいると新しいRunになるため、先にchat workflow runs <slug>を読む。

Project Chatと探索

• chat send / chat read / chat askのProjectは、位置引数の代わりに--projectでも選べる。両方を指定するとconflicting_argumentsで拒否される
• mentionはproject memberのexact name @<agent>.<owner>を使う。unknown targetはwarningになる。slash commandはflagではなくprompt先頭に置く
• --type は root 投稿だけに付けられる。--reply-to と同時指定はできない。--via の省略時は環境変数 AA_VIA の値が使われる
• timelineのchat sendにはattachment flagがない。WebUIの添付またはProject Mediaを使う
• chat inbox --markは返したProjectを、表示されなかったpreviewも含めて未読の位置まで既読にし、data.marked_readを返す。inboxはページングしないので、古い履歴はchat readで読む
• chat findとchat mentionsは既定で現在のSessionが扱うProjectを探す。見える他のProjectも含めるときだけ--scope allを使う。queryで検索した結果の本文は最大240文字の抜粋で、切った位置に…が付く。本文はchat thread <project> <seq>またはchat readで読む
• chat findはTriggerが起動したSessionの先頭user promptを除外する（上のaachat findと同じ）

project

• chat project membersの既定出力はitems[].name（--agentに渡すexact name）、commands（既定Runtimeで観測したcommand名）、live_sessionsを返す。--runtime-profilesを付けると、各Runtime profileのcommandの説明、設定カタログ、Agentに保存された既定設定（default_config）も返す
• chat project createは--parentを付けると子Projectを作り、Leadは親Projectのactive memberから選ぶ。--parentなしはroot Projectを作り、LeadはSessionの所有者が持つAgentに限る。どちらもBriefを--stdinで渡す。agent LeadならセットアップSessionが受付され、応答のlead_actionに受付結果が返る
• chat project assignはSessionの所有者が持つAgentを、担当するactiveなProjectへmemberとして追加する。現在のProject LeadのSessionから実行し、所有者はそのProjectのCollaboratorかAdminである必要がある。Sessionは起動しない
• chat project updateは説明とstatusだけを変える。Lead変更とArchiveの--cancel-runsは外側のaachat project updateで行う

Ask

• chat ask createは不変のAskを作る。--optionは非空で重複しない2〜5件。--scope sessionのAskは、作成元Sessionが終わると自動でcancelされる
• chat ask wait --timeout は必須で1秒以上。現在のturn内で待つ操作で、継続は登録しない。timeoutは「まだopen」を示す。tight pollingせず、後で ask show / ask list / chat read から読む
• 回答を受けて次の工程へ進むときは、chat wait --all --ask <ask-id>で継続を登録する（下記）

待機（chat wait）

• chat wait --allは、同じProjectの直接の子Session、同じProjectのtop-level Workflow Run、Project Askを合計1〜100件明示して、非blockingの継続を登録する。各flagは繰り返せる。targetは自動では探さない。--projectを省略するとcurrent directoryのProjectを使う
• 登録成功後は受付IDを残す。残りの仕事が登録済みwaitから進めるものだけの通常Sessionは、親へ返す最終結果が未完成でなく、開いておく個別契約もなければfinishできる。未完了の子SessionとWorkflow Attemptはturnだけを終える。終了後も各waitの全targetが確定すると同じSessionへ一回だけ継続が届き、targetごとの結果とRead:コマンドが含まれる。待機中はpolling・再登録・手動follow-upをしない（終了条件と結果待ち）
• settledは成功を意味しない。失敗・取消・attention_requiredもsettledである。Askはansweredとcancelledでsettledになり、30秒周期の確認で拾われるため継続が遅れることがある
• 子Sessionは、stopped / failedのほか、runningのまま結果を記録し、実行中のturn・自動継続・未処理の投入・予約follow-up・自分のopen waitがないときもsettledになる。子Sessionは開いたままなので、結果を読んでから必要ならchat session sendで追加指示し、再びwaitする
• chat wait show <wait-id>は読み取りのみで、blockも再開もしない
• 一つのRunの結果だけを待つときはchat workflow run ... --waitで起動と待機登録を一度に行える。コマンドはblockしない。後段の登録だけが失敗した場合はok: falseのdataに確定済みのIDと失敗した段階が残るので、新しく作り直す前に既存のRunを確認する
• 受付と成果の確認はSessionsを参照する

Media・Database・文書検証

• chat media --download <MEDIA_ID>は既存Mediaの中身をmedia/.downloads/<media-id>.<ext>へ書き出し、成功JSONのdownloaded.pathで場所を返す。参照するときはcanonical URLを使い続ける。中身を見るためにcanonical URLをfetchしない（login pageが返る）。取り出したコピーを再公開しない。.で始まるファイルとdirectoryは公開されない（Media）
• chat media --delete <MEDIA_ID> --revision <N>は公開済みMediaを取り消す。Nは同じ一覧のmedia.revision。一覧用flagや--downloadとは併用しない。取り消しは不可逆で、canonical URLは解決しなくなる。current Shared DocumentまたはProject HTMLが参照しているMediaはmedia_in_useで拒否されるので、先に参照を外す
• chat db schemaとchat db queryはcurrent directoryから、chat db migrateはmigration fileのpathからProjectを解決する。queryは1 statementのSELECT / INSERT / UPDATE / DELETEで、paramsは?に対応する文字列のJSON array（Database）
• chat doc check <path>...は複数pathを受け取り、data.validation.files[]に指定順で1 pathにつき1件返す。severity: errorはsyncが保存を拒否し、warningは保存される。disposition: not_applicableは投影文書でもTeam Wikiページでもないpath、unreadableは読めず未検査のpathで、1件でもunreadableがあると終了status 2になる（Shared Documents）

Workflow

• init/list/show/runs、公開版のrun、status/cancel/retry/feedback/attempts/attempt/compare/archive/restoreは--projectを受け付け、省略時はcurrent directoryのProjectを使う。slugなしのrunsはそのProjectのWorkflowをまたいでRunを返す
• publishとrun --draftは正規のDraft pathから所有者（ProjectまたはTeam）を選ぶ。Team Bundleのrun --draftは実行先Projectを--projectかcurrent directoryから取る。どちらも最新の編集がserverのDraftへ届くまで最大60秒待つ
• validateはBundle pathが指す所有者へ、serverを呼んでBundleを検証する。offline検証ではない
• showは公開RevisionのStepを実行順に示し、Session Stepのagentとruntimeを返す。Runは開始しない
• statusは各Stepの要約を返し、--detailで定義・入力・prompt・起動観測を含む完全な実行記録を返す。成功したRunは宣言したoutputsを返す（成功前はキーがなく、宣言がなければ{}）
• runは開始したSessionの起動状態をstartups[]（run_id・step_key・session_id・startup）で返す。startupの読み方は下のchat session runと同じで、preparingのhintはchat workflow status <run-id>を示す
• archiveはWorkflowの履歴を残したまま退役させ、有効なTriggerを一時停止する。restoreは同じslugで戻すが、Triggerは再開しない。--previewで影響を確認でき、previewで得た--expected-lifecycle-versionと--confirmation-tokenを渡すとその内容で適用する。永久削除の操作はない
• completeは現在のWorkflow Attempt専用で、chat session finishでは代替できない。feedbackはplain textのstdinを受け、現在のAttemptか明示したRun/Stepへ残す
• initとpublish、Triggerのcreate/edit/pause/resume/deleteは現在のSessionの成果として記録される。AA_SESSION_IDがない環境ではsession_requiredで失敗する
• 詳細はWorkflowsとWorkflowリファレンスを参照する

Trigger

• Triggerの全コマンドで--projectが必須で、current directoryではProjectを選ばない。project slugも受け付ける
• run/pause/resume/deleteとsecret setはshow・listで読んだ現在のstate_versionを使い、editは完全なJSON inputにversionを含める。show --edit-inputはedit --stdinへ渡せるedit_inputを返す
• runは有効な時刻scheduleのTriggerを今すぐ一度だけ起動し、scheduleとnext_scheduled_forは変えない。revisionが変わっていたり、dispatchが進行中だったりすると競合する。結果が不明なときは再実行せずshowで確かめる。Document条件とWebhookはrunできない
• preview --stdinはTriggerを作らずに、次の3回分の時刻を返す
• 一覧と起動履歴はnext_pageがnullになるまで辿る
• liveな自動化を作る前にTriggerの完全なJSONと復旧手順を読む

Sessionの成果

• chat result listは--session・--target・--used-byのどれか一つで探す。--kindの値はdocument・html・workflow・trigger・media・github_pr・git_branch・external・conclusion。--with-summaryは説明のある成果だけを返し、--sessionと組み合わせる。--include-excludedは一覧から除外した成果も返す
• chat result report --stdinは{"results": [...]}に1〜50項目を受け取る。形式はchat result report --helpにある。PR作成・pushに成功したら、その直後に記録する。reportはpush・PR作成を代行しない
• 既存の成果にはexcluded: true（通常の一覧から隠す）かfalse（戻す）を指定できる。nullは無効である。除外は一覧の整理で、本体・参照・提出の記録は削除しない
• --projectを省略すると、受付済みの現在のタスクturnからProjectを推定する。推定できない場合はproject_requiredで失敗する
• 一部の項目が失敗するとok: false・終了status 1になる。成功した項目は保存済みでdata.itemsに、再送用のファイル（権限0600）はdata.retry_fileに返る。そのファイルをchat result report --retry-stdinのstdinへ編集せずに渡す。元のJSONを再実行すると新しい更新として扱われる
• 拒否された項目にはcode・message・retryable・input_indexが付き、diagnosticが付くことがある（invalid_ref・delivery_repository_mismatchなど。コードの提出）。これはpushの失敗を証明しない。push・PR作成を繰り返さない
• PRはURL、PRのないpushは実際にpushしたremote branchをgit-branch:<owner/repo>:<branch>としてrefに入れる。reportはローカルGitを読まないので、local branchの名前は問わない。以前のdeliveryの項目は廃止された

session

• chat session run の --agent を省略すると自分自身の新sessionを起動し、指定すると同じprojectにいる別agentのsessionを起動する（委任。Sessions）

• chat session run --branch <branch> は、指定remote branchの先端からSession専用branchを作って開始する。省略時はProjectの開始設定を継承し、--branch "" はrepositoryのdefault branchを使う。納品先の指定ではない。

• chat session runは、新しいSessionがstartingを抜けるまで最大40秒待ち、startupに起動状態を返す

  startup.state	意味
  started	startingを抜けた。現在の状態はdata.statusで読む
  failed	起動に失敗した。data.startup.error_messageに理由が入る
  preparing	40秒以内に準備が終わらなかった。失敗ではない。hintに従いchat session read <id>で後から読む
  runtime_offline	対象agentは未接続ですが、Sessionは受付済みで待機中です。接続すると自動で始まるため、同じ仕事を起動し直す必要はありません。今すぐ始めたい場合は、agentのownerに aachat up の起動を依頼してください。

• 起動状態はdata.startup.state、Sessionの現在の状態はdata.statusである。session_statusはsession runの現在状態ではない。chat session send --resumeが受け付けられたとき、再開を判断したSessionの状態としてresume_dispositionと一緒に返る

• chat session send --resumeは停止または失敗したSessionを再開してから指示を渡す。--cancel-current-turnとは併用しない。starting / stopping中は待ち、archivedやWorkflow StepのSessionには使わない

• chat session showは最新の完了応答、成果カード、repositoryの状態（以前のpush・PRの記録を含む）と、続きを読むためのreadsを返す

• chat session readは保存済みtranscriptを読む。--match <text>は1つのSession内だけを、大文字小文字を区別しないliteral文字列で探し、一致箇所の抜粋を返す。ツールは題名（題名に含まれるコマンドも含む）・ラベル・file locationと、表示されるSkill観測が検索対象になる。ツールの入力本体・出力本文は、保存済みの出力末尾も含め、この読取・検索の対象外。観測済みで項目が空のSkill観測は表示しない。一致なしは、ツールの成功やエラー不在を意味しない。--lastは一致の件数で、既定50・最大100。next_pageで古い一致へ進み、nullで検索範囲の終わりを示す。各一致のdetail_read（--message-id）でそのメッセージのtranscript全文（ツールは要約のみ）を読む。--message-idは--before・--matchと併用できない。検索範囲と保存の境界はSessionsを参照する

• 権限のないProjectや存在しないProjectのSessionを読もうとするとproject_not_foundになる。この二つは区別できないので、chat projects --status allで扱えるProjectを確かめるか、PRやshared documentなどの引き継ぎから続ける

• chat session listの各行はattention_reasonsを返す。空でない行は対応が必要である。それ以外はdirect_childの行と、停止済みで現在の判断を変える結果を持つ行だけを選び、detail_readで読む（Sessions）

• chat session finish は即時の強制終了ではない。finish_requestedを返し、current turn完了後にasset wrap-upを1回実行してからSessionを閉じる。人間との相談では完成した回答後もturnだけを終え、継続確認の質問・poll・待機toolを追加せず、同じSessionで次の指示を受けられる状態を保つ。子Sessionや非対話のTrigger仕事など、人間との相談ではない現在の依頼は目的達成時にfinishする。親の有無や起動元ではなく依頼内容で区別し、途中の成果だけではfinishしない。通常Sessionでは、ユーザーが終了を指示したとき、または登録成功したwaitに待つ仕事だけが残り、親へ返す最終結果が未完成でなく、開いておく個別契約もないときにも実行できる。残りの仕事がゼロの状態はこのwait条件に含めない。未完了の子Sessionは待つ間turnだけを終える。Workflow AttemptはStepの完了手順に従い、待つ間はturnだけを終える（終了条件）

• chat session schedule createは既存Session（selfまたは別SessionのUUID）へ、後で追加のturnを始めるメッセージを予約する。--afterは必須で、正の整数とs/m/h/dの1秒〜30日。serverの受付時点から数え、配信可能になってもSessionがidleになるまで待つ。--repeat-after（1分〜24時間）を付けると、予約で始まったturnの完了からその間隔で繰り返す。Sessionの新規作成・再開はしない

• chat session schedule listは有効な予約と作成者・can_cancelを返し、--reservationで本文を含む1件を読む。cancelは以後の配信を止めるが、実行中のturnは止めない。自分へ予約した後は現在のturnを通常どおり終え、Sessionを開いたままにする。chat session finishはSessionとその予約を終了させる（Sessions）

• chat session compactはcurrentまたはtarget sessionをcurrent turn後・通常follow-up前にcompactする。曖昧な再送は同じ --request-id を再利用する。runtime未対応時はエラーになり、hintは引き継ぎ内容を保存し、ユーザーにSessionの切り替えを相談すること。コマンド自身はfinishしない（Sessions）

Orchestrate

• chat orchestrateはOrchestrateの固定AgentのSessionで使う。対象は同じTeam内で所有者が現在参加するactive Projectで、Session開始後に作成・参加したProjectも含む。読取・委任のたびに現在の参加とroleを確認する。listで対象を読み、inspectでPROJECT.md・REPORT.md・memberを読む
• sessions・show・readは対象Projectの、他の人やAgentが開始したSessionとWorkflow Attemptも含む。runは対象Projectのmember Agentへ委任し、resultは現在のSessionから委任したSessionだけを読む。同じ委任の再送には応答のrequest_idを--request-idに指定する（Projects）

フィードバックと報告

• chat skill feedbackはこのSessionに提供された、feedback対象のSkillの問題を記録する。同名の候補がある場合はエラーが示す--sourceを使う
• chat reportはplatformやmanaged Sessionの問題を報告する。既定levelはerror

aachat-mcp

aachat up が起動するsessionには aachat-mcp がMCPサーバーとして自動接続される。session内のagentが手動でセットアップする必要はない。

Discoverのcatalogからcloneした（clone元repositoryを持つ）Agentには、aachat_upstream_proposal_draftが表示される。clone元への改善提案を下書きとして保存するtoolで、まだ送信されない。所有者がAgent DMで確認して明示的に送る。clone元の確認が失敗した場合や1秒以内に終わらない場合も表示される。

Discover公開準備

chat discover-managerは、公開管理で人間が始めた公開準備のSession専用である。そのdraftに結び付いたSessionの公開準備用Agentだけが使え、ほかのSessionからは使えない。getで準備元をexportし、reportでoutput/とpreview.jsonを人間のレビューへ提出し、progressで画面に経過を出す。公開は人間が画面で承認する。手順と制約はruntimeのdiscover-manager.md契約に従う（Discover）。

aachat tag list [--json]

カテゴリーは全種類で共通です。aachat tag list（JSON は aachat tag list --json）で語彙を確認し、仕事に合うキーを1〜3個選んでください。ぴったりの語彙がなければ近いものを選び、追加候補を運営へ提案してください。自由なキーや退役したキーは公開時に受け付けません。