CLI

v1 status: hand-written from src/main.rs command enum. Will be generated from --help output once a generator script lands. The canonical reference in the upstream repo is docs/commands-reference.md.

Global flags

These work on every subcommand:

Flag	Effect
`--profile <name>`	Operate on the named profile (default: `default`)
`--config-dir <path>`	Override the config directory (overrides `RANTAICLAW_CONFIG_DIR`)

Top-level commands

Command	Purpose
`rantaiclaw onboard`	Original interactive setup wizard (kept for backward compat)
`rantaiclaw setup`	Canonical interactive setup; single-section topics like `setup mcp`, `setup knowledge`, etc.
`rantaiclaw autonomy [<preset>]`	Show or switch the approval-policy preset; writes the three `policy/*.toml` files and mirrors `[autonomy].level` / `[autonomy].allowed_commands` into `config.toml`
`rantaiclaw agent`	Run an agent — interactive REPL (no flag) or one-shot (`--message`)
`rantaiclaw chat`	Launch the terminal UI (TUI) — requires the `tui` feature
`rantaiclaw ui <subcommand>`	Install / run the optional web console (claw-ui); fetched on demand, needs a JS runtime
`rantaiclaw daemon`	Production daemon — gateway + all channels + scheduler + heartbeat
`rantaiclaw gateway [--port P] [--host H]`	Run only the gateway HTTP server (no channels)
`rantaiclaw service [--service-init auto\|systemd\|openrc] <sub>`	Manage the user-level OS service (`install`/`start`/`stop`/`restart`/`status`/`uninstall`)
`rantaiclaw doctor [--format text\|json\|brief] [--brief] [--offline]`	Run diagnostics (config + live + system); `doctor models` probes provider catalogs
`rantaiclaw status`	Print runtime status
`rantaiclaw config schema`	Export the config JSON Schema (no other subcommands today)
`rantaiclaw memory <subcommand>`	List, get, stats, clear memory entries
`rantaiclaw kb <subcommand>`	Knowledge Base CRUD + maintenance (built in by default; `kb` feature)
`rantaiclaw skills <subcommand>`	List, show, install, remove skills (note: plural `skills`)
`rantaiclaw cron <subcommand>`	Manage cron jobs
`rantaiclaw models refresh [--provider] [--force]`	Refresh cached provider model catalogs (only `refresh` exists)
`rantaiclaw providers`	List configured providers
`rantaiclaw channel <subcommand>`	Channel management (aliased `channels`)
`rantaiclaw permissions <subcommand>`	Per-role channel permissions (owners + the non-owner “guest” ceiling)
`rantaiclaw integrations`	External service integrations
`rantaiclaw migrate`	Run profile / config migrations
`rantaiclaw auth <subcommand>`	OAuth flows, device-code logins (Codex, Anthropic subscription, etc.)
`rantaiclaw hardware`	Hardware discovery
`rantaiclaw peripheral <subcommand>`	Hardware peripherals (STM32, RPi GPIO, ESP32, Arduino)
`rantaiclaw session <subcommand>`	Inspect / manage sessions
`rantaiclaw insights`	Show insights from session data
`rantaiclaw personality`	Manage active persona
`rantaiclaw profile <subcommand>`	Multi-profile management
`rantaiclaw update`	Self-update (replace the binary)
`rantaiclaw rollback`	Restore the previously installed binary from the snapshot saved by `update`
`rantaiclaw uninstall`	Remove the agent and (optionally) its data
`rantaiclaw completions <shell>`	Print shell completion script

For exact flag names and behavior, run rantaiclaw <command> --help.

rantaiclaw service manages a user-level unit; --service-init selects the init system — auto (detect), systemd, or openrc (validated in src/main.rs). Since v0.6.92, service start restarts an already-running unit instead of being a silent no-op, so a config/channel change takes effect without a manual restart.

Notable absences

You may have seen these documented elsewhere. They do not exist as top-level commands today:

Not a command	What you may want instead
`rantaiclaw run`	Use `rantaiclaw daemon`
`rantaiclaw mcp`	MCP setup goes through `rantaiclaw setup mcp`
`rantaiclaw secret`	Secrets are managed via `rantaiclaw setup` (encrypted inline as `enc2:<hex>` in `config.toml`)
`rantaiclaw skill` (singular)	The CLI is plural: `rantaiclaw skills`
`rantaiclaw config show`	No such verb — open `config.toml` directly
`rantaiclaw config validate`	Use `rantaiclaw doctor`
`rantaiclaw cron run` / `cron runs`	These are LLM-callable tool names, not CLI verbs

Common usage


# First time
rantaiclaw setup
rantaiclaw doctor
rantaiclaw chat
 
# Production
rantaiclaw daemon
 
# Debugging a profile
rantaiclaw --profile work doctor
rantaiclaw --profile work memory stats
 
# Adding a skill
rantaiclaw skills install https://github.com/example/my-skill.git
rantaiclaw skills list
 
# Switching profiles
rantaiclaw profile list
rantaiclaw profile use work

Subcommand surface (selected)

`rantaiclaw setup`


setup                       # full wizard; walks every wired section, skips already-configured
setup --force               # re-run every section
setup --non-interactive     # emit each section's headless hint and exit (also implied in non-TTY)
setup <topic>               # re-run a single section
setup <topic> --force

Wired sections (each is also a valid <topic>): provider, approvals, channels, persona, skills, mcp, and — because the kb feature is on by default — knowledge (defined in src/onboard/wizard.rs).


setup provider              # re-run the provider section only
setup channels              # re-run the channels section only
setup knowledge             # set the encrypted Knowledge Base API keys (v0.7.0)
setup whatsapp-web --non-interactive   # headless WhatsApp Web QR pairing

setup knowledge writes the encrypted [knowledge] block (embedding_api_key / vision_api_key, stored as enc2:<hex>; vision falls back to the embedding key). Env KB_EMBEDDING_API_KEY / KB_EXTRACT_VISION_API_KEY override config at load, with OPENROUTER_API_KEY as the final fallback. See the Knowledge Base configuration page.

onboard is a legacy alias for setup and keeps the older quick-mode flags (--api-key, --provider, --model, --memory, --channels-only, --interactive, --force).

`rantaiclaw memory`


memory list [--category core|daily|conversation|<custom>] [--session <id>] [--limit N] [--offset N]
memory get <key>
memory stats
memory clear [--category <c>] [--session <id>] [--key <k>] [--yes]

`rantaiclaw skills`


skills list
skills show <name>
skills install <git-url-or-local-path>
skills install-deps <name>     # run the skill's brew / npm / uv / go / download recipes
skills update <name>           # git-pull a skill installed from a URL
skills inspect <name>          # dump the parsed SKILL.toml / SKILL.md
skills remove <name>

`rantaiclaw cron`


cron list
cron add <expression> [--tz <IANA_TZ>] <command>   # 5-field cron; command is a positional, no name
cron add-at <rfc3339-timestamp> <command>          # one-shot at an RFC 3339 time
cron add-every <every_ms> <command>                # fixed interval in MILLISECONDS (e.g. 60000)
cron once <delay> <command>                         # one-shot delay, e.g. "30m", "2h", "1d"
cron remove <id>
cron update <id> [--expression <expr>] [--tz <tz>] [--command <cmd>] [--name <name>]
cron pause <id>
cron resume <id>

Examples:


cron add '0 9 * * 1-5' 'Good morning' --tz America/New_York
cron add-at 2026-01-15T14:00:00Z 'Send reminder'
cron add-every 60000 'Ping heartbeat'
cron once 30m 'Run backup in 30 minutes'

Mutating cron actions require cron.enabled = true. cron run / cron runs are LLM-callable tool names, not CLI subcommands.

`rantaiclaw profile`


profile list
profile current
profile create <name>
profile use <name>
profile clone <src> <dst>

`rantaiclaw config`


config schema    # prints the JSON Schema (powered by schemars derive). No flags.

config show and config validate do not exist. Read config.toml directly, or run rantaiclaw doctor to validate.

`rantaiclaw auth`

OAuth and subscription-based login flows (Codex device-code, Anthropic Claude.ai subscription, etc.).

All flows take --provider as a flag (required), not a positional. --profile defaults to default.


auth login --provider <name> [--profile <name>] [--device-code]
auth paste-redirect --provider <name> [--profile <name>] [--input <url-or-code>]
auth paste-token --provider <name> [--profile <name>] [--token <tok>] [--auth-kind <authorization|api-key>]
auth setup-token --provider <name> [--profile <name>]   # alias for paste-token, interactive
auth refresh --provider <name> [--profile <name>]
auth use --provider <name> --profile <name>             # set active profile for a provider
auth logout --provider <name> [--profile <name>]
auth list                                                # list stored auth profiles
auth status                                              # active profile + token expiry

Example:


auth paste-redirect --provider openai-codex --input https://example.com/callback?code=...

`rantaiclaw channel`

Aliased rantaiclaw channels.


channel list                        # list configured channels
channel start                       # start all configured channels (foreground)
channel run                         # alias of start with a louder startup banner
channel doctor                      # health-check configured channels
channel add <type> <config-json>    # e.g. channel add telegram '{"bot_token":"...","name":"my-bot"}'
channel remove <name>
channel bind-telegram <identity>    # add a username (no '@') or numeric user ID to the allowlist
channel unbind-telegram <identity>  # remove an identity, or the '*' wildcard
channel pair [--channel telegram] [--ttl 15] [--max-uses <n>] [--no-owner]

channel pair mints a time-windowed, multi-claim pairing code into the shared store — a running channel validates it on the next /bind / /claim message, so no daemon restart is needed. --ttl is in minutes (default 15), --max-uses defaults to unlimited, and --no-owner restricts the code to chat-only /bind (no owner /claim).

Universal self-onboarding: an unenrolled sender messages /bind <code> to add themselves to the channel allowlist, or an owner sends /claim <code> to also land in approval_owners. Both are handled by the shared channel core, so the same flow works across Telegram, Discord, Slack, Lark, Mattermost, and the other multi-user channels.

`rantaiclaw permissions`

Manages the per-role permission model shared by every multi-user channel. Owners (senders in approval_owners) get the full toolset and may approve tool calls; everyone else who can chat is a guest whose turns run under a capability ceiling you set here. The CLI/console operator is always an owner.


permissions show                                # current owners + the guest ceiling
permissions add owner <identity>                # numeric Telegram ID, or username on Slack/Discord/etc
permissions add tool <tool-name>                # widen which tools guests may trigger
permissions add command '<glob>'                # guest shell-command allowlist, e.g. 'kubectl get *'
permissions add allow-command <basename>        # owner allowlist (autonomy.allowed_commands), e.g. kubectl
permissions remove <owner|tool|command|allow-command> <value>

The command target takes a shell-command glob ("kubectl get *") and governs guests. The allow-command target (added v0.6.84) takes a command basename (kubectl) and edits autonomy.allowed_commands — the commands an owner may run without an approval prompt. Basenames here, not globs.

`rantaiclaw ui`

Installs and runs the optional web console (claw-ui). It is a separate Next.js app fetched on demand into ~/.rantaiclaw/ui — not bundled in the binary, and it needs a JavaScript runtime (bun or npm).


ui install [--dir <path>] [--ref <tag-or-branch>] [--force]
ui start [--dir <path>] [--port <p>] [--gateway <url>] [--token <bearer>]
ui stop [--dir <path>]
ui path [--dir <path>]              # print the install directory

ui start serves the console on port 3939 by default. --gateway defaults to the [gateway] config (falling back to the existing .env.local), and --token is remembered in .env.local (omit to keep the existing one or $RANTAICLAW_TOKEN).


ui install
ui start --gateway http://127.0.0.1:3055 --port 3939

`rantaiclaw kb`

Knowledge Base surface, built into the default binary (the kb feature is in Cargo.toml’s default set). Output is token-efficient TOON by default; pass --json on read commands to emit JSON instead. Operations target the KB database from KB_DB_PATH (env) or the platform data dir (~/.local/share/rantaiclaw/kb.db on Linux). Exit 0 is success, 1 is an operational failure (a TOON error[...] block is printed to stdout).


kb search <query> [--top 5] [--group <id>]... [--category <c>] [--json]
kb ingest <path> [--title <t>] [--category <c>]... [--group <id>]... [--json]
kb list [--organization <id>] [--json]
kb get <id> [--json]
kb delete <id> [--hard]             # soft-delete by default; --hard removes rows permanently
kb drift [--json]                   # chunks embedded with a stale model
kb re-embed [--include-current] [--dry-run] [--batch-size 100] [--json]
kb intelligence <document-id> [--json]   # entities + relations for one document
kb graph [--group <id>] [--limit <n>] [--json]   # cross-document entity graph

Re-extracting a document’s entities/relations is HTTP-only (POST /api/v1/kb/documents/{id}/re-extract), not a CLI verb.

See the Knowledge Base reference for the full command contract, plus ingesting, search & retrieval, and document intelligence.