Cli

Command Groups

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

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)