CLI reference

Everything in Ravi is a ravi command: you, your agents and the SDK all use the same CLI. This page shows you how to look up any command, what --json, exit codes and --execute mean, and what each of the 80-odd command groups is for. Flags and arguments live in --help, which is always current.

Find a command

ravi --help                      # every root command, plus the live runtime context
ravi sessions --help             # the subcommands of one group
ravi sessions send --help        # arguments, flags and defaults of one command
ravi tools search "send media"   # search commands by intent

Many commands print more than flags: USE, DO NOT USE, EXAMPLES and ON ERROR sections that say when to pick that command and what to do when it fails. Read them before running something unfamiliar. Most groups also have a skill: a longer guide written for agents, which you can read too. Most are written in Portuguese.

ravi skills list                                   # every system skill
ravi skills show pages                             # the full guide for one area
ravi skills show pages --file references/<file>    # one reference file of a skill
ravi skills show pages --file references/<file> --raw > out.txt   # copy a file as-is

ravi skills show lists the skill’s reference files at the end of its output. See Skills.

Conventions

Output

Add --json to get a machine-readable result on stdout. Use it in scripts instead of parsing the text output.

With --json, a failure is also JSON on stdout, never plain text:

{
  "success": false,
  "op": "settings delete",
  "error": {
    "code": "SETTING_NOT_FOUND",
    "message": "Setting not found: defaultTimezone",
    "retryable": false,
    "suggestedAction": "Check the setting key (see suggestions) or run `ravi settings list`"
  }
}

List commands accept --limit and --offset, and many accept --fields a,b,c to keep only some fields.

Exit codes

Code	Meaning
`0`	Success.
`1`	The command ran and failed: not found, provider error, permission denied.
`2`	Usage error or refused input: unknown flag, bad argument, or a combination the command refuses. The JSON error lists the accepted flags.
`3`	Blocked by policy, not an error. Usually a dry-run: a braked command printed its plan and wrote nothing. `connectors` and `gmail` also exit `3` when a rule stops the call, for example a write waiting for the account owner’s approval.

Braked vs immediate

Commands whose effect is irreversible, visible outside your machine, or that start an agent run are braked. Without --execute they print the planned input, write nothing and exit 3. Run them again with --execute to do it.

ravi sessions delete <nameOrKey> --execute   # deletes a session permanently
ravi sessions reset <nameOrKey> --execute    # clears a session's context
ravi cron run <id> --execute                 # runs a scheduled job now
ravi triggers test <id> --execute            # fires a trigger with fake event data
ravi media send <filePath> --execute         # sends a file to a chat
ravi agents permissions main full-access --execute   # raises an agent's permission ceiling
ravi heartbeat trigger <id> --execute        # queues a heartbeat run

Some brakes are conditional. ravi heartbeat trigger is braked only when the agent’s HEARTBEAT.md has content; with no file or an empty file it does nothing and says so. ravi agents permissions is braked only when the new profile grants more than the current one. ravi pages visibility is braked only when switching to public. Reversible changes run immediately, with no --execute, even demoting a WhatsApp group admin:

ravi contacts block <contact>
ravi instances delete <name>
ravi instances routes remove <name> <pattern>
ravi whatsapp group demote <groupId> <participants>

ravi instances delete and ravi instances routes remove are soft deletes: ravi instances deleted and ravi instances routes deleted list what was removed, and ravi instances restore and ravi instances routes restore bring it back. ravi contacts tag is immediate too, including the permission-owner tag, which grants full authority to an allowed contact (see Make yourself the owner). ravi pages ship publishes in one call; a leftover --execute on it is ignored. When unsure, run the command without --execute first. If it is braked, you get the plan and exit 3.

Console-scoped commands

Commands that work with the Ravi Console (pages, bases, connectors, gmail, bridges, bug, feedback, projects) need ravi login first; without it they fail with AUTH_REQUIRED. Commands that act on a Console project take --project <ref>, a project id or slug. ravi pages and ravi bases fall back to a saved default project when you omit it:

ravi cloud scope set --global --project <ref>   # default project for this install
ravi cloud scope show                           # what the next command will use
ravi bases list --project <ref>                 # one-off override

ravi cloud scope set also takes --agent, --session or --workspace instead of --global. See Log in to the Console. connectors and gmail do not use a project: a connection belongs to the person who connected it. --project on connectors is ignored with a warning. Writes such as ravi gmail send --execute ask the account owner first; after they approve, the same command runs again with --approval <id>. ravi connectors mode <agent> google shows whose account an agent uses (yours, the person asking’s, or a shared one); switching away from yours needs --execute. See Connect your accounts.

Who runs the command

Commands you type in your own shell run as the local operator, with full authority. The same commands run by an agent are checked against that agent’s permissions, and a denial is published on ravi.audit.denied. See Permissions. Some commands that change agents, instances and routes refuse to run when the ravi you call is a different build from the running daemon (CLI/runtime mismatch detected). Use the same install the daemon runs, or restart the daemon after an update.

Command map

Each line is one root command. Run ravi <group> --help for its subcommands.

Install and operate

Command	What it is for
`setup`	Interactive first-run wizard (PM2, Omni, `~/.ravi/.env`, daemon).
`update`	Update the CLI to an exact release or switch channel (`--next`, `--stable`); restarts the Ravi processes.
`doctor`	Check runtime, database, provider and contract health.
`daemon`	Start, stop, restart, inspect and log the `ravi` daemon under PM2; edit `~/.ravi/.env`.
`channels`	Configure native channels (Slack) and run the `ravi-channels` runner.
`settings`	Global settings stored in `ravi.db`.
`events`	Stream live NATS events or replay persisted ones.
`db`	Inspect `ravi.db` locks, WAL and holders.
`adapters`	Inspect session adapters and their debug snapshots.
`costs`	Token and cost tracking per agent and session.
`metrics`	Daily metrics rollup and reports.
`service`	Start the bot server directly (`service wa` is deprecated; use `daemon start`).
`stream`	Run the JSONL stdio stream server.

Agents, sessions and runtime

Command	What it is for
`agents`	Create agents, set properties, permission profiles, debounce, reset sessions.
`sessions`	List, send to, ask, inform, trace, reset and delete sessions.
`self`	Read the current agent, session, chat and permissions (inside an agent turn).
`runtime`	Model providers (`claude`, `codex`, `pi`, `grok`), credential pools, presets and allowlisted `.env` keys.
`context`	Runtime context keys: issue, list, check, revoke.
`permissions`	Inspect and grant runtime authorization: `status`, `check`, `allow`, `deny`, `list`, `resolve`, `materialize`.
`skills`	List, show, install and grant skills.
`skill-gates`	Rules that make a tool or command load a required skill first.
`commands`	Prompt commands: list, validate and render.
`rules`	Import provider prompt rules into `.ravi/rules`.
`hooks`	Runtime hooks on session events (start, tool use, stop) that inject context or send events.
`tools`	List, search and inspect the CLI as agent tools.
`tasks`	Tracked work dispatched to agents, with progress, done, block and fail.
`jobs`	Run a long command in the background and deliver the result to the session.
`threads`	Ravi-owned threads with comments, notes and handoff briefs.
`sandbox`	Run one task in a disposable E2B cloud sandbox and collect its patch.

Channels, people and routing

Command	What it is for
`instances`	Channel accounts: create, connect (WhatsApp QR), policies, pending approvals, routes.
`routes`	Read-only view of routes and of which route wins for a chat.
`contacts`	People: add, approve, block, tag, link identities, find.
`chats`	Canonical chats, their messages and reading queues.
`slack`	Native Slack operations: channels, messages, Block Kit, modals, Canvas, topology.
`whatsapp`	WhatsApp group and DM operations through Omni (`group`, `dm`).
`credentials`	The credential broker: provider connections (Slack tokens) and policies.
`react`	Send an emoji reaction to a message.
`media`	Send a file to a chat.
`stickers`	Sticker library and sending.
`crm`	Contacts, accounts, opportunities and pipelines.

Automation

Command	What it is for
`cron`	Scheduled prompts and jobs.
`heartbeat`	Proactive runs driven by an agent’s `HEARTBEAT.md`.
`triggers`	Run an agent prompt when a NATS event matches. `ravi triggers topics` lists known topics.
`watch`	Watches on external sources, wired to triggers.
`workflows`	Workflow specs and runs.
`observers`	Observation Plane bindings, profiles and rules.
`tags`	Unified tags for Ravi assets.
`tag-rules`	Deterministic tag classification rules.

Ravi Console

Command	What it is for
`login`	Link this CLI to the Console (default `https://console.ravi.bot`).
`whoami`	Show the linked Console identity.
`logout`	Remove the local Console credentials and revoke them when possible.
`link` / `unlink`	Bind the current contact to the active Console user, from inside an agent turn.
`cloud`	Console projects and the default organization/project scope.
`pages`	Publish pages to your project host (`ravi pages ship`), visibility, passwords, domains.
`bases`	Typed project tables: schema, rows, views, charts, row-event subscriptions.
`artifacts`	Artifact ledger and lineage; `artifacts publish` is the advanced upload behind Pages.
`connectors`	Connect your own accounts (Gmail, Calendar, …) through the Console.
`bridges`	MCP bridges managed through the Console.
`inbox`	Local inbox and the Console agent-inbox poller.
`sync`	Local-first sync outbox and inbox with the Console.
`bug`	File and follow Ravi bug reports.
`feedback`	Send structured feedback.

Media, content and integrations

Command	What it is for
`audio`	Text-to-speech generation.
`transcribe`	Transcribe an audio file.
`image`	Image generation.
`video`	Video analysis.
`meetings`	Meeting artifacts, cloud meeting bots, and reading a Console meeting’s transcript (`meetings read`).
`mail`	Local-first mail accounts, mailboxes, threads and sending.
`calendars`	Local-first calendars and availability.
`gmail`	Your Gmail, through your connected Google account.
`yt`	YouTube Data and Analytics APIs.
`insights`	Operational insights with lineage.
`specs`	Versioned specs under `.ravi/specs`.
`projects`	Project context, resources, tasks and workflows.
`apps`	Discover, validate and run Ravi app manifests.
`work-objects`	Resolve and act on Work Objects through domain adapters.
`devin`	Devin authentication and remote sessions.
`prox`	Voice follow-up calls for prox.city.
`sdk`	SDK code generation (TypeScript, Swift, Dart) and the OpenAPI snapshot.

SDKs and HTTP gateway: the same commands over HTTP.
Events: the topics commands and agents publish.
Troubleshooting: ravi doctor, logs and traces.

CLI

System

Tools

CLI reference

Find a command

Conventions

Output

Exit codes

Braked vs immediate

Console-scoped commands

Who runs the command

Command map

Install and operate

Agents, sessions and runtime

Channels, people and routing

Automation

Ravi Console

Media, content and integrations

​Find a command

​Conventions

​Output

​Exit codes

​Braked vs immediate

​Console-scoped commands

​Who runs the command

​Command map

​Install and operate

​Agents, sessions and runtime

​Channels, people and routing

​Automation

​Ravi Console

​Media, content and integrations

​Related

Find a command

Conventions

Output

Exit codes

Braked vs immediate

Console-scoped commands

Who runs the command

Command map

Install and operate

Agents, sessions and runtime

Channels, people and routing

Automation

Ravi Console

Media, content and integrations

Related