{
  "markdown": "# Vulcan\n\nAgent and human-friendly CLI for trading perpetual futures on [Phoenix](https://phoenix.trade).\n\n> ⚠️ **Experimental software:** live commands can execute irreversible financial transactions on Solana Mainnet. You are responsible for wallet security, agent permissions, and all trading outcomes.\n\n## What Vulcan Provides\n\n- Account, margin, position, and order management for Phoenix perps.\n- Local paper trading with live market prices and no wallet required.\n- A local MCP server so agents can use Vulcan tools directly.\n- First-class strategy runners for TWAP, grid trading, and TA.\n- Bundled Agent Skills for Cursor, Claude Code, Codex, and Agentskills/OpenClaw-style clients.\n\n### Example Agent Prompts\n\n> \"Give me a full portfolio snapshot: cross + isolated margin health, open positions with unrealized PnL %, resting orders, and any funding exposure I should know about.\"\n>\n> \"Scan the top 5 markets on Phoenix by 24h volume — give me funding rate, mark price, and a one-line take on each.\"\n>\n> \"Open a $200 long on SOL then attach a TP at +5% and SL at -3%.\"\n>\n> \"I need to long $5,000 of SOL. Run a TWAP over 20 minutes in 10 slices.\n>\n> \"Watch BTC on 15m and alert me when EMA(9) crosses EMA(21), paper only\"\n>\n> \"Build a TA strategy that goes long when RSI(14) crosses above 30 on the 5m and exits when it crosses 70. Paper mode first, $500 per entry\"\n\n## Install\n\nInstall the latest release on macOS/Linux:\n\n```bash\ncurl -fsSL https://github.com/Ellipsis-Labs/vulcan-cli/releases/latest/download/install.sh | sh\n```\n\nThe installer verifies the release archive against `vulcan-checksums-sha256.txt` and installs to `~/.local/bin/vulcan` by default. Make sure `~/.local/bin` is on your `PATH`.\n\nInstall a specific version:\n\n```bash\ncurl -fsSL https://github.com/Ellipsis-Labs/vulcan-cli/releases/download/v0.5.3/install.sh | sh\n```\n\nBuild from source:\n\n```bash\ncargo install --path vulcan\n```\n\nVerify:\n\n```bash\nvulcan version\n```\n\nCheck for newer releases:\n\n```bash\nvulcan update check\n```\n\nThis is read-only — vulcan never modifies its own binary. When an update is available it prints a method-appropriate hint: re-run the install one-liner above for default or custom `~/.local/bin`-style installs, or use your package manager for Homebrew/Nix/distro installs. Agents that load `vulcan://agent/health` see the same information under `cli_update`.\n\n## Quick Start\n\n```bash\n# Guided setup for config, wallet, registration, deposit, and agent options\nvulcan setup\n\n# Check installation, config, wallet, RPC/API, registration, and paper readiness\nvulcan status -o json\n\n# Read market data\nvulcan market list -o json\nvulcan market ticker SOL -o json\n\n# Begin paper trading\nvulcan paper init --balance 10000 -o json\nvulcan paper buy SOL --notional-usdc 100 --type market -o json\nvulcan paper status -o json\n```\n\n## Agent Setup\n\nVulcan installs a local MCP server and a bundled set of Agent Skills into your agent host (Claude Code, Cursor, Codex, or any agentskills-compatible client). Two commands per host: one to install the skill files, one to register the MCP server. Live trading is opt-in.\n\nSupported `--target` values: `claude`, `cursor`, `codex`, `agentskills`. `--scope user` writes to your user-level config (default); `--scope project` writes to the current project.\n\n### Step 1: Install skills + MCP server (read-only / paper-safe)\n\n```bash\n# Bundled Agent Skills (workflow guides, recipes, runtime contract)\nvulcan agent install --target claude --scope user\n\n# Register the Vulcan MCP server with the host's standard config file\nvulcan agent mcp install --target claude --scope user\n\n# End-to-end probe: spawn the server, handshake, assert vulcan_* tools appear\nvulcan agent mcp diagnose --target claude --scope user\n```\n\n**Fully restart your host** afterward so it picks up the new MCP server.\n\n### Step 2 (optional): Enable live trading\n\nLive trading requires a stored wallet to unlock for signing and live signing permission. You can setup at install time with `--dangerous`\n\n```bash\n# Wire up the wallet for live signing.\n# Prompts for the wallet password interactively, validates decryption\nvulcan agent mcp install --target claude --scope user --dangerous\n```\n\nAfter restart, dangerous tools (live trades, deposits, withdrawals, cancellations) appear in the agent's tool list and can be invoked with `acknowledged: true`.\n\n> ⚠️ Both flows write your wallet password into the host's MCP config file on disk. The file is created `chmod 0600` — protect it like any other credential file.\n\n### Switching wallets later\n\n```bash\nvulcan agent mcp set-wallet <wallet-name> --target claude --scope user\n```\n\n### Inspecting and repairing\n\n```bash\n# Show what's installed and what's missing per host\nvulcan agent mcp doctor --target claude --scope user\n\n# Reinstall command path / args while preserving the wallet password env\nvulcan agent mcp install --target claude --scope user --repair\n\n# Combined readiness check across all configured hosts\nvulcan strategy preflight\n```\n\n### Running MCP standalone\n\nFor local testing or custom orchestration without a host:\n\n```bash\n# Read-only / paper-safe\nvulcan mcp\n\n# Live-capable\nexport VULCAN_WALLET_NAME=my-wallet\nexport VULCAN_WALLET_PASSWORD=your-password\nvulcan mcp --allow-dangerous\n```\n\n`VULCAN_WALLET_NAME` selects a stored wallet; if omitted, Vulcan uses the default wallet. `VULCAN_WALLET_PASSWORD` is required when `--allow-dangerous` is set; empty strings are treated as unset.\n\nDangerous tools require both:\n\n1. MCP server started with `--allow-dangerous`.\n2. `acknowledged: true` on each dangerous tool call.\n\n### Agent context, skills, and catalogs\n\n- `vulcan://context` or `vulcan agent-context` — canonical runtime contract.\n- `vulcan://skills/index` or `skills/INDEX.md` — workflow skill index.\n- `vulcan://agents/tool-catalog` or `agents/tool-catalog.json` — exact tool schemas.\n- `vulcan://agents/error-catalog` or `agents/error-catalog.json` — error codes and recovery hints.\n\nPlaintext private-key export is user-only. Agents should explain the risk and provide the command for the user to run locally, but should not execute it.\n\nSee `AGENTS.md` for full integration details.\n\n## Command Groups\n\n\n| Group           | Purpose                                                                                   |\n| --------------- | ----------------------------------------------------------------------------------------- |\n| `setup`         | Interactive setup wizard for config, wallet, registration, deposits, and agent setup.     |\n| `status`        | Health check for config, wallet, RPC, API, registration, and balances.                    |\n| `market`        | Market list, ticker, market info, orderbook, and candles.                                 |\n| `paper`         | Local paper trading with live prices and no real funds.                                   |\n| `trade`         | Place and manage live orders, cancellations, multi-limit orders, and TP/SL.               |\n| `position`      | List, show, close, reduce, and attach TP/SL to positions.                                 |\n| `margin`        | Deposit, withdraw, transfer collateral, add isolated collateral, and view leverage tiers. |\n| `portfolio`     | Combined margin, positions, and orders snapshot.                                          |\n| `strategy`      | TWAP, grid, and TA runners, status, monitor, pause, stop, resume, finalize, and reports.  |\n| `ta`            | Technical analysis — compute indicators, evaluate triggers, and multi-indicator reports.  |\n| `history`       | Trader history for trades, orders, collateral, funding, and PnL.                          |\n| `wallet`        | Create, import, export encrypted backups, list, select, and inspect wallets.              |\n| `account`       | Account info and registration.                                                            |\n| `auth`          | Phoenix API wallet-session login, status, and logout.                                     |\n| `agent`         | Install, inspect, and repair Agent Skills and MCP config.                                 |\n| `mcp`           | Start the local MCP server.                                                               |\n| `agent-context` | Print the runtime contract for agents.                                                    |\n| `version`       | Print version and build information.                                                      |\n\n\nAll commands support JSON output with `-o json`:\n\n```json\n{ \"ok\": true, \"data\": { }, \"meta\": { } }\n{ \"ok\": false, \"error\": { \"category\": \"...\", \"code\": \"...\", \"message\": \"...\", \"retryable\": false } }\n```\n\n### Global Flags\n\nAvailable on every command:\n\n\n| Flag            | Purpose                                               |\n| --------------- | ----------------------------------------------------- |\n| `-o, --output`  | `json` or `table` (default `table`).                  |\n| `-w, --wallet`  | Use a specific stored wallet instead of the default.  |\n| `--dry-run`     | Simulate the action without submitting a transaction. |\n| `-y, --yes`     | Skip interactive confirmation prompts.                |\n| `--watch`       | Stream live updates via WebSocket where supported.    |\n| `-v, --verbose` | Verbose/debug logging to stderr.                      |\n| `--rpc-url`     | Override the Solana RPC endpoint.                     |\n| `--api-url`     | Override the Phoenix API endpoint.                    |\n\n\n## Strategies\n\nUse first-class runners when Vulcan provides the strategy. Runners own the loop, perform launch-time checks for live modes, persist structured tick logs and ledgers under `~/.vulcan/strategy-runs`, and produce status/report output.\n\nSupported runners:\n\n- TWAP: split a larger order into timed slices.\n- Grid: maintain layered limit orders across a price range.\n- TA: rule-based runner over technical indicators for entry/exit.\n\nModes:\n\n- `paper` - local simulation against live prices.\n- `dry_run` - plan intended live actions without submitting transactions.\n- `confirm_each` - live mode with confirmation before each execution step.\n- `auto_execute` - live mode after explicit approval for the configured parameters.\n\nExamples:\n\n```bash\nvulcan strategy twap start --symbol SOL --side buy --notional-usdc 1000 --slices 5 --interval-seconds 30 --mode paper -o json\nvulcan strategy runs -o json\nvulcan strategy monitor <RUN_ID> -o json\nvulcan strategy finalize <RUN_ID> --cancel-orders --wait --yes -o json\n```\n\nFor agent-specific strategy behavior, see `CONTEXT.md`, `skills/vulcan-twap-execution/SKILL.md`, and `skills/vulcan-grid-trading/SKILL.md`.\n\n## Development\n\nPrerequisites:\n\n- Rust 1.84+\n- Phoenix Rise SDK dependency from crates.io\n\n```bash\ncargo build\ncargo test\ncargo run -- --help\ncargo run -- market ticker SOL -o json\n```\n\nProject layout:\n\n```text\nvulcan/           # Binary crate and CLI entry point\nvulcan-lib/       # Library crate with commands, MCP, wallet, config, output, and errors\nagents/           # Tool/error catalogs and fallback agent prompt\nskills/           # Bundled Agent Skills (markdown)\nCONTEXT.md        # Canonical runtime contract for agents\nAGENTS.md         # MCP/client integration guide\nCLAUDE.md         # Contributor guide\n```\n\n",
  "bytes": 11236,
  "sha": "65301b11cf7978756bdccc71ebdad077b2aad4578ab6fcb9ac9caa3f19eaf4d3",
  "repo_slug": "ellipsis-labs/vulcan-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ellipsis_labs_vulcan_cli_vulcan_82c2951f/readme"
}