CLI Reference

The Lobu CLI (@lobu/cli) scaffolds local project files, runs the embedded server, and manages org/agent configuration through the same REST API used by the web app.

Install

# Run directly (no install)
npx @lobu/cli@latest <command>

# Or install globally
npm install -g @lobu/cli
lobu <command>

Commands

`init [name]`

Scaffold a local agent project with lobu.config.ts, .env, and an agent directory.

npx @lobu/cli@latest init my-agent

Generates:

lobu.config.ts: the TypeScript project entrypoint (defineConfig from @lobu/cli/config)
package.json + tsconfig.json: declare @lobu/cli / @lobu/connector-sdk and give the editor type resolution
.env — local environment variables (API keys, optional external DATABASE_URL)
agents/{name}/ — IDENTITY.md, SOUL.md, USER.md, skill files, and evals
*.connector.ts — custom connectors, referenced from lobu.config.ts via connectorFromFile
*.reaction.ts — automation reaction scripts, referenced via defineAutomation({ reaction })
AGENTS.md, TESTING.md, README.md, .gitignore

Interactive prompts guide you through provider, platform, network access policy, gateway port, public URL, and memory configuration. Local runs use an embedded Postgres (PG18 + pgvector) by default; set DATABASE_URL when you want to use an external Postgres.

`run` (aliases: `dev`, `start`)

Run the embedded Lobu stack. lobu.config.ts is not required. With no DATABASE_URL, the command starts an embedded Postgres (PG18 + pgvector) and stores data under ~/.lobu/pgdata (override with LOBU_DATA_DIR). If DATABASE_URL is set in the environment or .env, Lobu uses that external Postgres instead.

npx @lobu/cli@latest run
npx @lobu/cli@latest run --port 9000
npx @lobu/cli@latest dev --verbose       # `dev` and `start` are aliases for `run`

Flag	Description
`--port <port>`	Gateway port (overrides `GATEWAY_PORT` in `.env`)
`--quiet`	Suppress the startup banner; raise log level to `warn`
`--verbose`	Lower log level to `debug`
`--log-level <level>`	Forwarded as `LOG_LEVEL` to the bundled server

The command spawns the bundled Node server and forwards stdio. Ctrl+C cleanly stops the server and worker subprocesses.

`login`

Authenticate with Lobu via the OAuth 2.0 device-code flow. Prints a verification URL and opens it in the browser; you approve there and the CLI receives the token.

npx @lobu/cli@latest login
npx @lobu/cli@latest login --token <api-token>      # CI/CD
npx @lobu/cli@latest login -c staging               # login to a named context
npx @lobu/cli@latest login --force                  # re-authenticate

Flag	Description
`--token <token>`	Use an API token directly
`-c, --context <name>`	Authenticate against a named context
`-f, --force`	Re-authenticate, revoking the existing OAuth session first

`context`

Manage named API contexts.

npx @lobu/cli@latest context list
npx @lobu/cli@latest context current
npx @lobu/cli@latest context add staging --url https://staging.example.com/api/v1
npx @lobu/cli@latest context use staging

Environment overrides: set LOBU_CONTEXT to select a context by name, or LOBU_API_URL to override the URL directly.

`org`

Manage the active organization for org-scoped API commands.

npx @lobu/cli@latest org list
npx @lobu/cli@latest org current
npx @lobu/cli@latest org set my-org

LOBU_ORG overrides the active org for one process.

`agent`

Manage agents via the same org-scoped REST endpoints as the web app.

npx @lobu/cli@latest agent list
npx @lobu/cli@latest agent get my-agent
npx @lobu/cli@latest agent create my-agent --name "My Agent"
npx @lobu/cli@latest agent update my-agent --description "Handles support"
npx @lobu/cli@latest agent delete my-agent --yes

agent scaffold <agentId> adds a new local agent (agents/<id>/* plus a defineAgent entry in lobu.config.ts) without touching existing agents, the local-files counterpart of agent create:

npx @lobu/cli@latest agent scaffold support-bot --name "Support Bot" --description "Handles tickets"

Config helpers use the web app’s /config API:

npx @lobu/cli@latest agent config get my-agent --output config.json
npx @lobu/cli@latest agent config patch my-agent --file config.patch.json

Most agent commands accept --org <slug>, -c/--context <name>, and --json where useful.

`providers`

Manage the org’s model (inference) providers over the same REST surface the web console and lobu apply (defineConfig({ providers })) edit — one store, many editors. Exists so a project with no lobu.config.ts can still add a provider. Secret-bearing flags take a literal value or a $ENV_VAR reference (quote it).

npx @lobu/cli@latest providers list
npx @lobu/cli@latest providers catalog
npx @lobu/cli@latest providers create my-openai --kind openai --key '$OPENAI_API_KEY' --model gpt-5 --default
npx @lobu/cli@latest providers update my-openai --name "My OpenAI"
npx @lobu/cli@latest providers set-key my-openai --key '$OPENAI_API_KEY'
npx @lobu/cli@latest providers set-capability my-openai text --model gpt-5
npx @lobu/cli@latest providers set-default my-openai
npx @lobu/cli@latest providers delete my-openai --yes

Subcommand	Description
`list`	List the org’s model providers
`catalog`	List provider kinds available to add
`create <slug>`	Add a provider. Required: `--kind <kind>`, `--key <value\|$ENV_VAR>`. Optional: `--name <name>`, `--model <id>`, `--capabilities <json>` (per-modality overrides, e.g. `{"text":{"model":"gpt-4o"}}`), `--default`
`update <slug>`	Rename a provider. Required: `--name <name>`
`set-key <slug>`	Rotate a provider’s API key. Required: `--key <value\|$ENV_VAR>`
`set-capability <slug> <modality>`	Set one modality’s model/endpoint (`text`, `image`, `stt`, `tts`). Optional: `--model <id>`, `--base-url <url>`, `--models-endpoint <path>`
`set-default <slug>`	Make a provider the org default
`delete <slug>`	Delete a provider. Optional: `--yes` to confirm

Subcommands accept --org <slug>; read-facing ones (list, catalog, create, update) also accept --json.

`sandbox`

Manage sandboxes — the runtime providers agents use to execute code. (environment was renamed to sandbox; the old verb prints a pointer.)

npx @lobu/cli@latest sandbox list
npx @lobu/cli@latest sandbox create my-sandbox --provider vercel --credential 'token=$VERCEL_TOKEN'
npx @lobu/cli@latest sandbox set-credential my-sandbox --credential 'token=$VERCEL_TOKEN'
npx @lobu/cli@latest sandbox delete my-sandbox --yes

Subcommand	Description
`list`	List sandboxes
`create <name>`	Create a sandbox. Required: `--provider <kind>`. Optional: `--credential <key=value\|key=$ENV_VAR>` (repeatable, quote it)
`set-credential <id>`	Set or rotate a sandbox’s credential. Required: `--credential <key=value\|key=$ENV_VAR>` (repeatable)
`delete <id>`	Delete a sandbox. Optional: `--yes` to confirm

Subcommands accept --org <slug>; list and create also accept --json.

`clients`

List and revoke connected clients — MCP apps and messaging integrations bound to the org.

npx @lobu/cli@latest clients list
npx @lobu/cli@latest clients list --agent my-agent
npx @lobu/cli@latest clients revoke <clientId> --yes

Subcommand	Description
`list`	List connected clients. Optional: `--agent <agentId>` to filter to one agent
`revoke <clientId>`	Revoke an MCP client’s tokens and sessions. Optional: `--yes` to confirm

Subcommands accept --org <slug>; list also accepts --json.

`call [tool]`

Invoke an admin REST tool by name (POST /api/<org>/<tool>). One entry point over the same UI-callable tool surface, instead of a bespoke command per action. Run with --list or no arguments to discover available tools. (lobu memory run is the MCP JSON-RPC counterpart; call routes through the REST proxy.)

npx @lobu/cli@latest call                       # list tools (default when called bare)
npx @lobu/cli@latest call --list --all          # include internal/admin-only tools
npx @lobu/cli@latest call sync_connection --arg connection_id:=42
npx @lobu/cli@latest call some_tool --input-file args.json --raw

Flag	Description
`--list`	List tools available to the current token (default when called bare)
`--all`	Include internal/admin-only tools in `--list` output
`--input-file <path>`	Read the JSON args body from a file (top-level object)
`--arg <entry>`	Add a top-level arg as `key=string` or `key:=<json>` (repeatable)
`--raw`	Emit compact JSON (default is pretty-printed)
`--url <url>`	Server URL override
`--org <slug>`	Org slug override
`--json`	Print the full JSON response

`chat <prompt>`

Send a prompt to an agent and stream the response to the terminal.

npx @lobu/cli@latest chat "What is the weather?"
npx @lobu/cli@latest chat "Hello" --agent my-agent --thread conv-123
npx @lobu/cli@latest chat "Check my PRs" --user telegram:12345
npx @lobu/cli@latest chat "Where did we leave off?" --continue
npx @lobu/cli@latest chat "Status update" -c staging

-u/--user impersonates a platform user ID (telegram:<numeric-id>, slack:<member-id>), which routes the message through that platform instead of replying directly in the terminal.

Flag	Description
`-a, --agent <id>`	Agent ID (defaults to first agent in local `lobu.config.ts` when present)
`-u, --user <id>`	User ID to impersonate, e.g. `telegram:12345`. With this flag the message routes through the user’s platform (Telegram/Slack)
`-t, --thread <id>`	Thread/conversation ID for multi-turn conversations
`-g, --gateway <url>`	Gateway URL (default: `http://localhost:8787` or from `.env`)
`--dry-run`	Skip side-effecting tool calls (sandbox writes, sdk_run mutations). The turn still runs and history is still persisted.
`--new`	Force a new session (ignore an existing one)
`-C, --continue`	Resume the last thread for this `(context, agent)`
`--auto-approve`	Auto-approve every tool call — use only in trusted environments
`--json`	Emit raw SSE events as JSON lines instead of rendered text
`-c, --context <name>`	Use a named context for gateway URL and credentials

Evaluations

Lobu does not ship its own eval runner. Use promptfoo with @lobu/promptfoo-provider; see the Evaluations guide for the full pattern.

bun add -D promptfoo @lobu/promptfoo-provider
LOBU_TOKEN=$(npx @lobu/cli@latest token --raw) \
  bunx promptfoo eval -c agents/<agent-id>/evals/promptfooconfig.yaml

`validate`

Validate that local lobu.config.ts loads and conforms to the schema, plus skill IDs and provider configuration.

npx @lobu/cli@latest validate

Returns exit code 1 if validation fails.

`apply`

Sync local lobu.config.ts and agent directories to a Lobu Cloud org. Idempotent, prompt-confirmed, one-way (files are the source of truth). deploy is an alias.

npx @lobu/cli@latest apply                  # plan + prompt + apply
npx @lobu/cli@latest apply --dry-run         # plan only, no mutations
npx @lobu/cli@latest apply --yes --org my-org   # CI mode, no prompt
npx @lobu/cli@latest deploy --only agents    # `deploy` is an alias

Flag	Description
`--force`	Bypass the project-link guard if `context`/`org` don’t match `.lobu/project.json`
`--resume`	Clear the promotions pause a `lobu rollback` set and start a fresh apply

apply syncs agents, memory schema, connections + auth profiles, chat connections, org providers, and custom connectors — but never memory data or secret values (API keys are pushed to the server’s secrets store; other $VAR refs stay placeholders). The diff is idempotent; cloud-only resources unreported as drift, never deleted (no --prune). A missing secret("VAR") short-circuits the run with the list of missing vars.

required-secrets check
  ↓  upsertAgent → patchAgentSettings
  ↓  upsertEntityType → upsertRelationshipType → upsertAutomation
  ↓  upsertAuthProfile / upsertConnection → validate / configure connectors

lobu rollback <applyId> restores a previous deployment from its stored snapshot (pauses further applies until --resume). apply --resume clears it.

`status`

Show a summary of agents in the active org.

npx @lobu/cli@latest status
npx @lobu/cli@latest status --org my-org

`link` / `unlink`

link binds the current directory to a (context, org) pair, written to .lobu/project.json. Subsequent commands in this directory default to that context and org, and lobu apply refuses to run against a different pair unless you pass --force. unlink removes the file.

npx @lobu/cli@latest link --org my-org
npx @lobu/cli@latest link -c staging --org my-org
npx @lobu/cli@latest unlink

Flag	Description
`-c, --context <name>`	Use a named context
`--org <slug>`	Org slug to link (defaults to the active org)

`doctor`

Run local health checks: dependencies, DATABASE_URL reachability, pgvector, ports, and provider keys.

npx @lobu/cli@latest doctor
npx @lobu/cli@latest doctor --memory-only      # only check memory MCP connectivity + auth

Flag	Description
`--memory-only`	Only check memory MCP connectivity and authentication

`memory`

Lobu’s memory MCP surface — run tools, seed a workspace, and wire MCP clients. Auth is shared with the rest of the CLI (lobu login once); default MCP endpoint https://lobu.ai/mcp, override per-command with --org, --url, LOBU_MEMORY_ORG, or LOBU_MEMORY_URL.

Subcommand	Description
`run [tool] [params]`	Invoke an MCP tool, or list tools when called bare. e.g. `lobu memory run search_memory '{"query":"Acme"}' --org my-org`
`exec <script>`	Run a ClientSDK script source via `run_sdk` (sugar for `lobu memory run run_sdk '{\"script\": ...}'`)
`health`	Validate login + MCP connectivity (`lobu doctor --memory-only` is the equivalent)
`org`	`current` / `set <slug>` — manage the default org for memory MCP
`seed`	Provision a memory workspace (schema + org) from `lobu.config.ts`, plus optional `./data` records
`init`	Wire an existing project’s agents to a memory MCP endpoint (`--url`, `--agent`, `--skip-auth`)
`browser-auth`	Launch a dedicated Chrome for browser-based connectors and store its CDP endpoint on an auth profile (`--connector` required; `--check` verifies it)

memory seed mirrors the schema declared in lobu.config.ts (defineEntityType / defineRelationshipType / defineAutomation) to a workspace. memory tool names are the same MCP surface cataloged in the MCP reference.

`telemetry`

Show or toggle anonymous error reporting (Sentry). With no subcommand, prints the current status.

npx @lobu/cli@latest telemetry            # same as `telemetry status`
npx @lobu/cli@latest telemetry status
npx @lobu/cli@latest telemetry on         # writes SENTRY_DSN to .env
npx @lobu/cli@latest telemetry on --dsn https://[email protected]/1
npx @lobu/cli@latest telemetry off        # removes SENTRY_DSN from .env

Subcommand	Description
`status`	Show whether telemetry is on or off (default)
`on`	Enable telemetry — accepts `--dsn <dsn>` to override Lobu’s default DSN
`off`	Disable telemetry

`logout`, `whoami`, `token`

npx @lobu/cli@latest whoami
npx @lobu/cli@latest token --raw
npx @lobu/cli@latest logout

token (no subcommand) prints the stored session token. token create mints an org-scoped personal access token suitable for servers and CI — it survives a lobu logout and is not tied to the device-code session:

npx @lobu/cli@latest token create --org my-org --name ci-token --scope "mcp:read mcp:write" --expires-in-days 90
npx @lobu/cli@latest token create --org my-org --raw      # token only, for scripting
npx @lobu/cli@latest token create --org my-org --json

Flag	Description
`--org <slug>`	Org slug override
`--name <name>`	Token name (default: `lobu-cli-YYYY-MM-DD`)
`--description <text>`	Token description
`--scope <scope>`	Space-separated scopes (default: `mcp:read mcp:write`)
`--expires-in-days <days>`	Expire the token after N days (positive integer)
`--raw`	Print the token only, no labels
`--json`	Print the full JSON response
`-c, --context <name>`	Use a named context

Typical workflow

# 1. Authenticate and select org
npx @lobu/cli@latest login
npx @lobu/cli@latest org set my-org

# 2. Manage remote/UI-backed agents
npx @lobu/cli@latest agent list
npx @lobu/cli@latest agent create my-agent --name "My Agent"

# 3. Optional local artifact workflow
npx @lobu/cli@latest init my-agent
cd my-agent
npx @lobu/cli@latest validate
npx @lobu/cli@latest apply --org my-org

# 4. Run locally (embedded Postgres by default; external Postgres if DATABASE_URL is set)
npx @lobu/cli@latest run

lobu.config.ts reference: the declarative config lobu apply reconciles.
MCP reference: the tools lobu memory run invokes.
Connect your agents: point external agents at the same shared context.

CLI Reference

Install

Commands

init [name]

run (aliases: dev, start)

login

context

org

agent

providers

sandbox

clients

call [tool]

chat <prompt>

Evaluations

validate

apply

status

link / unlink

doctor

memory

telemetry

logout, whoami, token