lobe-chat/.agents/skills/agent-testing/cli/index.md

CLI Backend Verification

Default surface for verifying backend changes (TRPC routers, services, models, migrations) end-to-end: fastest loop, text-assertable output, zero UI flakiness.

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

Requirement	Details
Dev server	localhost:3010 — see ../references/dev-server.md
CLI source	apps/cli/ — runs from source, no rebuild; standalone node_modules — run pnpm install inside apps/cli/ (root install does not cover it)
CLI dev mode	LOBEHUB_CLI_HOME=.lobehub-dev for isolated settings
Auth	Seeded API key first; Device Code Flow only as fallback — see ../references/auth.md

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

source ../../.records/env/agent-testing-cli.env
CLI="bun src/index.ts"

Workflow

Step 1 — Server up?

See ../references/dev-server.md for the health check, start, and restart commands. Server-side code changes require a restart.

Step 2 — Auth ready?

./.agents/skills/agent-testing/scripts/setup-auth.sh status

If the CLI is not ready in the seeded local environment:

./.agents/skills/agent-testing/scripts/init-dev-env.sh seed-user
source .records/env/agent-testing-cli.env
./.agents/skills/agent-testing/scripts/setup-auth.sh cli-seed

If the target environment is not seeded, use the interactive fallback:

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

Seeded API-key auth does not store credentials. It writes local settings under $HOME/.lobehub-dev and requires the generated env file to be sourced before CLI commands. Details: ../references/auth.md.

Step 3 — Test with CLI commands

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

cd apps/cli
$CLI <command>

Capture output for the report as you go (e.g. $CLI task list | tee "$DIR/assets/task-list.txt").

Step 4 — Clean up test data

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

Step 5 — Report

Finish with a structured report — ../references/report.md. CLI evidence = exact command + trimmed output.

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 — see dev-server.md)
         |
4. CLI verification (end-to-end)
   $CLI <command>
         |
5. Clean up test data + write the report

Troubleshooting

Issue	Solution
No authentication found	Source .records/env/agent-testing-cli.env, or run device-code login --server http://localhost:3010
UNAUTHORIZED on API calls	Re-run init-dev-env.sh seed-user and re-source the env file; for device-code fallback, re-run login
ECONNREFUSED	Dev server not running — see dev-server.md
CLI shows old data/behavior	Server needs restart to pick up code changes
Login opens wrong server	Must use --server flag (env var doesn't work)