Using the CLI

The RunReveal CLI is a JSON-in/JSON-out interface to the RunReveal API. API commands accept a JSON request body and print the raw API response as JSON, which makes the CLI equally suited to interactive use, scripting, and AI agents. Human-readable status output goes to stderr, so stdout is always safe to pipe or parse.

Install the CLI

Install homebrew for macOS, then enable our homebrew tap and install the CLI:

brew tap runreveal/runreveal
brew trust --formula runreveal/runreveal/runreveal
brew install runreveal

brew install runreveal/runreveal/runreveal

Upgrading from the previous CLI

CLI versions v2026.7 and later are a new implementation. If you are upgrading from an earlier version (pre-v2026.7), here is what changed:

• Re-authenticate once. Browser-based logins are not carried over. Run runreveal auth login after upgrading.
• API tokens continue to work as before. RUNREVEAL_TOKEN and the --token flag accept the same tokens they always have, including the legacy session token formats — CI/CD pipelines need no changes.
• Auto-generated API commands moved under the runreveal api prefix. For example, runreveal sources list is now runreveal api sources list.
• The interactive logs shell was removed due to low usage. Query logs with runreveal api logs query-v3 instead.
• runreveal auth status replaces runreveal config show.
• runreveal openapi was removed. API documentation is available in the API reference.
• The RUNREVEAL_APPBASEURL and RUNREVEAL_HEADER_FILE environment variables are no longer used.

Login to RunReveal

Authenticate with your browser:

runreveal auth login

runreveal init and runreveal login are aliases for the same flow. This opens your browser to authorize the CLI and stores the resulting token in your OS keychain, falling back to ~/.config/runreveal/ when no keychain is available.

To use a manually-created API token instead:

runreveal auth token

Validate that you're logged in:

runreveal auth status

{
  "profile": "default",
  "base_url": "https://api.runreveal.com",
  "workspace": "2KUOdUOFyuTbPD7amU3WidyfOzf",
  "token": "abcd1234...",
  "logged_in": true,
  "auth_method": "oauth"
}

Profiles

Profiles let you switch between workspaces or deployments (for example, RunReveal Cloud and an on-prem instance). A profile is created by logging in to it — runreveal auth login --profile staging --base-url URL — and non-secret profile settings live in ~/.config/runreveal/profiles.toml.

runreveal auth profile list          # list profiles (active field marks the current one)
runreveal auth profile use NAME      # switch the active profile (persistent)
runreveal auth profile env NAME      # print shell exports for one-off use with eval
runreveal auth profile delete NAME   # delete a profile (asks for confirmation; -f skips)

Environment Variables

Settings are resolved in this order (highest priority first): CLI flags (--token, --base-url, --workspace, --profile), environment variables, then the active profile.

RUNREVEAL_TOKEN

Authenticates the CLI without runreveal auth login. When set, profiles and the keychain are not consulted at all. This is the recommended approach for CI/CD and other non-interactive environments because API tokens are long-lived and do not require a browser flow.

RUNREVEAL_WORKSPACE

Sets the active workspace for the session. This ID must be a workspace ID, not the name of your workspace.

RUNREVEAL_PROFILE

Selects a named profile for the current invocation. This is equivalent to passing --profile <name> on the command line and overrides the current profile stored in profiles.toml. Useful in environments that manage credentials for multiple workspaces:

export RUNREVEAL_PROFILE=production
runreveal detections sync -d ./detections

RUNREVEAL_BASEURL

For customers who have deployed the RunReveal API on-prem or in a private cloud, you can set the RUNREVEAL_BASEURL environment variable to point the CLI to your RunReveal API instance.

RunReveal Cloud:

export RUNREVEAL_BASEURL=https://api.runreveal.com

Custom/On-Prem Instances:

export RUNREVEAL_BASEURL="https://api.YOUR_BASE_DOMAIN.runreveal.com"

RUNREVEAL_DEBUG

Enables debug logging and prints the HTTP requests the CLI sends to the RunReveal API (as curl commands), which is helpful when troubleshooting.

export RUNREVEAL_DEBUG=1

API Commands

Every RunReveal API endpoint is available under the api group, organized by resource:

runreveal api <group> <command> [--json '<body>']

The request body can be supplied with --json/-j or piped on stdin. If neither is provided, an empty object is sent, which suits GET/LIST endpoints.

# List sources
runreveal api sources list
 
# Query your logs
echo '{"query":"SELECT * FROM logs LIMIT 10"}' | runreveal api logs query-v3
 
# Create a source
runreveal api sources create --json '{"name":"my-source","type":"structured-webhook","ingestType":"webhook"}'

Available groups include account, agents, alerts, custom-views, destinations, detections, enrichments, filters, investigations, logs, managed-detections, notifications, pipelines, saved-queries, sources, topics, transforms, user, and workspace. Discover the full list and each group's commands with:

runreveal api --help
runreveal api sources --help

Detections as Code

Curated commands for managing detections in a git repository:

runreveal detections export -d ./detections   # export workspace detections to files
runreveal lint sigma ./detections             # lint Sigma rules
runreveal lint sql ./detections               # lint SQL detections
runreveal detections test -f FILE             # run a SQL detection over a time range
runreveal detections run -f FILE -i EVENTS    # run a Sigma detection against sample events
runreveal detections sync -d ./detections     # upload local detections

See Detections as Code for the full workflow.

MCP Server

runreveal mcp

Starts a local Model Context Protocol server over stdio, exposing RunReveal tools to Claude, Cursor, and other MCP clients. It uses the same credential resolution as the rest of the CLI. See Model Context Protocol for setup.

Interactive Agent Chat

runreveal agent

Starts an interactive, terminal-based chat with RunReveal's AI assistant, streaming responses the same way the in-app Native AI Chat does—it talks to the same backend, so chats started in one place can be picked up in the other.

Flags:

• --provider — LLM provider to use: anthropic (default), openai, googleai, bedrock, vertex, or ollama. The provider must be configured for your workspace (see Native AI Chat setup).
• --model — model name to use (e.g. claude-sonnet-4-6). Defaults to the provider's configured default.
• --chat-id — resume an existing chat by ID instead of starting a new one.

Agent Skill

The CLI can describe itself to AI agents:

mkdir -p .claude/skills/runreveal
runreveal skill > .claude/skills/runreveal/SKILL.md

runreveal skill prints a ready-to-use agent skill in markdown covering authentication, the JSON command pattern, and the detections workflow.

Shell Completion

Homebrew installs completions for bash, zsh, and fish automatically. To generate them manually:

runreveal completion zsh   # or bash, fish