Skip to main content

CLI Commands Reference

This page covers the terminal commands you run from your shell.

For in-chat slash commands, see Slash Commands Reference.

Global entrypoint

crewlabs [global-options] <command> [subcommand/options]

Global options

OptionDescription
--version, -VShow version and exit.
--profile <name>, -p <name>Select which Crewlabs profile to use for this invocation. Overrides the sticky default set by crewlabs profile use.
--resume <session>, -r <session>Resume a previous session by ID or title.
--continue [name], -c [name]Resume the most recent session, or the most recent session matching a title.
--worktree, -wStart in an isolated git worktree for parallel-agent workflows.
--yoloBypass dangerous-command approval prompts.
--pass-session-idInclude the session ID in the agent's system prompt.
--ignore-user-configIgnore ~/.crewlabs/config.yaml and fall back to built-in defaults. Credentials in .env are still loaded.
--ignore-rulesSkip auto-injection of AGENTS.md, SOUL.md, .cursorrules, memory, and preloaded skills.
--tuiLaunch the TUI instead of the classic CLI. Equivalent to CREWLABS_TUI=1.
--devWith --tui: run the TypeScript sources directly via tsx instead of the prebuilt bundle (for TUI contributors).

Top-level commands

CommandPurpose
crewlabs chatInteractive or one-shot chat with the agent.
crewlabs modelInteractively choose the default provider and model.
crewlabs fallbackManage fallback providers tried when the primary model errors.
crewlabs gatewayRun or manage the messaging gateway service.
crewlabs proxyLocal OpenAI-compatible proxy that attaches OAuth provider credentials. See Subscription Proxy.
crewlabs lspManage Language Server Protocol integration (semantic diagnostics for write_file/patch).
crewlabs setupInteractive setup wizard for all or part of the configuration.
crewlabs whatsappConfigure and pair the WhatsApp bridge.
crewlabs slackSlack helpers (currently: generate the app manifest with every command as a native slash).
crewlabs authManage credentials — add, list, remove, reset, set strategy. Handles OAuth flows for Codex/Nous/Anthropic.
crewlabs login / logoutDeprecated — use crewlabs auth instead.
crewlabs statusShow agent, auth, and platform status.
crewlabs cronInspect and tick the cron scheduler.
crewlabs kanbanMulti-profile collaboration board (tasks, links, dispatcher).
crewlabs webhookManage dynamic webhook subscriptions for event-driven activation.
crewlabs hooksInspect, approve, or remove shell-script hooks declared in config.yaml.
crewlabs doctorDiagnose config and dependency issues.
crewlabs security auditOn-demand supply-chain audit (OSV.dev) for the venv, plugin requirements, and pinned MCP servers.
crewlabs dumpCopy-pasteable setup summary for support/debugging.
crewlabs debugDebug tools — upload logs and system info for support.
crewlabs backupBack up Crewlabs home directory to a zip file.
crewlabs checkpointsInspect / prune / clear ~/.crewlabs/checkpoints/ (the shadow store used by /rollback). Run with no args for a status overview.
crewlabs importRestore a Crewlabs backup from a zip file.
crewlabs logsView, tail, and filter agent/gateway/error log files.
crewlabs configShow, edit, migrate, and query configuration files.
crewlabs pairingApprove or revoke messaging pairing codes.
crewlabs skillsBrowse, install, publish, audit, and configure skills.
crewlabs bundlesGroup several skills under a single /<name> slash command. See Skill Bundles.
crewlabs curatorBackground skill maintenance — status, run, pause, pin. See Curator.
crewlabs memoryConfigure external memory provider. Plugin-specific subcommands (e.g. crewlabs honcho) register automatically when their provider is active.
crewlabs acpRun Crewlabs as an ACP server for editor integration.
crewlabs mcpManage MCP server configurations and run Crewlabs as an MCP server.
crewlabs pluginsManage Crewlabs Agent plugins (install, enable, disable, remove).
crewlabs portalNous Portal status, subscription link, and Tool Gateway routing. See Tool Gateway.
crewlabs toolsConfigure enabled tools per platform.
crewlabs computer-useInstall or check the cua-driver backend (macOS Computer Use).
crewlabs sessionsBrowse, export, prune, rename, and delete sessions.
crewlabs insightsShow token/cost/activity analytics.
crewlabs clawOpenClaw migration helpers.
crewlabs dashboardLaunch the web dashboard for managing config, API keys, and sessions.
crewlabs profileManage profiles — multiple isolated Crewlabs instances.
crewlabs completionPrint shell completion scripts (bash/zsh/fish).
crewlabs versionShow version information.
crewlabs updatePull latest code and reinstall dependencies (git installs), or check PyPI and pip install --upgrade (pip installs). --check previews without installing; --backup takes a pre-pull CREWLABS_HOME snapshot.
crewlabs uninstallRemove Crewlabs from the system.

crewlabs chat

crewlabs chat [options]

Common options:

OptionDescription
-q, --query "..."One-shot, non-interactive prompt.
-m, --model <model>Override the model for this run.
-t, --toolsets <csv>Enable a comma-separated set of toolsets.
--provider <provider>Force a provider: auto, openrouter, nous, openai-codex, copilot-acp, copilot, anthropic, gemini, google-gemini-cli, huggingface, novita, zai, kimi-coding, kimi-coding-cn, minimax, minimax-cn, minimax-oauth, kilocode, xiaomi, arcee, gmi, alibaba, alibaba-coding-plan (alias alibaba_coding), deepseek, nvidia, ollama-cloud, xai (alias grok), xai-oauth (alias grok-oauth), qwen-oauth, bedrock, opencode-zen, opencode-go, ai-gateway, azure-foundry, lmstudio, stepfun, tencent-tokenhub (alias tencent, tokenhub).
-s, --skills <name>Preload one or more skills for the session (can be repeated or comma-separated).
-v, --verboseVerbose output.
-Q, --quietProgrammatic mode: suppress banner/spinner/tool previews.
--image <path>Attach a local image to a single query.
--resume <session> / --continue [name]Resume a session directly from chat.
--worktreeCreate an isolated git worktree for this run.
--checkpointsEnable filesystem checkpoints before destructive file changes.
--yoloSkip approval prompts.
--pass-session-idPass the session ID into the system prompt.
--ignore-user-configIgnore ~/.crewlabs/config.yaml and use built-in defaults. Credentials in .env are still loaded. Useful for isolated CI runs, reproducible bug reports, and third-party integrations.
--ignore-rulesSkip auto-injection of AGENTS.md, SOUL.md, .cursorrules, persistent memory, and preloaded skills. Combine with --ignore-user-config for a fully isolated run.
--source <tag>Session source tag for filtering (default: cli). Use tool for third-party integrations that should not appear in user session lists.
--max-turns <N>Maximum tool-calling iterations per conversation turn (default: 90, or agent.max_turns in config).

Examples:

crewlabs
crewlabs chat -q "Summarize the latest PRs"
crewlabs chat --provider openrouter --model anthropic/claude-sonnet-4.6
crewlabs chat --toolsets web,terminal,skills
crewlabs chat --quiet -q "Return only JSON"
crewlabs chat --worktree -q "Review this repo and open a PR"
crewlabs chat --ignore-user-config --ignore-rules -q "Repro without my personal setup"

crewlabs -z <prompt> — scripted one-shot

For programmatic callers (shell scripts, CI, cron, parent processes piping in a prompt), crewlabs -z is the purest one-shot entry point: single prompt in, final response text out, nothing else on stdout or stderr. No banner, no spinner, no tool previews, no Session: line — just the agent's final reply as plain text.

crewlabs -z "What's the capital of France?"
# → Paris.

# Parent scripts can cleanly capture the response:
answer=$(crewlabs -z "summarize this" < /path/to/file.txt)

Per-run overrides (no mutation to ~/.crewlabs/config.yaml):

FlagEquivalent env varPurpose
-m / --model <model>CREWLABS_INFERENCE_MODELOverride the model for this run
--provider <provider>(none)Override the provider for this run
crewlabs -z "…" --provider openrouter --model openai/gpt-5.5
# or:
CREWLABS_INFERENCE_MODEL=anthropic/claude-sonnet-4.6 crewlabs -z "…"

Same agent, same tools, same skills — just strips every interactive / cosmetic layer. If you need tool output in the transcript too, use crewlabs chat -q instead; -z is explicitly for "I only want the final answer".

crewlabs model

Interactive provider + model selector. This is the command for adding new providers, setting up API keys, and running OAuth flows. Run it from your terminal — not from inside an active Crewlabs chat session.

crewlabs model

Use this when you want to:

  • add a new provider (OpenRouter, Anthropic, Copilot, DeepSeek, custom, etc.)
  • log into OAuth-backed providers (Anthropic, Copilot, Codex, Nous Portal)
  • enter or update API keys
  • pick from provider-specific model lists
  • configure a custom/self-hosted endpoint
  • save the new default into config
crewlabs model vs /model — know the difference

crewlabs model (run from your terminal, outside any Crewlabs session) is the full provider setup wizard. It can add new providers, run OAuth flows, prompt for API keys, and configure endpoints.

/model (typed inside an active Crewlabs chat session) can only switch between providers and models you've already set up. It cannot add new providers, run OAuth, or prompt for API keys.

If you need to add a new provider: Exit your Crewlabs session first (Ctrl+C or /quit), then run crewlabs model from your terminal prompt.

/model slash command (mid-session)

Switch between already-configured models without leaving a session:

/model                              # Show current model and available options
/model claude-sonnet-4 # Switch model (auto-detects provider)
/model zai:glm-5 # Switch provider and model
/model custom:qwen-2.5 # Use model on your custom endpoint
/model custom # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5 # Use a named custom provider
/model openrouter:anthropic/claude-sonnet-4 # Switch back to cloud

By default, /model changes apply to the current session only. Add --global to persist the change to config.yaml:

/model claude-sonnet-4 --global     # Switch and save as new default
What if I only see OpenRouter models?

If you've only configured OpenRouter, /model will only show OpenRouter models. To add another provider (Anthropic, DeepSeek, Copilot, etc.), exit your session and run crewlabs model from the terminal.

Provider and base URL changes are persisted to config.yaml automatically. When switching away from a custom endpoint, the stale base URL is cleared to prevent it leaking into other providers.

crewlabs gateway

crewlabs gateway <subcommand>

Subcommands:

SubcommandDescription
runRun the gateway in the foreground. Recommended for WSL, Docker, and Termux.
startStart the installed systemd/launchd background service.
stopStop the service (or foreground process).
restartRestart the service.
statusShow service status.
listList all profiles and whether each profile's gateway is currently running (with PID where available). Handy when you run multiple profiles side-by-side and want a single overview.
installInstall as a systemd (Linux) or launchd (macOS) background service.
uninstallRemove the installed service.
setupInteractive messaging-platform setup.

Options:

OptionDescription
--allOn start / restart / stop: act on every profile's gateway, not just the active CREWLABS_HOME. Useful if you run multiple profiles side-by-side and want to restart them all after crewlabs update.
WSL users

Use crewlabs gateway run instead of crewlabs gateway start — WSL's systemd support is unreliable. Wrap it in tmux for persistence: tmux new -s crewlabs 'crewlabs gateway run'. See WSL FAQ for details.

crewlabs lsp

crewlabs lsp <subcommand>

Manage the Language Server Protocol integration. LSP runs real language servers (pyright, gopls, rust-analyzer, …) in the background and feeds their diagnostics into the post-write check used by write_file and patch. Gated on git workspace detection — LSP only runs when the cwd or edited file is inside a git worktree.

Subcommands:

SubcommandDescription
statusShow service state, configured servers, install status.
listPrint the registry of supported servers. Pass --installed-only to skip missing ones.
install <id>Eagerly install one server's binary.
install-allInstall every server with a known auto-install recipe.
restartTear down running clients so the next edit re-spawns.
which <id>Print the resolved binary path for one server.

See LSP — Semantic Diagnostics for the full guide, supported languages, and configuration knobs.

crewlabs setup

crewlabs setup [model|tts|terminal|gateway|tools|agent] [--non-interactive] [--reset] [--quick] [--reconfigure] [--portal]

First run: launches the first-time wizard.

Returning user (already configured): drops straight into the full reconfigure wizard — every prompt shows your current value as its default, press Enter to keep or type a new value. No menu.

Jump into one section instead of the full wizard:

SectionDescription
modelProvider and model setup.
terminalTerminal backend and sandbox setup.
gatewayMessaging platform setup.
toolsEnable/disable tools per platform.
agentAgent behavior settings.

Options:

OptionDescription
--quickOn returning-user runs: only prompt for items that are missing or unset. Skip items you already have configured.
--non-interactiveUse defaults / environment values without prompts.
--resetReset configuration to defaults before setup.
--reconfigureBackwards-compat alias — bare crewlabs setup on an existing install now does this by default.
--portalOne-shot Nous Portal setup: log in via OAuth, set Nous as the inference provider, and opt into the Tool Gateway. Skips the rest of the wizard.

crewlabs portal

crewlabs portal [status|open|tools]

Inspect Nous Portal auth, Tool Gateway routing, and reach the subscription page. Subcommand-less invocation runs status.

SubcommandDescription
status (default)Portal auth state + per-tool Tool Gateway routing summary. Also shown when no subcommand is given.
openOpen portal.nousresearch.com/manage-subscription in your default browser.
toolsList every Tool Gateway partner (Firecrawl, FAL, OpenAI TTS, Browser Use, Modal) and which are routed via Nous.

For configuration of the gateway itself, see Tool Gateway. For the one-shot setup path, see crewlabs setup --portal above.

crewlabs whatsapp

crewlabs whatsapp

Runs the WhatsApp pairing/setup flow, including mode selection and QR-code pairing.

crewlabs slack

crewlabs slack manifest              # print manifest to stdout
crewlabs slack manifest --write # write to ~/.crewlabs/slack-manifest.json
crewlabs slack manifest --slashes-only # just the features.slash_commands array

Generates a Slack app manifest that registers every gateway command in COMMAND_REGISTRY (/btw, /stop, /model, …) as a first-class Slack slash command — matching Discord and Telegram parity. Paste the output into your Slack app config at https://api.slack.com/apps → your app → Features → App Manifest → Edit, then Save. Slack prompts for reinstall if scopes or slash commands changed.

FlagDefaultPurpose
--write [PATH]stdoutWrite to a file instead of stdout. Bare --write writes $CREWLABS_HOME/slack-manifest.json.
--name NAMECrewlabsBot display name in Slack.
--description DESCdefault blurbBot description shown in the Slack app directory.
--slashes-onlyoffEmit only features.slash_commands for merging into a manually-maintained manifest.

Run crewlabs slack manifest --write again after crewlabs update to pick up any new commands.

crewlabs login / crewlabs logout (Deprecated)

caution

crewlabs login has been removed. Use crewlabs auth to manage OAuth credentials, crewlabs model to select a provider, or crewlabs setup for full interactive setup.

crewlabs auth

Manage credential pools for same-provider key rotation. See Credential Pools for full documentation.

crewlabs auth                                              # Interactive wizard
crewlabs auth list # Show all pools
crewlabs auth list openrouter # Show specific provider
crewlabs auth add openrouter --api-key sk-or-v1-xxx # Add API key
crewlabs auth add anthropic --type oauth # Add OAuth credential
crewlabs auth remove openrouter 2 # Remove by index
crewlabs auth reset openrouter # Clear cooldowns
crewlabs auth status anthropic # Show auth status for a provider
crewlabs auth logout anthropic # Log out and clear stored auth state
crewlabs auth spotify # Authenticate Crewlabs with Spotify via PKCE

Subcommands: add, list, remove, reset, status, logout, spotify. When called with no subcommand, launches the interactive management wizard.

crewlabs status

crewlabs status [--all] [--deep]
OptionDescription
--allShow all details in a shareable redacted format.
--deepRun deeper checks that may take longer.

crewlabs cron

crewlabs cron <list|create|edit|pause|resume|run|remove|status|tick>
SubcommandDescription
listShow scheduled jobs.
create / addCreate a scheduled job from a prompt, optionally attaching one or more skills via repeated --skill.
editUpdate a job's schedule, prompt, name, delivery, repeat count, or attached skills. Supports --clear-skills, --add-skill, and --remove-skill.
pausePause a job without deleting it.
resumeResume a paused job and compute its next future run.
runTrigger a job on the next scheduler tick.
removeDelete a scheduled job.
statusCheck whether the cron scheduler is running.
tickRun due jobs once and exit.

crewlabs kanban

crewlabs kanban [--board <slug>] <action> [options]

Multi-profile, multi-project collaboration board. Each install can host many boards (one per project, repo, or domain); each board is a standalone queue with its own SQLite DB and dispatcher scope. New installs start with one board called default, whose DB is ~/.crewlabs/kanban.db for back-compat; additional boards live at ~/.crewlabs/kanban/boards/<slug>/kanban.db. The gateway-embedded dispatcher sweeps every board per tick.

Global flags (apply to every action below):

FlagPurpose
--board <slug>Operate on a specific board. Defaults to the current board (set via crewlabs kanban boards switch, the CREWLABS_KANBAN_BOARD env var, or default).

This is the human / scripting surface. Agent workers spawned by the dispatcher drive the board through a dedicated kanban_* toolset (kanban_show, kanban_complete, kanban_block, kanban_create, kanban_link, kanban_comment, kanban_heartbeat; orchestrator profiles also get kanban_list and kanban_unblock) instead of shelling to crewlabs kanban. Workers have CREWLABS_KANBAN_BOARD pinned in their env so they physically cannot see other boards.

ActionPurpose
initCreate kanban.db if missing. Idempotent.
boards list / boards lsList all boards with task counts. --json, --all (include archived).
boards create <slug>Create a new board. Flags: --name, --description, --icon, --color, --switch (make active). Slug is kebab-case, auto-downcased.
boards switch <slug> / boards usePersist <slug> as the active board (writes ~/.crewlabs/kanban/current).
boards show / boards currentPrint the currently-active board's name, DB path, and task counts.
boards rename <slug> "<name>"Change a board's display name. Slug is immutable.
boards rm <slug>Archive (default) or hard-delete a board. --delete skips the archive step. Archived boards move to boards/_archived/<slug>-<ts>/. Refused for default.
create "<title>"Create a new task on the active board. Flags: --body, --assignee, --parent (repeatable), --workspace scratch|worktree|dir:<path>, --tenant, --priority, --triage, --idempotency-key, --max-runtime, --max-retries, --skill (repeatable).
list / lsList tasks on the active board. Filter with --mine, --assignee, --status, --tenant, --archived, --json.
show <id>Show a task with comments and events. --json for machine output.
assign <id> <profile>Assign or reassign. Use none to unassign. Refused while task is running.
link <parent> <child>Add a dependency. Cycle-detected. Both tasks must be on the same board.
unlink <parent> <child>Remove a dependency.
claim <id>Atomically claim a ready task. Prints resolved workspace path.
comment <id> "<text>"Append a comment. The next worker that claims the task reads it as part of its kanban_show() response.
complete <id>Mark task done. Flags: --result, --summary, --metadata.
block <id> "<reason>"Mark task blocked for human input. Also appends the reason as a comment.
schedule <id> "<reason>"Park time-delay/follow-up work in scheduled so it is not shown as a human blocker.
unblock <id>Return a blocked or scheduled task to ready (or todo if dependencies are still open).
archive <id>Hide from default list. gc will remove scratch workspaces.
tail <id>Follow a task's event stream.
dispatchOne dispatcher pass on the active board. Flags: --dry-run, --max N, --failure-limit N, --json.
context <id>Print the full context a worker would see (title + body + parent results + comments).
specify <id> / specify --allFlesh out a triage-column task into a concrete spec (title + body with goal, approach, acceptance criteria) via the auxiliary LLM, then promote it to todo. Flags: --tenant (scope --all to one tenant), --author, --json. Configure the model under auxiliary.triage_specifier in config.yaml.
decompose <id> / decompose --allFan a triage-column task out into a graph of child tasks routed to specialist profiles by description (the orchestrator-driven path). Falls back to specify-style single-task promotion when the LLM decides the task doesn't benefit from fan-out. Same flags as specify. Configure the model under auxiliary.kanban_decomposer in config.yaml. Also runs automatically every dispatcher tick when kanban.auto_decompose: true (the default). See Auto vs Manual orchestration.
gcRemove scratch workspaces for archived tasks.

Examples:

# Create a second board and put a task on it without switching away.
crewlabs kanban boards create atm10-server --name "ATM10 Server" --icon 🎮
crewlabs kanban --board atm10-server create "Restart server" --assignee ops

# Switch the active board for subsequent calls.
crewlabs kanban boards switch atm10-server
crewlabs kanban list # shows atm10-server tasks

# Archive a board (recoverable) or hard-delete it.
crewlabs kanban boards rm atm10-server
crewlabs kanban boards rm atm10-server --delete

Board resolution order (highest precedence first): --board <slug> flag → CREWLABS_KANBAN_BOARD env var → ~/.crewlabs/kanban/current file → default.

All actions are also available as a slash command in the gateway (/kanban …), with the same argument surface — including boards subcommands and the --board flag.

For the full design — comparison with Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise, eight collaboration patterns, four user stories, concurrency correctness proof — see docs/crewlabs-kanban-v1-spec.pdf in the repository or the Kanban user guide.

crewlabs webhook

crewlabs webhook <subscribe|list|remove|test>

Manage dynamic webhook subscriptions for event-driven agent activation. Requires the webhook platform to be enabled in config — if not configured, prints setup instructions.

SubcommandDescription
subscribe / addCreate a webhook route. Returns the URL and HMAC secret to configure on your service.
list / lsShow all agent-created subscriptions.
remove / rmDelete a dynamic subscription. Static routes from config.yaml are not affected.
testSend a test POST to verify a subscription is working.

crewlabs webhook subscribe

crewlabs webhook subscribe <name> [options]
OptionDescription
--promptPrompt template with {dot.notation} payload references.
--eventsComma-separated event types to accept (e.g. issues,pull_request). Empty = all.
--descriptionHuman-readable description.
--skillsComma-separated skill names to load for the agent run.
--deliverDelivery target: log (default), telegram, discord, slack, github_comment.
--deliver-chat-idTarget chat/channel ID for cross-platform delivery.
--secretCustom HMAC secret. Auto-generated if omitted.
--deliver-onlySkip the agent — deliver the rendered --prompt as the literal message. Zero LLM cost, sub-second delivery. Requires --deliver to be a real target (not log).

Subscriptions persist to ~/.crewlabs/webhook_subscriptions.json and are hot-reloaded by the webhook adapter without a gateway restart.

crewlabs doctor

crewlabs doctor [--fix]
OptionDescription
--fixAttempt automatic repairs where possible.

crewlabs dump

crewlabs dump [--show-keys]

Outputs a compact, plain-text summary of your entire Crewlabs setup. Designed to be copy-pasted into Discord, GitHub issues, or Telegram when asking for support — no ANSI colors, no special formatting, just data.

OptionDescription
--show-keysShow redacted API key prefixes (first and last 4 characters) instead of just set/not set.

What it includes

SectionDetails
HeaderCrewlabs version, release date, git commit hash
EnvironmentOS, Python version, OpenAI SDK version
IdentityActive profile name, CREWLABS_HOME path
ModelConfigured default model and provider
TerminalBackend type (local, docker, ssh, etc.)
API keysPresence check for all 22 provider/tool API keys
FeaturesEnabled toolsets, MCP server count, memory provider
ServicesGateway status, configured messaging platforms
WorkloadCron job counts, installed skill count
Config overridesAny config values that differ from defaults

Example output

--- crewlabs dump ---
version: 0.8.0 (2026.4.8) [af4abd2f]
os: Linux 6.14.0-37-generic x86_64
python: 3.11.14
openai_sdk: 2.24.0
profile: default
crewlabs_home: ~/.crewlabs
model: anthropic/claude-opus-4.6
provider: openrouter
terminal: local

api_keys:
openrouter set
openai not set
anthropic set
nous not set
firecrawl set
...

features:
toolsets: all
mcp_servers: 0
memory_provider: built-in
gateway: running (systemd)
platforms: telegram, discord
cron_jobs: 3 active / 5 total
skills: 42

config_overrides:
agent.max_turns: 250
compression.threshold: 0.85
display.streaming: True
--- end dump ---

When to use

  • Reporting a bug on GitHub — paste the dump into your issue
  • Asking for help in Discord — share it in a code block
  • Comparing your setup to someone else's
  • Quick sanity check when something isn't working
tip

crewlabs dump is specifically designed for sharing. For interactive diagnostics, use crewlabs doctor. For a visual overview, use crewlabs status.

crewlabs debug

crewlabs debug share [options]

Upload a debug report (system info + recent logs) to a paste service and get a shareable URL. Useful for quick support requests — includes everything a helper needs to diagnose your issue.

OptionDescription
--lines <N>Number of log lines to include per log file (default: 200).
--expire <days>Paste expiry in days (default: 7).
--localPrint the report locally instead of uploading.

The report includes system info (OS, Python version, Crewlabs version), recent agent and gateway logs (512 KB limit per file), and redacted API key status. Keys are always redacted — no secrets are uploaded.

Paste services tried in order: paste.rs, dpaste.com.

Examples

crewlabs debug share              # Upload debug report, print URL
crewlabs debug share --lines 500 # Include more log lines
crewlabs debug share --expire 30 # Keep paste for 30 days
crewlabs debug share --local # Print report to terminal (no upload)

crewlabs backup

crewlabs backup [options]

Create a zip archive of your Crewlabs configuration, skills, sessions, and data. The backup excludes the crewlabs-agent codebase itself.

OptionDescription
-o, --output <path>Output path for the zip file (default: ~/crewlabs-backup-<timestamp>.zip).
-q, --quickQuick snapshot: only critical state files (config.yaml, state.db, .env, auth, cron jobs). Much faster than a full backup.
-l, --label <name>Label for the snapshot (only used with --quick).

The backup uses SQLite's backup() API for safe copying, so it works correctly even when Crewlabs is running (WAL-mode safe).

What's excluded from the zip:

  • *.db-wal, *.db-shm, *.db-journal — SQLite's WAL / shared-memory / journal sidecars. The *.db file already got a consistent snapshot via sqlite3.backup(); shipping the live sidecars alongside it would let a restore see a half-committed state.
  • checkpoints/ — per-session trajectory caches. Hash-keyed and regenerated per session; wouldn't port cleanly to another install anyway.
  • The crewlabs-agent code itself (this is a user-data backup, not a repo snapshot).

Examples

crewlabs backup                           # Full backup to ~/crewlabs-backup-*.zip
crewlabs backup -o /tmp/crewlabs.zip # Full backup to specific path
crewlabs backup --quick # Quick state-only snapshot
crewlabs backup --quick --label "pre-upgrade" # Quick snapshot with label

crewlabs checkpoints

crewlabs checkpoints [COMMAND]

Inspect and manage the shadow git store at ~/.crewlabs/checkpoints/ — the storage layer behind the in-session /rollback command. Safe to run any time; does not require the agent to be running.

SubcommandDescription
status (default)Show total size, project count, and per-project breakdown. Bare crewlabs checkpoints is equivalent.
listAlias for status.
pruneForce a cleanup sweep — delete orphan and stale projects, GC the store, enforce the size cap. Ignores the 24h idempotency marker.
clearDelete the entire checkpoint base. Irreversible; asks for confirmation unless -f.
clear-legacyDelete only the legacy-<timestamp>/ archives produced by the v1→v2 migration.

Options

OptionSubcommandDescription
--limit Nstatus, listMax projects to list (default 20).
--retention-days NpruneDrop projects whose last_touch is older than N days (default 7).
--max-size-mb NpruneAfter the orphan/stale pass, drop the oldest commit per project until total store size ≤ N MB (default 500).
--keep-orphanspruneSkip deleting projects whose working directory no longer exists.
-f, --forceclear, clear-legacySkip the confirmation prompt.

Examples

crewlabs checkpoints                                  # status overview
crewlabs checkpoints prune --retention-days 3 # aggressive cleanup
crewlabs checkpoints prune --max-size-mb 200 # tighten size cap once
crewlabs checkpoints clear-legacy -f # drop v1 archive dirs
crewlabs checkpoints clear -f # wipe everything

See Checkpoints and /rollback for the full architecture and the in-session commands.

crewlabs import

crewlabs import <zipfile> [options]

Restore a previously created Crewlabs backup into your Crewlabs home directory. All files in the archive overwrite existing files in your Crewlabs home; --force only skips the confirmation prompt that fires when the target already has a Crewlabs installation.

OptionDescription
-f, --forceSkip the existing-installation confirmation prompt.
warning

Stop the gateway before importing to avoid conflicts with running processes.

Examples

crewlabs import ~/crewlabs-backup-20260423.zip           # Prompts before overwriting existing config
crewlabs import ~/crewlabs-backup-20260423.zip --force # Overwrite without prompting

crewlabs logs

crewlabs logs [log_name] [options]

View, tail, and filter Crewlabs log files. All logs are stored in ~/.crewlabs/logs/ (or <profile>/logs/ for non-default profiles).

Log files

NameFileWhat it captures
agent (default)agent.logAll agent activity — API calls, tool dispatch, session lifecycle (INFO and above)
errorserrors.logWarnings and errors only — a filtered subset of agent.log
gatewaygateway.logMessaging gateway activity — platform connections, message dispatch, webhook events

Options

OptionDescription
log_nameWhich log to view: agent (default), errors, gateway, or list to show available files with sizes.
-n, --lines <N>Number of lines to show (default: 50).
-f, --followFollow the log in real time, like tail -f. Press Ctrl+C to stop.
--level <LEVEL>Minimum log level to show: DEBUG, INFO, WARNING, ERROR, CRITICAL.
--session <ID>Filter lines containing a session ID substring.
--since <TIME>Show lines from a relative time ago: 30m, 1h, 2d, etc. Supports s (seconds), m (minutes), h (hours), d (days).
--component <NAME>Filter by component: gateway, agent, tools, cli, cron.

Examples

# View the last 50 lines of agent.log (default)
crewlabs logs

# Follow agent.log in real time
crewlabs logs -f

# View the last 100 lines of gateway.log
crewlabs logs gateway -n 100

# Show only warnings and errors from the last hour
crewlabs logs --level WARNING --since 1h

# Filter by a specific session
crewlabs logs --session abc123

# Follow errors.log, starting from 30 minutes ago
crewlabs logs errors --since 30m -f

# List all log files with their sizes
crewlabs logs list

Filtering

Filters can be combined. When multiple filters are active, a log line must pass all of them to be shown:

# WARNING+ lines from the last 2 hours containing session "tg-12345"
crewlabs logs --level WARNING --since 2h --session tg-12345

Lines without a parseable timestamp are included when --since is active (they may be continuation lines from a multi-line log entry). Lines without a detectable level are included when --level is active.

Log rotation

Crewlabs uses Python's RotatingFileHandler. Old logs are rotated automatically — look for agent.log.1, agent.log.2, etc. The crewlabs logs list subcommand shows all log files including rotated ones.

crewlabs config

crewlabs config <subcommand>

Subcommands:

SubcommandDescription
showShow current config values.
editOpen config.yaml in your editor.
set <key> <value>Set a config value.
pathPrint the config file path.
env-pathPrint the .env file path.
checkCheck for missing or stale config.
migrateAdd newly introduced options interactively.

crewlabs pairing

crewlabs pairing <list|approve|revoke|clear-pending>
SubcommandDescription
listShow pending and approved users.
approve <platform> <code>Approve a pairing code.
revoke <platform> <user-id>Revoke a user's access.
clear-pendingClear pending pairing codes.

crewlabs skills

crewlabs skills <subcommand>

Subcommands:

SubcommandDescription
browsePaginated browser for skill registries.
searchSearch skill registries.
installInstall a skill.
inspectPreview a skill without installing it.
listList installed skills.
checkCheck installed hub skills for upstream updates.
updateReinstall hub skills with upstream changes when available.
auditRe-scan installed hub skills.
uninstallRemove a hub-installed skill.
resetUn-stick a bundled skill flagged as user_modified by clearing its manifest entry. With --restore, also replaces the user copy with the bundled version.
publishPublish a skill to a registry.
snapshotExport/import skill configurations.
tapManage custom skill sources.
configInteractive enable/disable configuration for skills by platform.

Common examples:

crewlabs skills browse
crewlabs skills browse --source official
crewlabs skills search react --source skills-sh
crewlabs skills search https://mintlify.com/docs --source well-known
crewlabs skills inspect official/security/1password
crewlabs skills inspect skills-sh/vercel-labs/json-render/json-render-react
crewlabs skills install official/migration/openclaw-migration
crewlabs skills install skills-sh/anthropics/skills/pdf --force
crewlabs skills install https://sharethis.chat/SKILL.md # Direct URL (single-file SKILL.md)
crewlabs skills install https://example.com/SKILL.md --name my-skill # Override name when frontmatter has none
crewlabs skills check
crewlabs skills update
crewlabs skills config
crewlabs skills reset google-workspace
crewlabs skills reset google-workspace --restore --yes

Notes:

  • --force can override non-dangerous policy blocks for third-party/community skills.
  • --force does not override a dangerous scan verdict.
  • --source skills-sh searches the public skills.sh directory.
  • --source well-known lets you point Crewlabs at a site exposing /.well-known/skills/index.json.
  • --source browse-sh searches browse.sh's catalog of 200+ site-specific browser-automation skills. Identifiers look like browse-sh/airbnb.com/search-listings-ddgioa.
  • Passing an http(s)://…/*.md URL installs a single-file SKILL.md directly. When frontmatter has no name: and the URL slug isn't a valid identifier, an interactive terminal prompts for a name; non-interactive surfaces (/skills install inside the TUI, gateway platforms) require --name <x> instead.

crewlabs bundles

crewlabs bundles <subcommand>

Skill bundles group several skills under one /<bundle-name> slash command. Invoking the bundle loads every referenced skill into a single combined user message. Storage: ~/.crewlabs/skill-bundles/<slug>.yaml. See Skill Bundles for the YAML schema and behavior.

Subcommands:

SubcommandDescription
listList installed bundles (default when no subcommand given)
show <name>Show one bundle's name, description, skills, and file path
create <name>Create a new bundle. Pass --skill <id> (repeat) or omit for interactive entry. --description, --instruction, --force available.
delete <name>Remove a bundle file
reloadRe-scan ~/.crewlabs/skill-bundles/ and report added/removed bundles

Examples:

crewlabs bundles create backend-dev \
--skill github-code-review \
--skill test-driven-development \
--skill github-pr-workflow \
-d "Backend feature work"

crewlabs bundles list
crewlabs bundles show backend-dev
crewlabs bundles delete backend-dev

In a chat session, /bundles lists installed bundles and /<bundle-name> loads one.

crewlabs curator

crewlabs curator <subcommand>

The curator is an auxiliary-model background task that periodically reviews agent-created skills, prunes stale ones, consolidates overlaps, and archives obsolete skills. Bundled and hub-installed skills are never touched. Archives are recoverable; auto-deletion never happens.

SubcommandDescription
statusShow curator status and skill stats
runTrigger a curator review now (blocks until the LLM pass finishes)
run --backgroundStart the LLM pass in a background thread and return immediately
run --dry-runPreview only — produce the review report with no mutations
backupTake a manual tar.gz snapshot of ~/.crewlabs/skills/ (curator also snapshots automatically before every real run)
rollbackRestore ~/.crewlabs/skills/ from a snapshot (defaults to newest)
rollback --listList available snapshots
rollback --id <ts>Restore a specific snapshot by id
rollback -ySkip the confirmation prompt
pausePause the curator until resumed
resumeResume a paused curator
pin <skill>Pin a skill so the curator never auto-transitions it
unpin <skill>Unpin a skill
restore <skill>Restore an archived skill
archive <skill>Archive a skill manually
pruneManually prune skills the curator would normally clean up
list-archivedList archived skills (recoverable via restore)

On a fresh install the first scheduled pass is deferred by one full interval_hours (7 days by default) — the gateway will not curate immediately on the first tick after crewlabs update. Use crewlabs curator run --dry-run to preview before that happens.

See Curator for behavior and config.

crewlabs fallback

crewlabs fallback <subcommand>

Manage the fallback provider chain. Fallback providers are tried in order when the primary model fails with rate-limit, overload, or connection errors.

SubcommandDescription
list (alias: ls)Show the current fallback chain (default when no subcommand)
addPick a provider + model (same picker as crewlabs model) and append to the chain
remove (alias: rm)Pick an entry to delete from the chain
clearRemove all fallback entries

See Fallback Providers.

crewlabs hooks

crewlabs hooks <subcommand>

Inspect shell-script hooks declared in ~/.crewlabs/config.yaml, test them against synthetic payloads, and manage the first-use consent allowlist at ~/.crewlabs/shell-hooks-allowlist.json.

SubcommandDescription
list (alias: ls)List configured hooks with matcher, timeout, and consent status
test <event>Fire every hook matching <event> against a synthetic payload
revoke (aliases: remove, rm)Remove a command's allowlist entries (takes effect on next restart)
doctorCheck each configured hook: exec bit, allowlist, mtime drift, JSON validity, and synthetic run timing

See Hooks for event signatures and payload shapes.

crewlabs memory

crewlabs memory <subcommand>

Set up and manage external memory provider plugins. Available providers: honcho, openviking, mem0, hindsight, holographic, retaindb, byterover, supermemory. Only one external provider can be active at a time. Built-in memory (MEMORY.md/USER.md) is always active.

Subcommands:

SubcommandDescription
setupInteractive provider selection and configuration.
statusShow current memory provider config.
offDisable external provider (built-in only).
Provider-specific subcommands

When an external memory provider is active, it may register its own top-level crewlabs <provider> command for provider-specific management (e.g. crewlabs honcho when Honcho is active). Inactive providers do not expose their subcommands. Run crewlabs --help to see what's currently wired in.

crewlabs acp

crewlabs acp

Starts Crewlabs as an ACP (Agent Client Protocol) stdio server for editor integration.

Related entrypoints:

crewlabs-acp
python -m acp_adapter

Install support first:

pip install -e '.[acp]'

See ACP Editor Integration and ACP Internals.

crewlabs mcp

crewlabs mcp <subcommand>

Manage MCP (Model Context Protocol) server configurations and run Crewlabs as an MCP server.

SubcommandDescription
serve [-v|--verbose]Run Crewlabs as an MCP server — expose conversations to other agents.
add <name> [--url URL] [--command CMD] [--args ...] [--auth oauth|header]Add an MCP server with automatic tool discovery.
remove <name> (alias: rm)Remove an MCP server from config.
list (alias: ls)List configured MCP servers.
test <name>Test connection to an MCP server.
configure <name> (alias: config)Toggle tool selection for a server.
login <name>Force re-authentication for an OAuth-based MCP server.

See MCP Config Reference, Use MCP with Crewlabs, and MCP Server Mode.

crewlabs plugins

crewlabs plugins [subcommand]

Unified plugin management — general plugins, memory providers, and context engines in one place. Running crewlabs plugins with no subcommand opens a composite interactive screen with two sections:

  • General Plugins — multi-select checkboxes to enable/disable installed plugins
  • Provider Plugins — single-select configuration for Memory Provider and Context Engine. Press ENTER on a category to open a radio picker.
SubcommandDescription
(none)Composite interactive UI — general plugin toggles + provider plugin configuration.
install <identifier> [--force]Install a plugin from a Git URL or owner/repo.
update <name>Pull latest changes for an installed plugin.
remove <name> (aliases: rm, uninstall)Remove an installed plugin.
enable <name>Enable a disabled plugin.
disable <name>Disable a plugin without removing it.
list (alias: ls)List installed plugins with enabled/disabled status.

Provider plugin selections are saved to config.yaml:

  • memory.provider — active memory provider (empty = built-in only)
  • context.engine — active context engine ("compressor" = built-in default)

General plugin disabled list is stored in config.yaml under plugins.disabled.

See Plugins and Build a Crewlabs Plugin.

crewlabs tools

crewlabs tools [--summary]
OptionDescription
--summaryPrint the current enabled-tools summary and exit.

Without --summary, this launches the interactive per-platform tool configuration UI.

crewlabs computer-use

crewlabs computer-use <subcommand>

Subcommands:

SubcommandDescription
installRun the upstream cua-driver installer (macOS only).
install --upgradeRe-run the installer even if cua-driver is already on PATH. The upstream script always pulls the latest release, so this performs an in-place upgrade.
statusPrint whether cua-driver is on $PATH and which version is installed.

crewlabs computer-use install is the stable entry point for installing the cua-driver binary used by the computer_use toolset. It runs the same upstream installer that crewlabs tools invokes when you first enable Computer Use, so it's safe to use for re-running the install if the toolset toggle didn't trigger it (for example, on returning-user setups).

crewlabs update automatically re-runs the upstream installer at the end of the update if cua-driver is on PATH, so most users will not need to call --upgrade manually. Use it when upstream ships a fix you want right now without waiting for the next Crewlabs update.

crewlabs sessions

crewlabs sessions <subcommand>

Subcommands:

SubcommandDescription
listList recent sessions.
browseInteractive session picker with search and resume.
export <output> [--session-id ID]Export sessions to JSONL.
delete <session-id>Delete one session.
pruneDelete old sessions.
statsShow session-store statistics.
rename <session-id> <title>Set or change a session title.

crewlabs insights

crewlabs insights [--days N] [--source platform]
OptionDescription
--days <n>Analyze the last n days (default: 30).
--source <platform>Filter by source such as cli, telegram, or discord.

crewlabs claw

crewlabs claw migrate [options]

Migrate your OpenClaw setup to Crewlabs. Reads from ~/.openclaw (or a custom path) and writes to ~/.crewlabs. Automatically detects legacy directory names (~/.clawdbot, ~/.moltbot) and config filenames (clawdbot.json, moltbot.json).

OptionDescription
--dry-runPreview what would be migrated without writing anything.
--preset <name>Migration preset: full (all compatible settings) or user-data (excludes infrastructure config). Neither preset imports secrets — pass --migrate-secrets explicitly.
--overwriteOverwrite existing Crewlabs files on conflicts (default: refuse to apply when the plan has conflicts).
--migrate-secretsInclude API keys in migration. Required even under --preset full.
--no-backupSkip the pre-migration zip snapshot of ~/.crewlabs/ (by default a single restore-point archive is written to ~/.crewlabs/backups/pre-migration-*.zip before apply; restorable with crewlabs import).
--source <path>Custom OpenClaw directory (default: ~/.openclaw).
--workspace-target <path>Target directory for workspace instructions (AGENTS.md).
--skill-conflict <mode>Handle skill name collisions: skip (default), overwrite, or rename.
--yesSkip the confirmation prompt.

What gets migrated

The migration covers 30+ categories across persona, memory, skills, model providers, messaging platforms, agent behavior, session policies, MCP servers, TTS, and more. Items are either directly imported into Crewlabs equivalents or archived for manual review.

Directly imported: SOUL.md, MEMORY.md, USER.md, AGENTS.md, skills (4 source directories), default model, custom providers, MCP servers, messaging platform tokens and allowlists (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), agent defaults (reasoning effort, compression, human delay, timezone, sandbox), session reset policies, approval rules, TTS config, browser settings, tool settings, exec timeout, command allowlist, gateway config, and API keys from 3 sources.

Archived for manual review: Cron jobs, plugins, hooks/webhooks, memory backend (QMD), skills registry config, UI/identity, logging, multi-agent setup, channel bindings, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.

API key resolution checks three sources in priority order: config values → ~/.openclaw/.envauth-profiles.json. All token fields handle plain strings, env templates (${VAR}), and SecretRef objects.

For the complete config key mapping, SecretRef handling details, and post-migration checklist, see the full migration guide.

Examples

# Preview what would be migrated
crewlabs claw migrate --dry-run

# Full migration (all compatible settings, no secrets)
crewlabs claw migrate --preset full

# Full migration including API keys
crewlabs claw migrate --preset full --migrate-secrets

# Migrate user data only (no secrets), overwrite conflicts
crewlabs claw migrate --preset user-data --overwrite

# Migrate from a custom OpenClaw path
crewlabs claw migrate --source /home/user/old-openclaw

crewlabs dashboard

crewlabs dashboard [options]

Launch the web dashboard — a browser-based UI for managing configuration, API keys, and monitoring sessions. Requires pip install crewlabs-agent[web] (FastAPI + Uvicorn). The embedded browser Chat tab requires --tui plus the pty extra. See Web Dashboard for full documentation.

OptionDefaultDescription
--port9119Port to run the web server on
--host127.0.0.1Bind address
--no-openDon't auto-open the browser
--tuioffEnable the in-browser Chat tab by running crewlabs --tui behind a PTY/WebSocket bridge. Requires pip install 'crewlabs-agent[web,pty]' and a POSIX PTY environment such as Linux, macOS, or WSL2.
--insecureoffAllow binding to non-localhost hosts. Exposes dashboard credentials on the network; use only behind trusted network controls.
--stopStop running crewlabs dashboard processes and exit.
--statusList running crewlabs dashboard processes and exit.
# Default — opens browser to http://127.0.0.1:9119
crewlabs dashboard

# Custom port, no browser
crewlabs dashboard --port 8080 --no-open

# Enable the browser Chat tab
crewlabs dashboard --tui

crewlabs profile

crewlabs profile <subcommand>

Manage profiles — multiple isolated Crewlabs instances, each with its own config, sessions, skills, and home directory.

SubcommandDescription
listList all profiles.
use <name>Set a sticky default profile.
create <name> [--clone] [--clone-all] [--clone-from <source>] [--no-alias]Create a new profile. --clone copies config, .env, and SOUL.md from the active profile. --clone-all copies all state. --clone-from specifies a source profile.
delete <name> [-y]Delete a profile.
show <name>Show profile details (home directory, config, etc.).
alias <name> [--remove] [--name NAME]Manage wrapper scripts for quick profile access.
rename <old> <new>Rename a profile.
export <name> [-o FILE]Export a profile to a .tar.gz archive (local backup).
import <archive> [--name NAME]Import a profile from a .tar.gz archive (local restore).
install <source> [--name N] [--alias] [--force] [-y]Install a profile distribution from a git URL or local directory.
update <name> [--force-config] [-y]Re-pull a distribution; preserves user data (memories, sessions, auth).
info <name>Show a profile's distribution manifest (version, requirements, source).

Examples:

crewlabs profile list
crewlabs profile create work --clone
crewlabs profile use work
crewlabs profile alias work --name h-work
crewlabs profile export work -o work-backup.tar.gz
crewlabs profile import work-backup.tar.gz --name restored
crewlabs profile install github.com/user/my-distro --alias
crewlabs profile update work
crewlabs -p work chat -q "Hello from work profile"

crewlabs completion

crewlabs completion [bash|zsh|fish]

Print a shell completion script to stdout. Source the output in your shell profile for tab-completion of Crewlabs commands, subcommands, and profile names.

Examples:

# Bash
crewlabs completion bash >> ~/.bashrc

# Zsh
crewlabs completion zsh >> ~/.zshrc

# Fish
crewlabs completion fish > ~/.config/fish/completions/crewlabs.fish

crewlabs update

crewlabs update [--check] [--backup] [--restart-gateway]

Pulls the latest crewlabs-agent code and reinstalls dependencies in your venv, then re-runs the post-install hooks (MCP servers, skills sync, completion install). Safe to run on a live install.

pip installs: crewlabs update detects pip-based installations automatically — it queries PyPI for the latest release and runs pip install --upgrade crewlabs-agent instead of git pull. PyPI releases track tagged versions (major/minor releases), not every commit on main. Use --check to see if a newer PyPI release is available without installing.

OptionDescription
--checkPrint the current commit and the latest origin/main commit side by side, and exit 0 if in sync or 1 if behind. Does not pull, install, or restart anything.
--backupCreate a labeled pre-update snapshot of CREWLABS_HOME (config, auth, sessions, skills, pairing data) before pulling. Default is off — the previous always-backup behavior was adding minutes to every update on large homes. Flip it on permanently via update.backup: true in config.yaml.
--restart-gatewayAfter a successful update, restart the running gateway service. Implies --all semantics if multiple profiles are installed.

Additional behavior:

  • Pairing data snapshot. Even when --backup is off, crewlabs update takes a lightweight snapshot of ~/.crewlabs/pairing/ and the Feishu comment rules before git pull. You can roll it back with crewlabs backup restore --state pre-update if a pull rewrites a file you were editing.
  • Legacy crewlabs.service warning. If Crewlabs detects a pre-rename crewlabs.service systemd unit (instead of the current crewlabs-gateway.service), it prints a one-time migration hint so you can avoid flap-loop issues.
  • Exit codes. 0 on success, 1 on pull/install/post-install errors, 2 on unexpected working-tree changes that block git pull.

Maintenance commands

CommandDescription
crewlabs versionPrint version information.
crewlabs updatePull latest changes and reinstall dependencies.
crewlabs uninstall [--full] [--yes]Remove Crewlabs, optionally deleting all config/data.

See also