larksuite/cliを業務APIの操作面として読む: 認証、粒度、AI利用時の境界

18領域を一つのCLIに集約する設計

larksuite/cliは、larksuiteチームがメンテナンスするLarkと飛書の公式コマンドラインツールです。READMEでは、人間のユーザーとAIエージェントの両方を対象に作られていると説明されています。Messenger、Docs、Base、Sheets、Slides、Calendar、Mail、Tasks、Meetings、Markdownなどを含む18の業務ドメインをカバーし、200以上のコマンドと26のAIエージェントスキルを持つと主張しています。リポジトリのメタデータによると、このプロジェクトはGoで書かれ、スター数16,168、フォーク数1,283、未解決issue数501で、アーカイブされていません。READMEにはバージョン番号やリリース頻度の記載はありません。

「18領域を一つのCLIに集約する設計」では、cliの設定と実行結果を確認します。確認用には `lark-cli calendar +agenda --format json`、`lark-cli auth status`、`lark-cli api GET /open-apis/calendar/v4/calendars` を順番に実行し、戻り値の `ok`、identity、stderrの分離を記録するのが具体的です。

npm導入から認証完了までの実際の境界

2つのインストール方法が記載されています。推奨されるのはnpmを使う方法で、`npx @larksuite/cli@latest install` を実行します。ソースからビルドする場合はGo v1.23以上とPython 3が必要で、`git clone https://github.com/larksuite/cli.git`、`cd cli`、`make install` の後に `npx skills add larksuite/cli -y -g` を実行してCLIスキルをインストールします。インストール後のクイックスタートは、`lark-cli config init` でアプリ認証情報を設定し、`lark-cli auth login --recommend` でログインし、`lark-cli calendar +agenda` などのコマンドを使います。READMEは「3ステップで3分」と述べていますが、具体的な所要時間の根拠は示していません。

「npm導入から認証完了までの実際の境界」では、cliの設定と実行結果を確認します。確認用には `lark-cli calendar +agenda --format json`、`lark-cli auth status`、`lark-cli api GET /open-apis/calendar/v4/calendars` を順番に実行し、戻り値の `ok`、identity、stderrの分離を記録するのが具体的です。

ショートカット、API、Raw APIの使い分け

AIエージェントの場合、インストールコマンドは同じですが、`lark-cli config init --new` と `lark-cli auth login --recommend` はバックグラウンドで実行し、それぞれ認証URLを出力してユーザーに送信します。ユーザーがブラウザで操作を完了すると、コマンドは自動的に終了します。`lark-cli auth status` で結果を確認します。READMEは、一部のステップでユーザーがブラウザでの操作を完了する必要があると注意書きしています。CIパイプラインなどのヘッドレス環境での動作については記載がありません。

「ショートカット、API、Raw APIの使い分け」では、cliの設定と実行結果を確認します。確認用には `lark-cli calendar +agenda --format json`、`lark-cli auth status`、`lark-cli api GET /open-apis/calendar/v4/calendars` を順番に実行し、戻り値の `ok`、identity、stderrの分離を記録するのが具体的です。

エージェント連携で見るJSON応答契約

認証関連のコマンドは `auth login`、`auth logout`、`auth status`、`auth check`、`auth scopes`、`auth list` です。`auth login` は対話式TUIのほか、`--domain calendar,task` でドメインを絞り込む、`--recommend` で一般的なスコープを自動選択する、`--scope "calendar:calendar:read"` で正確なスコープを指定する、`--no-wait` でエージェント向けに検証URLをすぐ返す、といったフラグをサポートします。後から `auth login --device-code <DEVICE_CODE>` でポーリングを再開できます。コマンドは `--as user` または `--as bot` でユーザーまたはボットとして実行でき、READMEでは `lark-cli calendar +agenda --as user` と `lark-cli im +messages-send --as bot --chat-id "oc_xxx" --text "Hello"` が例として示されています。READMEには全スコープの一覧やトークンの有効期限の説明はありません。

「エージェント連携で見るJSON応答契約」では、cliの設定と実行結果を確認します。確認用には `lark-cli calendar +agenda --format json`、`lark-cli auth status`、`lark-cli api GET /open-apis/calendar/v4/calendars` を順番に実行し、戻り値の `ok`、identity、stderrの分離を記録するのが具体的です。

スコープとuser/bot切り替えの扱い

ショートカットは `+` プレフィックスを使い、人間とAIの両方にとって使いやすく設計されており、スマートデフォルト、テーブル出力、ドライラン・プレビューを備えています。例として `lark-cli calendar +agenda` や `lark-cli docs +create --doc-format markdown --content $'<title>Weekly Report</title>\n# Progress\n- Completed feature X'` が挙げられています。APIコマンドはLark OAPIメタデータから自動生成され、評価と品質ゲートを経て、100以上のコマンドがプラットフォームのエンドポイントに1対1で対応しています（例：`lark-cli calendar calendars list`）。Raw API呼び出しは2500以上のエンドポイントをカバーし、例として `lark-cli api GET /open-apis/calendar/v4/calendars` があります。READMEには、プラットフォームAPIの変更に合わせてコマンドが自動更新されるかどうかは記載されていません。

「スコープとuser/bot切り替えの扱い」では、cliの設定と実行結果を確認します。確認用には `lark-cli calendar +agenda --format json`、`lark-cli auth status`、`lark-cli api GET /open-apis/calendar/v4/calendars` を順番に実行し、戻り値の `ok`、identity、stderrの分離を記録するのが具体的です。

入力保護とリスク制御の既定値

出力フォーマットは5種類あります：`--format json`（デフォルト）、`pretty`、`table`、`ndjson`、`csv`。JSONでは、成功時はstdoutに出力され、終了コード0で `{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }` のようなボディになります。エラー時はstderrに出力され、終了コードは非ゼロで、`{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }` のようなボディになります。READMEは、成功の判定は `ok == true` または終了コードを見るべきであり、`code == 0` ではないと警告しています。成功のエンベロープには `code` フィールドがなく、`code` はエラーオブジェクト内の上流OpenAPIコードとしてのみ現れるためです。完全なエラータクソノミーは `errs/ERROR_CONTRACT.md` にありますが、READMEにはその内容は記載されていません。

「入力保護とリスク制御の既定値」では、cliの設定と実行結果を確認します。確認用には `lark-cli calendar +agenda --format json`、`lark-cli auth status`、`lark-cli api GET /open-apis/calendar/v4/calendars` を順番に実行し、戻り値の `ok`、identity、stderrの分離を記録するのが具体的です。

MITライセンスとLark側の利用条件

READMEは、このツールがAIエージェントによって呼び出される可能性があり、モデルの幻覚、予測不能な実行、プロンプトインジェクションなどのリスクを伴うと警告しています。認証後、エージェントは付与されたスコープ内でユーザーIDの下で動作するため、機密データの漏洩や不正な操作を引き起こす可能性があります。デフォルトの保護には、入力インジェクション対策、ターミナル出力のサニタイズ、OSネイティブのキーチェーン資格情報ストレージが含まれます。また、公式のFeishu/Lark HTTPSドメインへのOpenAPIリクエストには、オペレーティングシステムの種類とデバイスのハードウェアモデルという最小限のリスク制御シグナルが添付されます。これらは `lark-cli config risk-control off` で無効化、`on` で有効化、`default` でデフォルトに戻せます。READMEはデフォルト設定を変更しないこと、統合されたボットをグループチャットに追加せずプライベートアシスタントとして使用することを強く推奨しています。

「MITライセンスとLark側の利用条件」では、cliの設定と実行結果を確認します。確認用には `lark-cli calendar +agenda --format json`、`lark-cli auth status`、`lark-cli api GET /open-apis/calendar/v4/calendars` を順番に実行し、戻り値の `ok`、identity、stderrの分離を記録するのが具体的です。

ライセンスと外部契約の確認点

このプロジェクトはMITライセンスで提供され、著作権はLark Technologies Pte. Ltd.に帰属します。MITライセンスは、ライセンス本文の条件に従って、ソフトウェアの複製、変更、結合、公開、配布、サブライセンス、販売を許可します。ライセンスはソフトウェアを「現状のまま」提供し、いかなる種類の保証もありません。READMEは、CLIを使用するとLark/飛書オープンプラットフォームAPIを呼び出すことになり、FeishuとLarkの利用規約やプライバシーポリシーを含む契約を遵守する必要があると付け加えています。ライセンス本文は、セキュリティ保証、サポート、本番環境での適合性については何も述べていません。

「ライセンスと外部契約」では、cliの設定と実行結果を確認します。確認用には `lark-cli calendar +agenda --format json`、`lark-cli auth status`、`lark-cli api GET /open-apis/calendar/v4/calendars` を順番に実行し、戻り値の `ok`、identity、stderrの分離を記録するのが具体的です。

編集部の結論

larksuite/cliは、Larkや飛書の操作を短いショートカットからRaw APIまで同じ入口に載せたい個人開発者や社内エージェント基盤に向きます。導入前には `lark-cli config init` と `lark-cli auth login --recommend` を検証用アプリで実行し、`--format json` の成功時と失敗時のstdout・stderr、`--as user` と `--as bot` の権限差、`config risk-control` の初期値を確認してください。

公式情報源

1. Official README
2. Project repository
3. Release notes