CLI Reference

The Lobu CLI (@lobu/cli) scaffolds projects, runs agents locally, and manages deployments.

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 new agent project with lobu.toml, .env, and an agent directory.

npx @lobu/cli@latest init my-agent

Generates:

lobu.toml — agent configuration (skills, providers, connections, network)
.env — credentials and environment variables (set DATABASE_URL after init)
agents/{name}/ — agent directory with IDENTITY.md, SOUL.md, USER.md, and skills/
skills/ — shared skills directory (available to all agents)
AGENTS.md, TESTING.md, README.md, .gitignore

Interactive prompts guide you through provider, skills, platform, network access policy, gateway port, public URL, admin password, and memory configuration. Postgres (with pgvector) is the only user-provided external — Lobu does not bundle it.

`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 "Status update" -c staging

API mode (default): creates a session, sends the message, and streams the response to the terminal.

Platform mode (with --user): routes the message through Telegram/Slack/Discord so the response appears on the platform. The terminal also streams the output.

Flag	Description
`-a, --agent <id>`	Agent ID (defaults to first agent in `lobu.toml`)
`-u, --user <id>`	Route through a platform (e.g. `telegram:12345`, `slack:C0123`)
`-t, --thread <id>`	Thread/conversation ID for multi-turn conversations
`-g, --gateway <url>`	Gateway URL (default: `http://localhost:8080` or from `.env`)
`--dry-run`	Process without persisting history
`--new`	Force a new session (ignore existing)
`-c, --context <name>`	Use a named context for gateway URL and credentials

`eval [name]`

Run agent evaluations. Eval files live in the agent directory and define test cases with expected outcomes.

npx @lobu/cli@latest eval                           # run all evals
npx @lobu/cli@latest eval basic-qa                  # run a specific eval
npx @lobu/cli@latest eval --model claude/sonnet     # eval with a specific model
npx @lobu/cli@latest eval --ci --output results.json  # CI mode with JSON output

Flag	Description
`-a, --agent <id>`	Agent ID (defaults to first in `lobu.toml`)
`-g, --gateway <url>`	Gateway URL (default: `http://localhost:8080`)
`-m, --model <model>`	Model to evaluate (e.g. `claude/sonnet`, `openai/gpt-4.1`)
`--trials <n>`	Override trial count
`--ci`	CI mode: JSON output, non-zero exit on failure
`--output <file>`	Write results to JSON file
`--list`	List available evals without running them

`run`

Run the embedded Lobu stack. Validates lobu.toml, checks that DATABASE_URL is set in .env, then spawns the bundled Node server (@lobu/owletto-backend/dist/server.bundle.mjs) as a child process and forwards stdio. Ctrl+C cleanly stops the server and any worker subprocesses.

npx @lobu/cli@latest run              # boot the gateway + workers + memory backend

Extra arguments are forwarded to the Node entry point.

`validate`

Validate lobu.toml schema, skill IDs, and provider configuration.

npx @lobu/cli@latest validate

Returns exit code 1 if validation fails.

`context`

Manage named API contexts for switching between local and remote gateways.

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

Subcommand	Description
`list`	List all configured contexts
`current`	Show the active context
`add <name> --api-url <url>`	Add a named context
`use <name>`	Set the active context

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

`login`

Authenticate with Lobu Cloud. Opens a browser for OAuth by default.

npx @lobu/cli@latest login
npx @lobu/cli@latest login --token <api-token>      # CI/CD
npx @lobu/cli@latest login --admin-password          # local dev fallback
npx @lobu/cli@latest login -c staging               # login to a named context
npx @lobu/cli@latest login --force                  # re-authenticate (revokes existing session)

Flag	Description
`--token <token>`	Use an API token directly (for CI/CD pipelines)
`--admin-password`	Use the development-only admin password fallback
`-c, --context <name>`	Authenticate against a named context
`-f, --force`	Re-authenticate, revoking the existing session first

`logout`

Revoke the session server-side and clear stored credentials. If the gateway is unreachable, local credentials are still cleared.

npx @lobu/cli@latest logout
npx @lobu/cli@latest logout -c staging

Flag	Description
`-c, --context <name>`	Clear credentials for a named context

`whoami`

Show the current authenticated user, linked agent, and API URL.

npx @lobu/cli@latest whoami
npx @lobu/cli@latest whoami -c staging

Flag	Description
`-c, --context <name>`	Query a named context

`status`

Show agent health: lists agents with their providers and models, platform connections with status, and active sandboxes. Requires the gateway to be running.

npx @lobu/cli@latest status

`secrets`

Manage agent secrets (stored in .env for local dev).

npx @lobu/cli@latest secrets set OPENAI_API_KEY sk-...
npx @lobu/cli@latest secrets list
npx @lobu/cli@latest secrets delete OPENAI_API_KEY

Subcommand	Description
`set <key> <value>`	Set a secret
`list`	List secrets (values redacted)
`delete <key>`	Remove a secret

`skills`

Install bundled starter skills into a local skills/ directory.

npx @lobu/cli@latest skills list
npx @lobu/cli@latest skills add lobu
npx @lobu/cli@latest skills add lobu --force

Subcommand	Description
`list`	Show bundled Lobu starter skills
`add <id>`	Copy a bundled starter skill into `skills/<id>`

The bundled Lobu starter skill includes memory guidance:

npx @lobu/cli@latest skills add lobu

`providers`

Browse and manage LLM providers.

npx @lobu/cli@latest providers list       # browse available providers
npx @lobu/cli@latest providers add gemini  # add to lobu.toml

Subcommand	Description
`list`	Browse available LLM providers
`add <id>`	Add a provider to `lobu.toml`

Typical workflow

# 1. Scaffold
npx @lobu/cli@latest init my-agent

# 2. Configure
cd my-agent
npx @lobu/cli@latest skills add lobu
npx @lobu/cli@latest providers add gemini
npx @lobu/cli@latest secrets set GEMINI_API_KEY ...

# Optional: install the bundled Lobu starter skill
npx @lobu/cli@latest skills add lobu

# 3. Validate
npx @lobu/cli@latest validate

# 4. Run locally
npx @lobu/cli@latest run -d

# 5. Chat with your agent
npx @lobu/cli@latest chat "Hello, what can you do?"