Cli
LobeHub CLI (@lobehub/cli) development guide — commands, subcommands, architecture.
mkdir -p ~/.claude/skills/cli && curl -fsSL 'https://raw.githubusercontent.com/lobehub/lobehub/canary/.agents/skills/cli/SKILL.md' -o ~/.claude/skills/cli/SKILL.md
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Cli when an AI agent needs a reusable SKILL.md workflow for this job: LobeHub CLI (@lobehub/cli) development guide — commands, subcommands, architecture.
When not to use it
Skip Cli when the task is outside the productivity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/cli && curl -fsSL 'https://raw.githubusercontent.com/lobehub/lobehub/canary/.agents/skills/cli/SKILL.md' -o ~/.claude/skills/cli/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/cli/SKILL.md. For a shared project, commit the folder at .claude/skills/cli/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Cli skill for this task: Use Cli when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
67/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 67/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 68/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptinferred
The skill text mentions ChatGPT or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# 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/ │ ├── 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 │ ├── automation.ts # Automations = MCP Events subscriptions (helpers in automation/) │ ├── 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 # Legacy 1.0 plugins (`lh legacy-plugin`) │ ├── 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 │ ├── webhook.ts # Custom webhooks (helpers in webhook/, shared with automation) │ └── 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 ```
## 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 acceptance` | - | Delivery acceptances: review loop, rounds, per-run check plans, criteria, rubrics | | `lh verify` | - | Deprecated alias of `lh acceptance` commands | | `lh eval` | - | Manage evaluation workflows and benchmarks | | `lh generate` | `gen` | Content generation (text, image, video, tts, asr, download) | | `lh doc` | - | Document CRUD, batch-create, parse, topic linking | | `lh file` | - | File list, view, delete, recent | | `lh artifact` | - | Publish local HTML pages as artifacts | | `lh automation` | - | Automations (alias `automations`): list, view, rename, check, delete | | `lh kb` | - | Knowledge base CRUD, folders, docs, upload, tree view | | `lh memory` | - | User memory CRUD + extraction | | `lh message` | - | Message list, search, delete, count, heatmap | | `lh topic` | - | Topic CRUD + search + recent | | `lh notify` | - | Send a callback message to a topic and trigger the agent to process it | | `lh notification` | - | Notification settings: show, enable/disable channels, IM platforms and types | | `lh migrate` | - | Import data from external tools (OpenClaw, ChatGPT, Claude, etc.) | | `lh bot` | - | Manage bot integrations (channels, access policies, messengers) | | `lh skill` | - | Skill CRUD + import (GitHub/URL/market) | | `lh model` | - | Model CRUD, toggle, batch-toggle, clear | | `lh provider` | - | Provider CRUD, config, test, toggle | | `lh legacy-plugin` | - | Legacy 1.0 plugins: list, search, uninstall, update | | `lh search` | - | Global search across all types | | `lh work` | - | Register the files and links an agent run produced as Works, update, delete, lookup | | `lh session-group` | - | Manage agent session groups | | `lh workspace` | `ws` | Workspace list, scope switch, members, invites, usage | | `lh user` | - | Manage user account and settings | | `lh webhook` | - | Custom webhooks (alias `webhooks`): create, edit, pause, test, rotate-key, calls | | `lh whoami` | - | Current user info (including the resolved workspace scope) | | `lh usage` | - | Monthly/daily usage statistics | | `lh man` | - | Show a manual page for the CLI or a subcommand | | `lh completion` | - | Output shell completion script | | `lh update` | - | Update the CLI to the latest published version |
### Workspace Scope
Every command runs against one scope, resolved in this order:
1. an explicit `--workspace <id|slug>` on the `workspace`, `device` and `topic` commands that take it (a slug is resolved against `lh workspace list`; one that matches nothing fails). A credential that cannot call `workspace.list` (no `workspace:read`, such as a workspace-bound API key) skips resolution and sends the value as an id with a warning, so it must pass the id. `lh connect --workspace` takes an id only. 2. the `LOBEHUB_WORKSPACE_ID` env var (an id only) 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`:
```typescript 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`:
```typescript 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
```typescript const rows = items.map((item) => [item.id, truncate(item.title, 40), timeAgo(item.updatedAt)]); printTable(rows, ['ID', 'TITLE', 'UPDATED']); ```
### JSON Output
```typescript 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:
```typescript const client = await getTrpcClient(); // client.router.procedure.query/mutate(...) ```
### Confirmation Prompts
```typescript 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.
```bash # 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**
```bash # 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**
```bash 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**
```bash 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
```bash # 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
```bash # 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) - **Goals**: `references/goal.md` (planning turn, state, events, lifecycle, decisions) - **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) - **Webhooks**: `references/webhook.md` (custom webhooks, identifier, Channel delivery) - **Automations**: `references/automation.md` (MCP Events subscriptions: list, view, rename, check, delete)
Intended uses
- Use Cli when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.