Ravn Skill for AI Agents

A self-contained skill that lets an AI assistant (Claude Code, Codex, or any agent that supports skills) drive your Ravn trading platform via its REST API. Generate strategies, deploy bots, run backtests, and monitor trading — all from chat.

What you get

A natural-language interface to your Ravn account:

• "Build me a strategy that buys when EMA crosses up on this market and sells at 5% profit." → AI drafts the strategy JSON, validates it against the live server schema, and saves it to your account.
• "Deploy that simulated." → bot starts in seconds.
• "How is bot X doing?" → AI summarizes status, P&L, and recent anomalies.
• "Backtest the latest version against last week's data." → backtest runs, AI reports the summary.
• "Stop the EMA bot and roll it onto v3." → bot stops, redeploys on the new version.

Requirements

• Python 3.10 or newer (no third-party packages — stdlib only).
• A Ravn instance you can reach (self-hosted or hosted).
• A Ravn account with API keys enabled on your tier.

Install

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/freakspace/ravn-cli/main/install.sh | bash

That installs the skill to ~/.claude/skills/ravn and prints the next-step commands. Re-run anytime to update — the installer pulls in place.

For Codex instead of Claude Code:

curl -fsSL https://raw.githubusercontent.com/freakspace/ravn-cli/main/install.sh | bash -s -- --codex

To a custom path:

curl -fsSL https://raw.githubusercontent.com/freakspace/ravn-cli/main/install.sh | bash -s -- --dir /path/to/install

After install, restart Claude Code (or start a new conversation) — ravn will appear in available skills.

Manual install

If you'd rather not pipe to bash:

# Claude Code:
git clone https://github.com/freakspace/ravn-cli ~/.claude/skills/ravn

# Codex:
git clone https://github.com/freakspace/ravn-cli ~/.agents/skills/ravn

# Project-local (for one project):
git clone https://github.com/freakspace/ravn-cli <project>/.claude/skills/ravn

To update a manual install: cd ~/.claude/skills/ravn && git pull.

Configure

You have two options.

By default the CLI talks to the hosted Ravn instance at https://api.ravn.gg. Self-hosting? Override with --api-url, RAVN_API_URL, or by editing the config file (see below).

Option 1 (recommended): browser sign-in

# Hosted Ravn (default):
python3 ~/.claude/skills/ravn/scripts/raven_cli.py login

# Self-hosted:
python3 ~/.claude/skills/ravn/scripts/raven_cli.py --api-url https://your.ravn.url login

# Staging:
python3 ~/.claude/skills/ravn/scripts/raven_cli.py --api-url https://dev-api.ravn.gg login

The CLI opens your browser to a Ravn consent page. Sign in, verify the confirmation code, click Approve, and a fresh API key is saved to ~/.config/ravn/config.json (mode 0600). The API URL you logged into is saved alongside the key, so subsequent commands don't need --api-url again.

Option 2: bring your own key

Generate an API key in Settings → API Keys on the web app, then export:

export RAVN_API_KEY=rvn_...                  # required
export RAVN_API_URL=https://your.ravn.url   # optional, defaults to https://api.ravn.gg

Verify

python3 ~/.claude/skills/ravn/scripts/raven_cli.py whoami

You should see your email and tier. If you get HTTP 401, re-run login (or check RAVN_API_KEY). If you get a connection error, check the API URL.

Logout

python3 ~/.claude/skills/ravn/scripts/raven_cli.py logout

Removes the local config file. The API key itself remains valid until you revoke it in Settings → API Keys.

Config file

~/.config/ravn/config.json is generated by login and holds:

{
  "api_url": "https://api.ravn.gg",
  "api_key": "rvn_...",
  "user": { ... },
  "issued_at": "2026-05-06T..."
}

Edit api_url directly to point the CLI at a different Ravn instance without re-running login — the file is just JSON, no special format.

Resolution order

The CLI resolves the API URL and key in this order, taking the first non-empty value it finds:

1. --api-url / --api-key command-line flag
2. RAVN_API_URL / RAVN_API_KEY environment variable
3. ~/.config/ravn/config.json
4. Default (https://api.ravn.gg for the URL; no default for the key)

Usage

Once installed, just ask your agent in plain language. The skill description triggers automatically when you mention strategies, bots, backtests, or trading.

Example:

Use the ravn skill. Show me my bots and pick the one that's losing the most this week.

The agent will translate that into the right CLI calls and summarize the results.

What it can do

Area	Operations
Auth / discovery	whoami, fetch live schema docs, list available signal types
Strategies	list, get, create, update (new version), rename (metadata only), delete, validate-without-saving
Bots	list, get, deploy, start, stop, redeploy, delete, rename, logs, events, bootstrap, sessions
Sessions	list, get, stop, delete, trades, orders, equity, logs
Simulations	start a real-time simulation session
Backtests	single trial or Monte Carlo against a recording or past session
Recordings	list, start, stop, delete

Run python3 scripts/raven_cli.py --help for the full command tree.

Safety defaults

• All deployments are simulated by default. Live deployment requires explicit --allow-live and explicit user approval in the conversation. The agent is instructed not to carry approval across turns.
• Destructive operations require --confirm. Deleting bots, sessions, and recordings is irreversible.
• The agent does not auto-close positions. Stranded positions or stuck pending orders are surfaced for human decision, not auto-resolved.

See references/safety.md for the full rule set.

How it works

The skill is just a folder of instructions and a single Python script:

ravn/
  SKILL.md                   # entry point — what the agent reads
  agents/openai.yaml         # Codex/OpenAI manifest
  scripts/raven_cli.py       # the API client (~700 lines, stdlib only)
  references/
    workflows.md             # end-to-end recipes
    safety.md                # trading safety rules
    troubleshooting.md       # error reference
  install.sh                 # one-liner installer (curl | bash)
  README.md                  # this file

The agent reads SKILL.md, calls raven_cli.py via Bash for each action, and reads the references on demand. There's no daemon, no MCP server, no webhook — just stdlib HTTP calls to your Ravn instance.

The CLI also exposes the server's own agent docs (docs prompt, docs signals) so the agent always works against the schema your server actually accepts, even if the schema evolves.

Self-test

Verify the CLI parses cleanly without hitting the network:

python3 scripts/raven_cli.py self-test

Limitations

• WebSocket streams (live event monitoring) are not wrapped — use bots events --hours N polling instead.
• Wallet operations (cancel order, sell position, claim winnings) are intentionally not exposed. Those are user-initiated actions; deferring to the web app prevents the agent from moving real funds without a clear UI confirmation.
• API key creation/revocation is JWT-only on the server side, so the agent can't rotate its own key. Manage keys in the web app.

License

MIT. See LICENSE if shipped, or follow the license of your distribution.