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.

`daemon`

Map this machine as a device worker so Lobu can route connector syncs, actions, and device Automations to it.

lobu login
lobu daemon

No token setup required. The daemon uses your stored login once to mint a durable, device-bound owl_pat_ worker token (a long-lived child of your login), caches it per context and platform, and re-mints ahead of expiry — the short-lived OAuth bearer itself never runs the daemon. Your login decides which workspace a newly registered device joins.

On the first interactive boot for a named context, Lobu proposes <platform>:<hostname> and offers any offline devices registered for the same platform. The selected identity is cached per context and platform. Reusing an existing device preserves its server-side workspace attachment; the wizard does not move it to another workspace.

Started inside a Claude Code, Codex, or OpenCode session, the daemon discovers that session automatically and delivers interactive work into it under a separate per-session identity, so delivery never overwrites the host’s durable device mapping. Disable with --no-interactive-session; OpenCode also needs lobu opencode-plugin install. Registered devices appear on the Devices page, where Automations and device-pinned connectors bind to them: scheduled runs, actions, and connector syncs route to the pinned device on its next poll.

Flag	Description
`--worker-id <id>`	Use an explicit device identity; takes precedence over session detection and cached state
`--platform <name>`	Advanced override of the default `headless` platform (`macos` belongs to the Lobu Mac app); login-based setup supports `headless` only
`--api-url <url>`	Poll this gateway directly; stays stateless and does not read or write a named context’s cached identity
`--capabilities <a,b>`	Advertise device capabilities (default: `os.shell,os.files`)
`--label <name>`	Set the Devices-page label (default: hostname)
`--no-interactive-session`	Disable automatic delivery into an inherited Claude Code, Codex, or OpenCode session
`--debug`	Show poll, heartbeat, and retry detail

LOBU_API_URL behaves like --api-url: it selects a gateway without borrowing device state from the current named context.

For unattended machines where you cannot run the OAuth login flow, supply a personal access token instead:

WORKER_API_TOKEN="$(lobu token create --raw --org <slug> --scope mcp:write)" \
  lobu daemon

The token must be an owl_pat_ personal access token and determines the workspace for a newly registered device. Prefer the login path when you can: an org-scoped PAT like this one is not bound to a device row, so endpoints that require a device-bound token (for example manually triggering a device Automation) reject it, while the login-minted child token is fully device-bound.

`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 and seed a workspace. To wire an MCP client (Claude Code, Codex, OpenCode, Cursor, …), run lobu connect. 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
`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://...@sentry.example.com/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

daemon

org

agent

providers

sandbox

clients

call [tool]

chat <prompt>

Evaluations

validate

apply

status

link / unlink

doctor

memory

telemetry

logout, whoami, token