cli

LobeHub CLI 開発ガイド

概要

LobeHub CLI（@lobehub/cli）は、LobeHub サービスを管理し、操作するためのコマンドラインツールです。Commander.js + TypeScript で構築されています。

• パッケージ：apps/cli/
• エントリーポイント：apps/cli/src/index.ts
• バイナリ：lh、lobe、lobehub（すべて同じ CLI のエイリアスです）
• ビルド：tsup
• ランタイム：Node.js / Bun

アーキテクチャ

apps/cli/src/
├── index.ts                  # Entry point — parses argv, invokes program.ts
├── program.ts                # Builds the Commander program, registers every command
├── api/
│   ├── acceptance/           # `lh acceptance`: review loop, rounds (run/), plans, criteria, rubrics; `lh verify` aliases
│   ├── client.ts             # tRPC client (type-safe backend API)
│   └── http.ts               # Raw HTTP utilities
├── auth/
│   ├── credentials.ts        # Encrypted credential storage (AES-256-GCM)
│   ├── identity.ts           # Account fingerprint for machine-local state
│   ├── refresh.ts            # Token auto-refresh
│   └── resolveToken.ts       # Token resolution (flag > stored)
├── commands/                 # All CLI commands (one file per command group)
│   ├── agent.ts              # Agent CRUD + run
│   ├── agent-group.ts        # Agent group CRUD
│   ├── agent-signal/         # Inspect and trigger Agent Signal source events
│   ├── artifact.ts           # Publish local HTML pages as artifacts
│   ├── bot.ts                # Bot integrations (channels, access policies, messengers)
│   ├── completion.ts         # Shell completion script output
│   ├── config.ts             # whoami, usage
│   ├── connect.ts            # Device gateway connection + daemon
│   ├── device.ts             # Manage connected devices
│   ├── doc.ts                # Document management
│   ├── doctor.ts             # Machine diagnostics (runtime, endpoints, credentials, readiness)
│   ├── eval.ts               # Evaluation workflows & benchmarks
│   ├── file.ts               # File management
│   ├── generate/             # Content generation (text/image/video/tts/asr)
│   ├── goal.ts               # Long-horizon Goal Graphs
│   ├── hetero.ts             # Run heterogeneous agent CLIs, stream their output
│   ├── kb.ts                 # Knowledge base management
│   ├── login.ts              # OIDC Device Code Flow / API key auth
│   ├── logout.ts             # Clear credentials
│   ├── man.ts                # CLI manual pages
│   ├── memory.ts             # User memory management
│   ├── message.ts            # Message management
│   ├── migrate/              # Import data from external tools (OpenClaw, ChatGPT, Claude, etc.)
│   ├── model.ts              # AI model management
│   ├── notification.ts       # Notification delivery settings (personal / workspace)
│   ├── notify.ts             # Send a callback message to a topic to trigger the agent
│   ├── plugin.ts             # Plugin management
│   ├── project.ts            # Goal-oriented project management
│   ├── provider.ts           # AI provider management
│   ├── search.ts             # Global search
│   ├── session-group.ts      # Agent session group management
│   ├── skill.ts              # Agent skill management
│   ├── status.ts             # Gateway connectivity check
│   ├── task/                 # Agent task management (assignees, checkpoints, deps, review)
│   ├── thread.ts             # Message thread management
│   ├── topic.ts              # Conversation topic management
│   ├── trace/                # Inspect and replay recorded agent execution traces
│   ├── update.ts             # Self-update to the latest published version
│   ├── user.ts               # User account & settings
│   └── workspace.ts          # Workspace list/scope/members/usage/audit
├── daemon/
│   └── manager.ts            # Background daemon process management
├── tools/
│   ├── shell.ts              # Shell command execution (for gateway)
│   └── file.ts               # File operations (for gateway)
├── settings/
│   └── index.ts              # Persistent settings (~/.lobehub/)
├── utils/
│   ├── logger.ts             # Logging (verbose mode)
│   ├── format.ts             # Table output, JSON, timeAgo/timeUntil, truncate
│   └── agentStream.ts        # WebSocket streaming for agent runs and task follow
└── constants/
    └── urls.ts               # Official server & gateway URLs

コマンドグループ

コマンド	エイリアス	説明
lh login	-	OIDC デバイスコードフローまたは API キーで認証します
lh logout	-	保存された認証情報を消去します
lh connect	-	デバイスゲートウェイへの接続とデーモンの管理
lh device	-	接続済みデバイスを管理します
lh status	-	ゲートウェイの接続状態をすばやく確認します
lh doctor	-	マシンの準備状態（ランタイム、エンドポイント、認証情報、スコープ、デバイス、エージェント）を診断します
lh agent	-	エージェントの CRUD、実行、ステータス
lh agent-group	-	エージェントグループの CRUD
lh agent-signal	-	Agent Signal のソースイベントを調査してトリガーします
lh hetero	-	異種エージェント CLI（Claude Code、Codex など）を実行し、その出力をストリーミングします
lh goal	-	長期目標の Goal Graphs を実行します
lh project	-	目標指向のプロジェクトを管理します
lh task	-	エージェントタスク（担当者、チェックポイント、依存関係、レビュー）を管理します
lh thread	-	メッセージスレッドを管理します
lh trace	-	記録されたエージェント実行トレースを調査して再生します
lh acceptance	-	納品物の受け入れ：レビューループ、ラウンド、実行ごとのチェック計画、基準、ルーブリック
lh verify	-	lh acceptance コマンドの非推奨エイリアス
lh eval	-	評価ワークフローとベンチマークを管理します
lh generate	gen	コンテンツ生成（テキスト、画像、動画、tts、asr、ダウンロード）
lh doc	-	ドキュメントの CRUD、一括作成、解析、トピックとのリンク
lh file	-	ファイルの一覧表示、閲覧、削除、最近のファイル
lh artifact	-	ローカル HTML ページをアーティファクトとして公開します
lh kb	-	ナレッジベースの CRUD、フォルダー、ドキュメント、アップロード、ツリービュー
lh memory	-	ユーザーメモリの CRUD と抽出
lh message	-	メッセージの一覧表示、検索、削除、件数、ヒートマップ
lh topic	-	トピックの CRUD、検索、最近の項目
lh notify	-	トピックにコールバックメッセージを送信し、エージェントに処理を実行させます
lh notification	-	通知設定：表示、チャンネル、IM プラットフォーム、種類の有効化／無効化
lh migrate	-	外部ツール（OpenClaw、ChatGPT、Claude など）からデータをインポートします
lh bot	-	ボット連携（チャンネル、アクセス方針、メッセンジャー）を管理します
lh skill	-	スキルの CRUD とインポート（GitHub／URL／マーケット）
lh model	-	モデルの CRUD、切り替え、一括切り替え、消去
lh provider	-	プロバイダーの CRUD、設定、テスト、切り替え
lh plugin	-	プラグインのインストール、アンインストール、更新
lh search	-	すべての種類を対象とした横断検索
lh session-group	-	エージェントセッショングループを管理します
lh workspace	ws	ワークスペースの一覧表示、スコープの切り替え、メンバー、招待、使用状況
lh user	-	ユーザーアカウントと設定を管理します
lh whoami	-	現在のユーザー情報（解決されたワークスペーススコープを含む）
lh usage	-	月別／日別の使用状況統計
lh man	-	CLI またはサブコマンドのマニュアルページを表示します
lh completion	-	シェル補完スクリプトを出力します
lh update	-	CLI を公開済みの最新バージョンに更新します

ワークスペースのスコープ

すべてのコマンドは、次の順序で解決される1つのスコープに対して実行されます。

1. workspace、device、topic コマンドで指定する明示的な --workspace <id|slug>（slug は lh workspace list を使って解決され、一致するものがない場合は失敗します。workspace.list を呼び出せない認証情報（workspace:read の権限がないワークスペースに紐づく API キーなど）の場合は、解決をスキップして値を ID として送信し、警告を表示するため、ID を渡す必要があります）。 lh connect --workspace で指定できるのは ID のみです。
2. LOBEHUB_WORKSPACE_ID 環境変数（ID のみ）
3. lh workspace use <id|slug> で永続化されたスコープ
4. 個人コンテンツ（ワークスペースなし）

永続化されたスコープは、選択時のアカウントとサーバーに紐づいています。どちらかが変わった場合（別の lh login、--server の切り替え）、新しい ID が所属していないワークスペースヘッダーを付与しないよう、スコープは無視され、古いものとして報告されます。lh logout を実行するとクリアされます。lh whoami と lh workspace current は、どちらも4つのソースのうちどれが有効かを表示します。

API キー認証にはローカルのアカウント ID がないため、保存したスコープを紐づける対象がありません。そのため、呼び出し元は代わりに LOBEHUB_WORKSPACE_ID を渡します。

新しいコマンドの追加

1. コマンドファイルを作成する

apps/cli/src/commands/<name>.ts を作成します。

import type { Command } from 'commander';
import { getTrpcClient } from '../api/client';
import { outputJson, printTable, truncate } from '../utils/format';

export function register<Name>Command(program: Command) {
  const cmd = program.command('<name>').description('...');

  // Subcommands
  cmd
    .command('list')
    .description('List items')
    .option('-L, --limit <n>', 'Maximum number of items', '30')
    .option('--json [fields]', 'Output JSON, optionally specify fields')
    .action(async (options) => {
      const client = await getTrpcClient();
      const result = await client.<router>.<procedure>.query({ ... });
      // Handle output
    });
}

2. エントリーポイントに登録する

apps/cli/src/index.ts で登録します。

import { registerNewCommand } from './commands/new';
// ...
registerNewCommand(program);

3. テストを追加する

コマンドファイルと同じ場所に apps/cli/src/commands/<name>.test.ts を作成します。

規約

出力パターン

一覧表示／表示コマンドでは、次の一貫したパターンを使用します。

• --json [fields] - フィールドを任意で絞り込める JSON 出力
• --yes - 破壊的な操作の確認を省略
• -L, --limit <n> - ページネーションの上限（デフォルト：30）
• -v, --verbose - 詳細ログ

テーブル出力

const rows = items.map((item) => [item.id, truncate(item.title, 40), timeAgo(item.updatedAt)]);
printTable(rows, ['ID', 'TITLE', 'UPDATED']);

JSON 出力

if (options.json !== undefined) {
  const fields = typeof options.json === 'string' ? options.json : undefined;
  outputJson(items, fields);
  return;
}

認証

認証が必要なコマンドでは、トークンを自動的に解決する getTrpcClient() を使用します。

const client = await getTrpcClient();
// client.router.procedure.query/mutate(...)

確認プロンプト

import { confirm } from '../utils/format';
if (!options.yes) {
  const ok = await confirm('Are you sure?');
  if (!ok) return;
}

保存場所

ファイル	パス	用途
認証情報	~/.lobehub/credentials.json	暗号化されたトークン（AES-256-GCM）
設定	~/.lobehub/settings.json	カスタムサーバー／ゲートウェイ URL
ワークスペース	~/.lobehub/active-workspace	アクティブなスコープと、紐づけられたアカウント／サーバー
デーモン PID	~/.lobehub/daemon.pid	バックグラウンドプロセスの PID
デーモンの状態	~/.lobehub/daemon.status.json	接続状態の JSON
デーモンログ	~/.lobehub/daemon.log	デーモンの出力ログ

ベースディレクトリ（~/.lobehub/）は、LOBEHUB_CLI_HOME 環境変数で上書きできます（例：開発モードで分離する場合は LOBEHUB_CLI_HOME=.lobehub-dev）。

主な依存関係

• commander - CLI フレームワーク
• @trpc/client + superjson - 型安全な API クライアント
• @lobechat/device-gateway-client - WebSocket ゲートウェイ接続
• @lobechat/local-file-shell - ローカルシェル／ファイルツールの実行
• picocolors - ターミナルの色付け
• ws - WebSocket
• diff - テキスト差分の取得
• fast-glob - ファイルパターンの照合

開発

開発モードで実行する

開発モードでは LOBEHUB_CLI_HOME=.lobehub-dev を使用して、認証情報をグローバルな ~/.lobehub/ ディレクトリから分離します。そのため、開発用と本番用の設定が競合することはありません。

# Run a command in dev mode (from apps/cli/)
cd apps/cli && bun run dev -- <command>

# This is equivalent to:
LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>

ローカル開発サーバーへの接続

CLI からローカル開発サーバー（例：localhost:3011）に接続してテストするには、次の手順に従います。

Step 1: ローカルサーバーを起動する

# From cloud repo root
bun run dev
# Server starts on http://localhost:3011 (or configured port)

Step 2: デバイスコードフローを使ってローカルサーバーにログインする

cd apps/cli && bun run dev -- login --server http://localhost:3011

次の処理が行われます。

1. POST http://localhost:3011/oidc/device/auth を呼び出してデバイスコードを取得します
2. http://localhost:3011/oidc/device?user_code=XXXX-YYYY のような URL が表示されます
3. ブラウザーで URL を開き、ログインして認証します
4. 認証情報を apps/cli/.lobehub-dev/credentials.json に保存します
5. サーバー URL を apps/cli/.lobehub-dev/settings.json に保存します

ログイン後は、それ以降のすべての bun run dev -- <command> の呼び出しでローカルサーバーが使用されます。

Step 3: ローカルサーバーに対してコマンドを実行する

cd apps/cli && bun run dev -- task list
cd apps/cli && bun run dev -- task create -i "Test task" -n "My Task"
cd apps/cli && bun run dev -- agent list

トラブルシューティング：

• ログインで invalid_grant が返された場合は、ローカル OIDC プロバイダーが正しく設定されていることを確認してください（.env の OIDC_* 環境変数を確認します）
• API 呼び出しで UNAUTHORIZED が返された場合は、トークンの有効期限が切れている可能性があります。bun run dev -- login --server http://localhost:3011 を再度実行してください
• 開発用認証情報は ~/.lobehub/ ではなく、apps/cli/.lobehub-dev/ に保存されます（gitignore 対象）

ローカル環境と本番環境の切り替え

# Dev mode (local server) — uses .lobehub-dev/
cd apps/cli && bun run dev -- <command>

# Production (app.lobehub.com) — uses ~/.lobehub/
lh <command>

2 つの環境は、異なる認証情報ディレクトリによって完全に分離されています。

ビルドとテスト

# Build CLI
cd apps/cli && bun run build

# Unit tests
cd apps/cli && bun run test

# E2E tests (requires authenticated CLI)
cd apps/cli && bunx vitest run e2e/kb.e2e.test.ts

# Link globally for testing (installs lh/lobe/lobehub commands)
cd apps/cli && bun run cli:link

コマンドの詳細なリファレンス

各コマンドグループについては、references/ を参照してください。

• エージェント：references/agent.md（CRUD、実行、ステータス）
• ゴール：references/goal.md（計画ターン、状態、イベント、ライフサイクル、判断）
• コンテンツ生成：references/generate.md（テキスト、画像、動画、tts、asr、ダウンロード）
• ナレッジとファイル：references/knowledge.md（kb、ファイル、doc）
• 会話：references/conversation.md（トピック、メッセージ）
• メモリー：references/memory.md（メモリー管理、抽出）
• スキルとプラグイン：references/skills-plugins.md（スキル、プラグイン）
• モデルとプロバイダー：references/models-providers.md（モデル、プロバイダー）
• 検索と設定：references/search-config.md（検索、whoami、使用状況、ワークスペース）