Mininglamp-OSS/octo-cli

octo-cli – Octo AIエージェントエコシステム向けの軽量でJSON優先のCLI

何であるか – octo-cli はGoで書かれた単一バイナリのコマンドラインクライアントで、OctoプラットフォームのREST APIと通信します。AIエージェントランタイム（例：OpenClaw、Claude Code）が exec を通じて呼び出すことを想定しています。すべての呼び出しは stdout に決定論的なJSONエンベロープを返します；エラーは stderr にJSON形式で出力され、固定された分類体系を採用しています。対話型プロンプトは存在しません。このツールは完全にプログラム的です。

なぜ存在するか – すべてのビジネスロジックはOctoのバックエンドサービス（ドキュメントストレージ、ドライブ、メッセージング、ファルコン制御など）にあります。CLIの役割は以下の通りです：

• バイナリに埋め込まれたOpenAPI 3.x仕様を読み込む
• 自動的にCobraベースのコマンドツリーを生成する
• 任意のネットワーク呼び出し前にリクエストペイロードを仕様で検証する
• HTTPリクエストを送信する
• レスポンスを標準エンベロープ形式にフォーマットする

主要な設計ポイント

機能	詳細
メタデータ駆動	エンドポイントは埋め込まれたOpenAPI仕様のみで定義される。APIを追加するにはGoコードを変更するのではなく、仕様の編集を行うだけ。
エージェント優先の出力	ok、identity、data、ページネーションおよびレートリミット情報が含まれる安定したJSONエンベロープ。
依存性注入	内部の Factory が設定、資格情報、HTTPクライアント、仕様レジストリを提供 – テストが容易になる。
決定論的なエラー	検証エラーはローカルでキャッチされる。バックエンドの拒否は固定された type/code スキーマで返される。
軽量クライアント	ビジネスロジックは一切持たない。CLIは単にトランスポート、検証、フォーマットのみを担当。

対応ドメイン – CLIはドメインごとにグループ化された多数の操作を公開しています（各ドメインはバックエンドサービスに対応）：

• docs – ライフサイクル、全文検索、スプレッドシート、ホワイトボード、コメント、バージョン、添付ファイル。
• html – 変更不可なインタラクティブHTMLドキュメント、ドラフト、共有コード、UIDごとの権限付与。
• drive – ネットワークドライブスペース、フォルダツリー、2段階のblobアップロード、署名付きダウンロード、共有リンク。
• group, thread, message, file, event – コラボレーションの基本要素。
• bot – ボット登録、ハートビート、ユーザー情報。
• loop – ファルコン制御プレーン（タスク、実行、エキスパート、自動化など）。
• matter, summary – 一時的に無効化中（バックエンドの安定化のため）。

インストール

• npm – npm install -g @mininglamp-oss/octo-cli（ホストプラットフォーム用の事前ビルドバイナリを取得）。
• Go – go install github.com/Mininglamp-OSS/octo-cli/cmd/octo-cli@latest。
• Homebrew – 計画中（brew install Mininglamp-OSS/tap/octo-cli）。
• GitHubリリース – OS/arch用のtarballをダウンロードし、$PATH 上のディレクトリにバイナリを移動。
• install.sh – 最新リリースを取得するワンライナーcurlスクリプト。

通常のワークフロー（環境変数で認証とルーティングを制御）：

export OCTO_BOT_TOKEN="bf_…"          # ボットトークン（app_、bf_、uk_、または octo_loop_）
# オプション：export OCTO_API_BASE_URL="https://im-test.deepminer.com.cn"

# ボットからメッセージを送信
octo-cli message send \
  --data '{"channel_id":"chat-1","channel_type":1,"payload":{"type":1,"content":"hi"}}'

# チャネル間でメッセージを検索
octo-cli message search --keyword "quarterly report"

# グループ一覧表示、スレッド作成
octo-cli group list
octo-cli thread create group-abc --name "design review"

# ドライブにファイルをアップロード
octo-cli file upload --file ./report.pdf

すべてのコマンドは --format（json|table|csv|ndjson）、--jq（後処理用）、--dry-run（解決されたリクエストを確認）、--verbose（リクエスト/レスポンスログ）、ページネーションヘルパー（--page-all、--page-limit）といった汎用フラグを受け入れます。

認証モデル – ボット専用。CLIは以下の優先順位でトークンを読み込みます：

1. ストアドプロファイル（octo-cli auth login）
2. OCTO_TOKEN
3. OCTO_BOT_TOKEN トークンはAppボット（app_*）、Userボット（bf_*）、ユーザーAPIキー（uk_*）、Loopタスク資格情報（octo_loop_*）のいずれかです。トークンの種類によりバックエンドが許可する機能が決まります。CLIはいくつかの事前チェック（例：app_* でメッセージ検索を拒否）を行います。

出力形式 – 成功した呼び出しは以下の形式で出力：

{ "ok": true, "identity": "bot", "data": {…}, "_pagination": {…}, "_rate_limit": {…} }

失敗時は stderr に error.type、code、message、およびオプションの hint/detail を含む同様のエンベロープを出力。終了コード：3（認証）、2（検証/設定）、1（その他）。

エージェントスキル – 人間が読める、機械が解析可能なスキルファイルは skills/ ディレクトリにあります。各ドメインのコマンド、フラグ、エラー分類体系を記述しており、AIエージェントが実行時に読み込むことができます（octo-cli skills）。これらのファイルはバイナリ内に埋め込まれており、オフラインでも利用可能。

拡張性 – エンドポイントの追加または変更は、internal/registry/specs/ 下のOpenAPI仕様ファイルを編集することで行います。CLIは起動時にコマンドツリーを再生成します。Goソースの変更は不要です。

ライセンス – Apache-2.0。

---

結論 – octo-cli は目的に特化した、非対話型のCLIであり、AIエージェントがOctoプラットフォームと予測可能でJSON中心の方法でやり取りできるようにします。組み込みのスキーマ検証、ページネーション、豊富なコラボレーションAPIを備えています。