Cli

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, registers all commands
├── api/
│   ├── client.ts             # tRPC client (type-safe backend API)
│   └── http.ts               # Raw HTTP utilities
├── auth/
│   ├── credentials.ts        # Encrypted credential storage (AES-256-GCM)
│   ├── 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
│   ├── config.ts             # whoami, usage
│   ├── connect.ts            # Device gateway connection + daemon
│   ├── doc.ts                # Document management
│   ├── file.ts               # File management
│   ├── generate/             # Content generation (text/image/video/tts/asr)
│   ├── kb.ts                 # Knowledge base management
│   ├── login.ts              # OIDC Device Code Flow auth
│   ├── logout.ts             # Clear credentials
│   ├── memory.ts             # User memory management
│   ├── message.ts            # Message management
│   ├── model.ts              # AI model management
│   ├── plugin.ts             # Plugin management
│   ├── provider.ts           # AI provider management
│   ├── search.ts             # Global search
│   ├── skill.ts              # Agent skill management
│   ├── status.ts             # Gateway connectivity check
│   └── topic.ts              # Conversation topic management
├── 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, truncate
│   └── agentStream.ts        # SSE streaming for agent runs
└── constants/
    └── urls.ts               # Official server & gateway URLs

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)

Agent Commands

Manage AI agents: create, edit, delete, list, run, and check status.

Source: apps/cli/src/commands/agent.ts

lh agent list

List all agents.

lh agent list [-L [-k [--json [fields]] < n > ] < keyword > ]

Table columns: ID, TITLE, DESCRIPTION, MODEL

---

lh agent view <agentId>

View agent configuration details.

lh agent view [fields]] < agentId > [--json

Displays: Title, description, model, provider, system role, plugins, tools.

---

lh agent create

Create a new agent.

lh agent create [options]

Output: Created agent ID and session ID.

---

lh agent edit <agentId>

Update an existing agent. Same options as create, all optional. Only specified fields are updated.

lh agent edit [-m [-s ... < agentId > [-t < title > ] < model > ] < role > ]

---

lh agent delete <agentId>

Delete an agent.

lh agent delete < agentId > [--yes]

Requires confirmation unless --yes is provided.

---

lh agent duplicate <agentId>

Duplicate an existing agent.

lh agent duplicate < agentId > [-t < title > ]

Output: New agent ID.

---

lh agent run

Start an agent execution (streaming SSE).

lh agent run [options]

Streaming Behavior

Uses utils/agentStream.ts to handle Server-Sent Events:

1. Sends agent run request to backend 2. Streams SSE events in real-time 3. Displays: text chunks, tool call status, operation progress 4. Shows final token usage and cost summary

Replay Mode

--replay <file> reads a saved JSON event stream for offline debugging without server connection.

---

lh agent status <operationId>

Check agent operation status.

lh agent status [fields]] [--history] [--history-limit < operationId > [--json < n > ]

Displays: Status (running/completed/failed), steps count, tokens used, cost, error info, timestamps.

Conversation Commands (Topic & Message)

Topic Management (lh topic)

Manage conversation topics (threads).

Source: apps/cli/src/commands/topic.ts

lh topic list

lh topic list [--agent-id [-L [--page [--json [fields]] < id > ] < n > ] < n > ]

Table columns: ID, TITLE, FAV, UPDATED

lh topic search <keywords>

lh topic search [--json [fields]] < keywords > [--agent-id < id > ]

lh topic create

lh topic create -t [--favorite] < title > [--agent-id < id > ]

lh topic edit <id>

lh topic edit [--favorite] [--no-favorite] < id > [-t < title > ]

lh topic delete <ids...>

lh topic delete [--yes] < id1 > [id2...]

lh topic recent

lh topic recent [-L [--json [fields]] < n > ]

---

Message Management (lh message)

Manage chat messages within topics.

Source: apps/cli/src/commands/message.ts

lh message list

lh message list [options] [--json [fields]]

Table columns: ID, ROLE, CONTENT, CREATED

Note: When --topic-id or --agent-id is provided, uses message.getMessages; otherwise uses message.listAll.

lh message search <keywords>

lh message search [fields]] < keywords > [--json

Full-text search across all messages.

lh message delete <ids...>

lh message delete [--yes] < id1 > [id2...]

lh message count

lh message count [--start [--end [--json] < date > ] < date > ]

Output: Total message count for the specified period.

lh message heatmap

lh message heatmap [--json]

Output: Activity heatmap data showing message frequency over time.

Content Generation Commands

Generate text, images, videos, speech, and transcriptions.

Source: apps/cli/src/commands/generate/

Command Structure

lh generate (alias: gen)
├── text <prompt>                          # Text generation
├── image <prompt>                         # Image generation
├── video <prompt>                         # Video generation
├── tts <text>                             # Text-to-speech
├── asr <audioFile>                        # Audio-to-text (speech recognition)
├── download <generationId> <asyncTaskId>  # Wait & download generation result
├── status <generationId> <asyncTaskId>    # Check async task status
└── list                                   # List generation topics

⚠️ Important: status and download require an asyncTaskId (UUID format, e.g.

7ad0eb13-e9a5-4403-8070-1f7fe95b2f95), not the generation ID (gen_xxx).

The asyncTaskId is printed after "→ Task" in the video / image command output.

---

lh generate text <prompt> / lh gen text <prompt>

Generate text completion.

Source: apps/cli/src/commands/generate/text.ts

lh gen text "Explain quantum computing" [options]
echo "context" | lh gen text "summarize" --pipe

Pipe Mode

When --pipe is used, reads stdin and prepends it to the prompt. Useful for piping file contents:

cat README.md | lh gen text "summarize this" --pipe

---

lh generate image <prompt> / lh gen image <prompt>

Generate images from text prompt. This is an async operation — the command submits the task and returns a generation ID + async task ID for tracking.

Source: apps/cli/src/commands/generate/image.ts

lh gen image "A sunset over mountains" [options]
lh gen image "A cute cat" --model dall-e-3 --provider openai --json

Output (non-JSON):

✓ Image generation started
  Batch ID: gb_xxx
  1 image(s) queued
  Generation gen_xxx → Task 7ad0eb13-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                            This is the asyncTaskId — use this for status/download

Use "lh generate status <generationId> <asyncTaskId>" to check progress.

Typical workflow:

# 1. Submit generation — note down BOTH IDs from the output
lh gen image "A cute cat"
#   Generation gen_abc123 → Task 7ad0eb13-e9a5-4403-8070-1f7fe95b2f95

# 2. Wait & download using generationId + asyncTaskId (the UUID)
lh gen download gen_abc123 7ad0eb13-e9a5-4403-8070-1f7fe95b2f95 -o cat.png

---

lh generate video <prompt> / lh gen video <prompt>

Generate video from text prompt. This is an async operation.

Source: apps/cli/src/commands/generate/video.ts

lh gen video "A cat playing piano" -m < model > -p < provider > [options]

Note: Unlike image, video requires -m and -p (no defaults). Use lh model list <provider> --type video to find available video models.

Output (non-JSON):

✓ Video generation started
  Batch ID: gb_xxx
  Generation gen_xxx → Task 7ad0eb13-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                            This is the asyncTaskId — use this for status/download

Use "lh generate status <generationId> <asyncTaskId>" to check progress.

Typical workflow:

# 1. Find available video models for a provider
lh model list volcengine --json | grep -i seedance

# 2. Submit generation — note down BOTH IDs from the output
lh gen video "A cat on a runway" -m doubao-seedance-2-0-260128 -p volcengine \
  --aspect-ratio 9:16 --duration 5 --resolution 1080p
#   Generation gen_abc123 → Task 7ad0eb13-e9a5-4403-8070-1f7fe95b2f95

# 3. Wait & download using generationId + asyncTaskId (the UUID)
lh gen download gen_abc123 7ad0eb13-e9a5-4403-8070-1f7fe95b2f95 -o result.mp4 --timeout 600

---

lh generate tts <text> / lh gen tts <text>

Text-to-speech generation.

Source: apps/cli/src/commands/generate/tts.ts

lh gen tts "Hello, world!" [options]

---

lh generate asr <audioFile> / lh gen asr <audioFile>

Audio-to-text transcription (Automatic Speech Recognition).

Source: apps/cli/src/commands/generate/asr.ts

lh gen asr recording.wav [options]

---

lh generate download <generationId> <asyncTaskId>

Wait for an async generation task to complete and download the result file.

Source: apps/cli/src/commands/generate/index.ts

⚠️ <asyncTaskId> is the UUID printed after "→ Task" in the video/image output.

Do not pass the generation ID (gen_xxx) here — that will cause a server error.

lh gen download <generationId> <asyncTaskId> [-o output.png]
lh gen download gen_xxx 7ad0eb13-xxxx-xxxx-xxxx-xxxxxxxxxxxx -o ~/Desktop/result.mp4 --timeout 600

Behavior:

1. Polls generation.getGenerationStatus at the specified interval 2. Shows live progress: ⋯ Status: processing... (42s) 3. On success: downloads asset URL to local file 4. On error / wrong ID: displays a clear message pointing to the correct ID format 5. On timeout: suggests using lh gen status to check later

---

lh generate status <generationId> <asyncTaskId>

Check the status of an async generation task.

⚠️ <asyncTaskId> is the UUID printed after "→ Task" in the video/image output.

Do not pass the generation ID (gen_xxx) here — that will cause a server error.

lh gen status <generationId> <asyncTaskId> [--json]
lh gen status gen_xxx 7ad0eb13-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Displays:

• Status (color-coded): success (green), error (red), processing (yellow), pending (cyan)
• Error message (if failed)
• Asset URL and thumbnail URL (if completed)

---

lh generate list

List all generation topics.

lh gen list [--json [fields]]

Table columns: ID, TITLE, TYPE, UPDATED

---

Backend Architecture

Image and video generation use an async task pattern:

1. Create topic → generationTopic.createTopic 2. Submit generation → image.createImage / video.createVideo

• Creates batch + generation + asyncTask records in a DB transaction
• Triggers async background task (image via createAsyncCaller, video via initModelRuntimeFromDB)
• Returns { data: { batch, generations }, success } with asyncTaskId in each generation

3. Poll status → generation.getGenerationStatus

• Input: { generationId, asyncTaskId } — both are required, and asyncTaskId must be the

UUID from the async_tasks table, not gen_xxx

• Returns { status, error, generation } (generation includes asset URLs on success)
• Before querying, calls checkTimeoutTasks which marks tasks as error if they have been

pending or processing for more than \~5 minutes (ASYNC_TASK_TIMEOUT = 298s)

Server routes:

• apps/server/src/routers/lambda/image/index.ts — image creation (uses authedProcedure + serverDatabase)
• apps/server/src/routers/lambda/video/index.ts — video creation (uses authedProcedure + serverDatabase)
• apps/server/src/routers/lambda/generation.ts — status checking
• packages/database/src/models/asyncTask.ts — AsyncTaskModel including checkTimeoutTasks

Note: Image/video routes do NOT use the keyVaults middleware — they read API keys from the database via initModelRuntimeFromDB or createAsyncCaller.

Knowledge Base, File & Document Commands

Knowledge Base (lh kb)

Manage knowledge bases for RAG (Retrieval-Augmented Generation). Supports directory tree structure with folders, documents, and file uploads.

Source: apps/cli/src/commands/kb.ts

lh kb list

lh kb list [--json [fields]]

Table columns: ID, NAME, DESCRIPTION, UPDATED

lh kb view <id>

lh kb view [fields]] < id > [--json

Displays: Name, description, full directory tree with all files and documents (recursively fetched). Shows indented tree structure with item type (File/Doc), file type, and size.

API: Uses file.getKnowledgeItems to recursively fetch items. Folders (custom/folder fileType) are traversed in parallel via Promise.all for performance.

lh kb create

lh kb create -n [--avatar < name > [-d < desc > ] < url > ]

Output: Created KB ID. Note: backend returns ID as a string directly (not an object).

lh kb edit <id>

lh kb edit [-d [--avatar < id > [-n < name > ] < desc > ] < url > ]

Requires at least one change flag. Errors if none specified.

lh kb delete <id>

lh kb delete [--yes] < id > [--remove-files]

lh kb add-files <knowledgeBaseId>

lh kb add-files <kbId> --ids <fileId1> <fileId2> ...

Link existing files to a knowledge base.

lh kb remove-files <knowledgeBaseId>

lh kb remove-files <kbId> --ids <fileId1> <fileId2> ... [--yes]

Unlink files from a knowledge base.

lh kb mkdir <knowledgeBaseId>

lh kb mkdir < kbId > -n < name > [--parent < folderId > ]

Create a folder in a knowledge base. Uses document.createDocument with fileType: 'custom/folder'.

lh kb create-doc <knowledgeBaseId>

lh kb create-doc [--parent < kbId > -t < title > [-c < content > ] < folderId > ]

Create a document in a knowledge base. Uses document.createDocument with fileType: 'custom/document'.

lh kb move <id>

lh kb move < id > --type < file | doc > [--parent < folderId > ]

Move a file or document to a different folder (or to root if --parent is omitted).

Uses document.updateDocument for docs, file.updateFile for files.

lh kb upload <knowledgeBaseId> <filePath>

lh kb upload <kbId> <filePath> [--parent <folderId>]

Upload a local file to a knowledge base via S3 presigned URL.

Flow: Compute SHA-256 hash → get presigned URL via upload.createS3PreSignedUrl → PUT to S3 → create file record via file.createFile.

---

File Management (lh file)

Manage uploaded files.

Source: apps/cli/src/commands/file.ts

lh file list

lh file list [--kb-id [-L [--json [fields]] < id > ] < n > ]

Table columns: ID, NAME, TYPE, SIZE, UPDATED

lh file view <id>

lh file view [fields]] < id > [--json

Displays: Name, type, size, chunking status, embedding status.

lh file delete <ids...>

lh file delete [--yes] < id1 > [id2...]

Supports deleting multiple files at once.

lh file recent

lh file recent [-L [--json [fields]] < n > ]

---

Document Management (lh doc)

Manage text documents (notes, wiki pages).

Source: apps/cli/src/commands/doc.ts

lh doc list

lh doc list [-L [--file-type [--source-type [--json [fields]] < n > ] < type > ] < type > ]

Table columns: ID, TITLE, TYPE, UPDATED

lh doc view <id>

lh doc view [fields]] < id > [--json

Displays: Title, type, KB association, updated time, full content.

lh doc create

lh doc create -t [-F [--parent [--slug [--kb [--file-type < title > [-b < body > ] < path > ] < id > ] < slug > ] < id > ] < type > ]

-b and -F are mutually exclusive; -F reads the file content as the body.

lh doc batch-create <file>

Batch create documents from a JSON file. The file must contain a non-empty array of document objects.

lh doc batch-create documents.json

Each object in the array can have: title, content, fileType, knowledgeBaseId, parentId, slug.

lh doc edit <id>

lh doc edit [-b [-F [--parent [--file-type < id > [-t < title > ] < body > ] < path > ] < id > ] < type > ]

lh doc delete <ids...>

lh doc delete [--yes] < id1 > [id2...]

lh doc parse <fileId>

Parse an uploaded file into a document.

lh doc parse [--json [fields]] < fileId > [--with-pages]

Output: Parsed title and content preview.

lh doc link-topic <docId> <topicId>

Associate a document with a topic. Creates a linked copy via the notebook router.

lh doc link-topic <docId> <topicId>

lh doc topic-docs <topicId>

List documents associated with a topic.

lh doc topic-docs [--json [fields]] < topicId > [--type < type > ]

Memory Commands

Manage user memories - the AI's long-term knowledge about users.

Source: apps/cli/src/commands/memory.ts

Memory Categories

---

lh memory list [category]

List memory entries, optionally filtered by category.

lh memory list            # All categories
lh memory list identity   # Only identity memories
lh memory list preference # Only preferences

Output: Grouped by category, showing type/status and descriptions.

---

lh memory create

Create a new identity memory entry.

lh memory create [options]

---

lh memory edit <category> <id>

Edit a memory entry. Options vary by category:

lh memory edit identity < id > [options]
lh memory edit activity < id > [options]
lh memory edit context < id > [options]
lh memory edit experience < id > [options]
lh memory edit preference < id > [options]

Category-specific Options

identity:

• --type <type>, --role <role>, --relationship <rel>

activity:

• --narrative <text>, --notes <text>, --status <status>

context:

• --title <title>, --description <desc>, --status <status>

experience:

• --situation <text>, --action <text>, --key-learning <text>

preference:

• --directives <text>, --suggestions <text>

---

lh memory delete <category> <id>

lh memory delete identity < id > [--yes]

---

lh memory persona

Display the compiled memory persona summary.

lh memory persona [--json [fields]]

Output: Summarized user profile built from all memory categories.

---

lh memory extract

Trigger async memory extraction from chat history.

lh memory extract [--from [--to < date > ] < date > ]

Starts a background task that analyzes chat history and creates new memory entries.

---

lh memory extract-status

Check the status of a memory extraction task.

lh memory extract-status [--task-id [--json [fields]] < id > ]

Model & Provider Commands

Model Management (lh model)

Manage AI models within providers.

Source: apps/cli/src/commands/model.ts

lh model list <providerId>

List models for a specific provider.

lh model list openai
lh model list openai --type image --enabled
lh model list lobehub --type video --json

Table columns: ID, NAME, ENABLED, TYPE

Backend: aiModel.getAiProviderModelList → AiInfraRepos.getAiProviderModelList (supports type filter at repository level)

lh model view <id>

lh model view [fields]] < modelId > [--json

Displays: Name, provider, type, enabled status, capabilities.

lh model create

lh model create --id [--type < id > --provider < providerId > [--display-name < name > ] < type > ]

lh model edit <id>

lh model edit [--type < modelId > --provider < providerId > [--display-name < name > ] < type > ]

lh model toggle <id>

Enable or disable a model.

lh model toggle < modelId > --provider < providerId > --enable
lh model toggle < modelId > --provider < providerId > --disable

lh model batch-toggle <ids...>

Enable or disable multiple models at once.

lh model batch-toggle model1 model2 model3 --provider openai --enable

lh model delete <id>

lh model delete < modelId > --provider < providerId > [--yes]

lh model clear

Clear all models (or only remote/fetched models) for a provider.

lh model clear --provider [--yes] < providerId > [--remote]

---

Provider Management (lh provider)

Manage AI service providers.

Source: apps/cli/src/commands/provider.ts

lh provider list

lh provider list [--json [fields]]

Table columns: ID, NAME, ENABLED, SOURCE

lh provider view <id>

lh provider view [fields]] < providerId > [--json

Displays: Name, enabled status, source, configuration.

lh provider create

lh provider create --id [-d [--logo [--sdk-type < id > -n < name > [-s < source > ] < desc > ] < url > ] < type > ]

lh provider edit <id>

lh provider edit [-d [--logo [--sdk-type < providerId > [-n < name > ] < desc > ] < url > ] < type > ]

Requires at least one change flag.

lh provider config <id>

Configure provider settings (API key, base URL, etc.).

lh provider config openai --api-key sk-xxx
lh provider config openai --base-url https://custom-endpoint.com
lh provider config openai --show
lh provider config openai --show --json

Important: The lobehub provider is platform-managed. Attempting to set --api-key or --base-url on it will be rejected with an error message.

lh provider test <id>

Test provider connectivity.

lh provider test openai
lh provider test openai -m gpt-4o --json

lh provider toggle <id>

lh provider toggle < providerId > --enable
lh provider toggle < providerId > --disable

lh provider delete <id>

lh provider delete < providerId > [--yes]

Search & Configuration Commands

Global Search (lh search)

Search across all LobeHub resource types.

Source: apps/cli/src/commands/search.ts

lh search <query>

lh search "meeting notes" [-t [-L [--json [fields]] < type > ] < n > ]

Searchable Types

Output: Results grouped by type, showing ID, title/name, description.

---

User Configuration (lh whoami / lh usage)

Source: apps/cli/src/commands/config.ts

lh whoami

Display current authenticated user information.

lh whoami [--json [fields]]

Displays: Name, username, email, user ID, subscription plan.

lh usage

Display usage statistics.

lh usage [--month [--daily] [--json [fields]] < YYYY-MM > ]

Output: Token usage, costs, and model breakdown for the specified period.

---

Global Options

These options are available across most commands:

JSON Field Filtering

The --json option supports field selection:

# Full JSON output
lh agent list --json

# Only specific fields
lh agent list --json "id,title,model"

Skill & Plugin Commands

Skill Management (lh skill)

Manage agent skills (custom instructions and capabilities).

Source: apps/cli/src/commands/skill.ts

lh skill list

lh skill list [--source [--json [fields]] < source > ]

Table columns: ID, NAME, DESCRIPTION, SOURCE, IDENTIFIER

lh skill view <id>

lh skill view [fields]] < id > [--json

Displays: Name, description, source, identifier, content.

lh skill create

lh skill create -n < name > -d < desc > -c < content > [-i < identifier > ]

lh skill edit <id>

lh skill edit [-n [-d < id > [-c < content > ] < name > ] < desc > ]

lh skill delete <id>

lh skill delete < id > [--yes]

lh skill search <query>

lh skill search [fields]] < query > [--json

lh skill install <source> (alias: lh skill i)

Install a skill. Auto-detects source type from the input:

# GitHub (URL or owner/repo shorthand)
lh skill install lobehub/skill-repo
lh skill install https://github.com/lobehub/skill-repo
lh skill install lobehub/skill-repo --branch dev

# ZIP URL
lh skill install https://example.com/skill.zip

# Marketplace identifier
lh skill install my-cool-skill
lh skill i my-cool-skill

Detection rules:

• https://github.com/... or owner/repo → GitHub
• Other https://... URLs → ZIP URL
• Everything else → marketplace identifier

Resource Commands

lh skill resources <id>

List files/resources within a skill.

lh skill resources [fields]] < id > [--json

Displays: Path, type, size.

lh skill read-resource <id> <path>

Read a specific resource file from a skill.

lh skill read-resource <skillId> <path>

Output: File content or JSON metadata.

---

Plugin Management (lh plugin)

Install and manage plugins (external tool integrations).

Source: apps/cli/src/commands/plugin.ts

lh plugin list

lh plugin list [--json [fields]]

Table columns: ID, IDENTIFIER, TYPE, TITLE

lh plugin install

lh plugin install -i [--settings < identifier > --manifest < json > [--type < type > ] < json > ]

lh plugin uninstall <id>

lh plugin uninstall < id > [--yes]

lh plugin update <id>

lh plugin update [--settings < id > [--manifest < json > ] < json > ]