CLI + Backend Integration Testing

Standard workflow for verifying backend changes using the LobeHub CLI (lh) against a local dev server.

When to Use

• Verifying TRPC router / service / model changes end-to-end
• Testing new API fields or response structure changes
• Validating CLI command output after backend modifications
• Debugging data flow issues between server and CLI

Prerequisites

Quick Reference

All CLI dev commands run from lobehub/apps/cli/. Subsequent examples use $CLI:

CLI="LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts"

Workflow

Step 1: Ensure Dev Server is Running

curl -s -o /dev/null -w '%{http_code}' http://localhost:3011/ 2> /dev/null

• If reachable: skip to Step 2.
• If unreachable: start from cloud repo root:

pnpm run dev:next

To restart (pick up server-side code changes):

lsof -ti:3011 | xargs kill
pnpm run dev:next

Important: Server-side code changes in the submodule (lobehub/apps/server/src/, lobehub/src/server/, lobehub/packages/) require a server restart. Next.js hot-reload may not pick up changes in submodule packages.

Step 2: Check CLI Authentication

cat lobehub/apps/cli/.lobehub-dev/settings.json 2> /dev/null

• If file exists and contains "serverUrl": "http://localhost:3011": skip to Step 3.
• If missing or wrong server: ask the user to run:

! cd lobehub/apps/cli && LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts login --server http://localhost:3011

Login requires interactive browser authorization (OIDC Device Code Flow), so the user must run it themselves via ! prefix. Credentials persist in lobehub/apps/cli/.lobehub-dev/.

Step 3: Test with CLI Commands

CLI runs from source, so CLI-side code changes take effect immediately without rebuilding.

cd lobehub/apps/cli
$CLI <command>

Step 4: Clean Up Test Data

$CLI task delete < id > -y
$CLI agent delete < id > -y

Common Testing Patterns

Task System

$CLI task list
$CLI task create -n "Root Task" -i "Test instruction"
$CLI task create -n "Child Task" -i "Sub instruction" --parent T-1
$CLI task view T-1
$CLI task tree T-1
$CLI task edit T-1 --status running
$CLI task comment T-1 -m "Test comment"
$CLI task delete T-1 -y

Agent System

$CLI agent list
$CLI agent view <agent-id>
$CLI agent run <agent-id> -m "Test prompt"

Document & Knowledge Base

$CLI doc list
$CLI doc create -t "Test Doc" -c "Content here"
$CLI doc view <doc-id>
$CLI kb list
$CLI kb tree <kb-id>

Model & Provider

$CLI model list
$CLI provider list
$CLI provider test <provider-id>

Dev-Test Cycle

1. Make code changes (service/model/router/type)
         |
2. Run unit tests (fast feedback)
   bunx vitest run --silent='passed-only' '<test-file>'
         |
3. Restart dev server (if server-side changes)
   lsof -ti:3011 | xargs kill && pnpm run dev:next
         |
4. CLI verification (end-to-end)
   $CLI <command>
         |
5. Clean up test data

When Server Restart is Needed

Troubleshooting