CLI reference
All commands accept --dir <path> to point at a team other than the current
directory, and --log-format <fmt> (pretty default, or json/NDJSON —
also settable via the RAVEL_LOG_FORMAT env var).
ravel create <name>
Section titled “ravel create <name>”Scaffolds a starter team: package.json (depending on @runravel/ravel,
with dev / validate / start scripts), ravel.json, a root agent.md,
one subordinate agent with its own tools.json, a
processes/hello.process.md, and a .gitignore.
ravel validate [--dir <org>]
Section titled “ravel validate [--dir <org>]”Compiles the team tree against the config schema. Prints ✗ for errors and
⚠ for warnings. Add --json for machine-readable output:
{ ok, nodes, processCount, diagnostics }. Exits 1 on error, 0 on
warnings-only.
ravel run <process-name> [options]
Section titled “ravel run <process-name> [options]”Boots the team, runs one process to completion, prints the result, exits.
| Flag | Effect |
|---|---|
--input key=value |
Pass input to the process (repeatable) |
--file <path> |
Attach a file (repeatable) |
--dry-run |
Tools skip their real handlers |
--sync |
Block for a y/N approval instead of an async proposal |
ravel chat <node-id> <message...>
Section titled “ravel chat <node-id> <message...>”Talks to one agent directly, bypassing the orchestrator. node-id is the
agent’s path in the registry — "" for the root, growth/copywriter for a
subordinate.
ravel proposals [list|approve <id>|reject <id>]
Section titled “ravel proposals [list|approve <id>|reject <id>]”Manages the deferred-approval queue. Approving one runs its matching executor action deterministically.
ravel dashboard
Section titled “ravel dashboard”A one-shot snapshot: spend, per-agent state, task counts, pending proposals.
ravel watch
Section titled “ravel watch”Boots the team and hot-reloads on changes to agent.md, tools.json, or
processes. No HTTP server — just a fast local iteration loop.
ravel serve [options]
Section titled “ravel serve [options]”Boots the team and keeps it running: an HTTP + SSE API plus the operator console, on one port.
| Flag | Default | Effect |
|---|---|---|
--port |
4317 |
|
--host |
127.0.0.1 |
Loopback-only by design — the API has no authentication |
--state-dir |
<org>/.ravel |
Where runtime state is written |
--read-only-config |
off | 403s PUT /api/files and PUT /api/secrets |
Shared flags
Section titled “Shared flags”| Flag | Applies to | Effect |
|---|---|---|
--dir <path> |
all commands | Team directory (default: cwd) |
-v, --verbose |
run, serve |
Streams the audit trail |
--log-format <fmt> |
all commands | pretty (default) or json |
Exit codes
Section titled “Exit codes”0 on success. 1 for an invalid team directory, unknown command, missing
required argument, an uncaught error, or (for serve) the port already
being in use.