Using the CLI

carabase (aliased cb) is the terminal counterpart to the Admin SPA. Anything you can do in the browser — search your workspace, read daily notes, manage folios, chat with the agent — you can do from your shell. Each command mirrors a host API route 1:1.

Run bare carabase with no subcommand and you land in an interactive REPL; pass a verb (carabase search "…") and it runs that one command and exits.

Note

This page is about the carabase CLI (the agent/workspace client). For the pnpm wrapper scripts that operate the host itself (db:migrate, backup, deploy:prod, …) see the CLI scripts reference. For first-time onboarding, start with the Quickstart.

Getting the binary

There are two ways to run it.

From the repo (dev path). If you’ve cloned the host, pnpm carabase runs the CLI straight from source:

pnpm carabase --help
pnpm carabase           # opens the REPL

As a standalone binary. Build once and link it so carabase / cb are on your PATH — cleaner output (no pnpm wrapper lines) and you can run it from any directory:

pnpm build && pnpm link --global
carabase --help
cb --help

The rest of this page writes carabase; substitute pnpm carabase if you’re on the dev path.

Connecting to a host

The CLI needs two things: which host to talk to and which workspace to act on. Both follow a strict precedence (flag → environment variable → .env.<env> file → default).

Host URL

Source	How
Flag	--base-url http://host:3000 (short -u)
Env var	export CARABASE_BASE_URL=http://host:3000
Default	http://127.0.0.1:3000 (or $PORT)

Workspace

Source	How
Flag	--workspace <uuid> (short -w)
Env var	export DEFAULT_WORKSPACE_ID=<uuid>
.env file	carabase workspace use <uuid> persists it
—	required for workspace-scoped commands

By default there is no API token — the CLI authenticates by reachability. Carabase has no public ports, so being able to reach the host (over Tailscale) is the authorization.

Caution

That holds only while owner-auth enforcement (oauth_auth_enabled) is off — which is the default. Flipping enforcement on makes the host require OAuth bearer tokens on API routes, and the CLI does not yet carry one — so leave enforcement off on hosts you drive from the CLI. See Securing your host.

Caution

The default environment is prod, not dev (the canonical deployment is an operator pointing the CLI at their always-on host). carabase workspace use therefore writes to .env.production unless you pass --env dev or set CARABASE_ENV. Keep the file you write and the one being read in sync.

Local host

If the host is running on the same machine, you only need a workspace:

carabase workspace list                 # discover workspaces (no workspace flag needed)
carabase workspace use <uuid>           # persist it as the default
carabase                                # REPL, pointed at localhost

Remote host

To target a host on another machine, point --base-url at its Tailscale address (a 100.x IP, or better, its MagicDNS name so it survives IP changes):

carabase --base-url http://my-host.tailnet.ts.net:3000 \
         --workspace <uuid> \
         workspace show

To make a remote target stick for a shell session, export the two variables — bare carabase then opens the REPL against the remote host:

export CARABASE_BASE_URL=http://my-host.tailnet.ts.net:3000
export DEFAULT_WORKSPACE_ID=<uuid>
carabase

workspace list is a good first call to confirm reachability: it hits an exempt route (no workspace header) and lists what actually exists on that host.

The interactive REPL

Bare carabase opens the REPL: a banner with host/gateway status up top, a prompt, and a status line pinned to the bottom row (workspace · session · last activity · gateway).

• Type a prompt and press Enter to chat with the agent (routes through /agent/message).
• /help lists the slash commands; /exit (or Ctrl+D on an empty line) quits.
• Shift+Enter inserts a newline for multi-line input; Enter submits.
• Ctrl+C aborts an in-flight response; press it twice quickly to exit.
• Up/Down walk per-workspace command history.

Chat routes through the single /agent/message contract. Which engine actually answers — the OpenClaw gateway, the host-native model loop, or a local codex/claude bridge — is configured on the host, not the CLI, so the REPL behaves the same regardless of how the workspace is wired.

Every non-REPL command also works as a one-shot from your shell — carabase search "quarterly planning" runs and exits without entering the REPL.

Command catalog

Run carabase --help for the authoritative list. The headline commands:

Retrieval & Q&A

Command	What it does
carabase ask "<question>"	Natural-language Q&A over your workspace (the ask-knowledge skill)
carabase search "<query>"	Semantic search over the workspace
carabase find "<prose>"	Structured-query retrieval — prose → metadata filter → matching items
carabase recall "<query>"	Memory-network biased retrieval — surfaces the most relevant memories
carabase analyze "<subject>"	Entity-anchored deep analysis (analyze-subject skill)
carabase summarize …	Folio / date-range / source scope → synthesized narrative
carabase summon	Workspace landing card — pulse, pending tasks, folios, recent days

Capture & notes

Command	What it does
carabase note add "<text>"	Write a logCard to today’s daily note
carabase bullet "<text>"	Write a bulleted logCard
carabase task add|list|check	Manage daily-note tasks
carabase daily-notes	Read daily notes
carabase harvest …	Feed content into the harvest + entity-extraction pipeline
carabase import …	Run a one-shot importer (Obsidian, Notion, …)

Knowledge graph & memory

Command	What it does
carabase folio	Manage folios — the unified substrate for collections and taste / domain / project narratives (create, list, delete, commit)
carabase entity	Knowledge-graph node CRUD
carabase edge	Knowledge-graph edges (read-only)
carabase memory list|add|search	Long-term memories
carabase decisions	List recorded decision records (carabase decide "<title>" to add one)
carabase why --file|--topic	Find which decision governs a given file or topic
carabase soul	Owner profile (SOUL.md) — show / edit / reset

Agent & operations

Command	What it does
carabase chat	Ask the agent a question (streaming) + list sessions and messages
carabase agent	Dispatch, list, and watch Agentic Flows runs
carabase workspace	Discover and select workspaces
carabase init	Interactive first-run onboarding wizard
carabase setup status	First-run setup check matrix
carabase health	Ping the running host
carabase env	Inspect and manage .env.<env> files
carabase version	Print the host version

Global flags

These apply to any command (and the REPL):

Flag	Effect
-e, --env <dev|staging|prod>	Which .env.<env> to read (default prod)
-w, --workspace <uuid>	Override the default workspace
-u, --base-url <url>	Override the host URL
--json	Emit JSON instead of pretty text (great for piping; not allowed with the interactive REPL)
--no-color	Disable coloured output
-v, --verbose	Verbose diagnostics on stderr
-q, --quiet	Suppress informational output

Troubleshooting

“Host unreachable.” The CLI couldn’t open a connection to --base-url. Confirm the host is running and, for a remote host, that you’re on the tailnet. carabase health and carabase workspace list are the cheapest probes.

“No workspace selected.” A workspace-scoped command ran without a workspace. Pass --workspace <uuid>, export DEFAULT_WORKSPACE_ID, or run carabase workspace use <uuid>.

The REPL renders as one broken line. A previous REPL that exited uncleanly can leave your terminal’s scroll region stuck. Open a fresh terminal tab, or reset the current one:

printf '\033[r\033[2J\033[H'   # reset scroll region, clear, home cursor
# or the blunt instrument:
reset

--json is refused in the REPL. Interactive input and machine-readable output are mutually exclusive. Use --json with a single command (carabase --json search "…") or pipe input via stdin.