LobeHub CLI Development Guide

Overview

LobeHub CLI (@lobehub/cli) is a command-line tool for managing and interacting with LobeHub services. Built with Commander.js + TypeScript.

• Package: apps/cli/
• Entry: apps/cli/src/index.ts
• Binaries: lh, lobe, lobehub (all aliases for the same CLI)
• Build: tsup
• Runtime: Node.js / Bun

Architecture

apps/cli/src/
├── index.ts                  # Entry point — parses argv, invokes program.ts
├── program.ts                # Builds the Commander program, registers every command
├── api/
│   ├── 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
│   ├── 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
│   ├── verify.ts             # Agent Run verification machinery (criteria, rubrics, check plans)
│   ├── verifyAcceptance.ts   # `lh acceptance`: cross-round delivery review loop
│   └── 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        # SSE streaming for agent runs
└── constants/
    └── urls.ts               # Official server & gateway URLs

Command Groups

Command	Alias	Description
lh login	-	Authenticate via OIDC Device Code Flow or API key
lh logout	-	Clear stored credentials
lh connect	-	Device gateway connection & daemon management
lh device	-	Manage connected devices
lh status	-	Quick gateway connectivity check
lh doctor	-	Diagnose machine readiness (runtime, endpoints, credentials, scope, device, agent)
lh agent	-	Agent CRUD, run, status
lh agent-group	-	Agent group CRUD
lh agent-signal	-	Inspect and trigger Agent Signal source events
lh hetero	-	Run heterogeneous agent CLIs (Claude Code, Codex, etc.), stream their output
lh goal	-	Run long-horizon Goal Graphs
lh project	-	Manage goal-oriented projects
lh task	-	Manage agent tasks (assignees, checkpoints, deps, review)
lh thread	-	Manage message threads
lh trace	-	Inspect and replay recorded agent execution traces
lh verify	-	Agent Run verification machinery — criteria, rubrics, per-run check plans
lh acceptance	-	Delivery acceptances — the cross-round review loop (checks, feedback, decision)
lh eval	-	Manage evaluation workflows and benchmarks
lh generate	gen	Content generation (text, image, video, tts, asr, download)
lh doc

Workspace Scope

Every command runs against one scope, resolved in this order:

1. an explicit --workspace <id> on the commands that take it
2. the LOBEHUB_WORKSPACE_ID env var
3. the scope persisted by lh workspace use <id|slug>
4. personal content (no workspace)

The persisted scope is bound to the account and server it was chosen under. If either changes — a different lh login, a --server switch — it is ignored and reported as stale rather than attaching a workspace header the new identity has no membership in. lh logout clears it. lh whoami and lh workspace current both print which of the four sources is in effect.

API-key auth carries no local account identity, so there is nothing to bind a saved scope to — those callers pass LOBEHUB_WORKSPACE_ID instead.

Adding a New Command

1. Create Command File

Create 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. Register in Entry Point

In apps/cli/src/index.ts:

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

3. Add Tests

Create apps/cli/src/commands/<name>.test.ts alongside the command file.

Conventions

Output Patterns

All list/view commands follow consistent patterns:

• --json [fields] - JSON output with optional field filtering
• --yes - Skip confirmation for destructive ops
• -L, --limit <n> - Pagination limit (default: 30)
• -v, --verbose - Verbose logging

Table Output

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

JSON Output

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

Authentication

Commands that need auth use getTrpcClient() which auto-resolves tokens:

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

Confirmation Prompts

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

Storage Locations

File	Path	Purpose
Credentials	~/.lobehub/credentials.json	Encrypted tokens (AES-256-GCM)
Settings	~/.lobehub/settings.json	Custom server/gateway URLs
Workspace	~/.lobehub/active-workspace	Active scope + the account/server it is bound to
Daemon PID	~/.lobehub/daemon.pid	Background process PID
Daemon Status	~/.lobehub/daemon.status.json	Connection status JSON
Daemon Log	~/.lobehub/daemon.log	Daemon output log

The base directory (~/.lobehub/) can be overridden with the LOBEHUB_CLI_HOME env var (e.g. LOBEHUB_CLI_HOME=.lobehub-dev for dev mode isolation).

Key Dependencies

• commander - CLI framework
• @trpc/client + superjson - Type-safe API client
• @lobechat/device-gateway-client - WebSocket gateway connection
• @lobechat/local-file-shell - Local shell/file tool execution
• picocolors - Terminal colors
• ws - WebSocket
• diff - Text diffing
• fast-glob - File pattern matching

Development

Running in Dev Mode

Dev mode uses LOBEHUB_CLI_HOME=.lobehub-dev to isolate credentials from the global ~/.lobehub/ directory, so dev and production configs never conflict.

# 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>

Connecting to Local Dev Server

To test CLI against a local dev server (e.g. localhost:3011):

Step 1: Start the local server

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

Step 2: Login to local server via Device Code Flow

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

This will:

1. Call POST http://localhost:3011/oidc/device/auth to get a device code
2. Print a URL like http://localhost:3011/oidc/device?user_code=XXXX-YYYY
3. Open the URL in your browser — log in and authorize
4. Save credentials to apps/cli/.lobehub-dev/credentials.json
5. Save server URL to apps/cli/.lobehub-dev/settings.json

After login, all subsequent bun run dev -- <command> calls will use the local server.

Step 3: Run commands against local server

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

Troubleshooting:

• If login returns invalid_grant, make sure the local OIDC provider is properly configured (check OIDC_* env vars in .env)
• If you get UNAUTHORIZED on API calls, your token may have expired — run bun run dev -- login --server http://localhost:3011 again
• Dev credentials are stored in apps/cli/.lobehub-dev/ (gitignored), not in ~/.lobehub/

Switching Between Local and Production

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

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

The two environments are completely isolated by different credential directories.

Build & Test

# 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

Detailed Command References

See references/ for each command group:

• Agent: references/agent.md (CRUD, run, status)
• Content Generation: references/generate.md (text, image, video, tts, asr, download)
• Knowledge & Files: references/knowledge.md (kb, file, doc)
• Conversation: references/conversation.md (topic, message)
• Memory: references/memory.md (memory management, extraction)
• Skills & Plugins: references/skills-plugins.md (skill, plugin)
• Models & Providers: references/models-providers.md (model, provider)
• Search & Config: references/search-config.md (search, whoami, usage, workspace)