Vincent CLI

Command-line interface for interacting with Vincent AI agent services. Manage secrets, wallets, Polymarket trading, Hyperliquid trading, data sources, and more — all from the terminal.

Installation

npm install -g @vincentai/cli

This installs the vincent command globally.

Quick Start

# Create an EVM wallet secret
vincent secret create --type EVM_WALLET --memo "My trading wallet"

# Check wallet address and balances
vincent wallet address
vincent wallet balances

# Create a Polymarket wallet secret (required for polymarket commands)
vincent secret create --type POLYMARKET_WALLET --memo "My prediction markets"

# Search Polymarket
vincent polymarket markets --query "election"

# Place a bet
vincent polymarket bet --token-id <TOKEN_ID> --side BUY --amount 10

When you create a secret, the CLI stores the API key locally in ~/.openclaw/credentials/ so subsequent commands can auto-discover it. If you have multiple keys of the same type, use --key-id <ID> to specify which one.

Configuration

| Variable | Default | Description | |---|---|---| | VINCENT_BASE_URL | https://heyvincent.ai | Override the API base URL | | OPENCLAW_STATE_DIR | ~/.openclaw | Override the local credentials directory |

Usage

vincent <group> <command> [options]

Every command supports --help to show usage and available flags.

vincent --help                    # List all groups and commands
vincent wallet --help             # List wallet commands
vincent wallet transfer --help    # Show transfer flags

Commands

secret — Secret Management

Create and manage secrets (wallets, signers, data sources). Secrets are stored server-side; the CLI stores the API key locally for reuse.

| Command | Description | Key Flags | |---|---|---| | secret create | Create a new secret | --type (required), --memo (required), --chain-id | | secret list | List stored secrets | --type | | secret relink | Re-link a secret using a relink token | --token (required) | | secret env | Write a secret value to a .env file | --env-var (required), --path, --key-id, --field |

Secret types: EVM_WALLET, POLYMARKET_WALLET, HYPERLIQUID_WALLET, RAW_SIGNER, API_KEY, SSH_KEY, OAUTH_TOKEN, CREDENTIALS, DATA_SOURCES

# Create a Polymarket wallet
vincent secret create --type POLYMARKET_WALLET --memo "Prediction markets"

# Create a credentials secret
vincent secret create --type CREDENTIALS --memo "My service credentials"

# List all secrets
vincent secret list

# List only data source secrets
vincent secret list --type DATA_SOURCES

# Write a credential value to a .env file (value never printed to stdout)
vincent secret env --key-id <KEY_ID> --env-var SERVICE_PASSWORD --field password

# Write to a specific path
vincent secret env --key-id <KEY_ID> --env-var MY_API_KEY --path ./config/.env

wallet — EVM Wallet Operations

Transfer tokens, check balances, execute transactions, and swap tokens using ZeroDev smart accounts.

| Command | Description | Key Flags | |---|---|---| | wallet address | Get wallet address | --key-id | | wallet balances | Get multi-chain token balances | --key-id, --chain-ids | | wallet transfer | Transfer ERC-20 or native ETH | --to (required), --amount (required), --token | | wallet send-tx | Execute raw transaction | --to (required), --data (required), --value | | wallet swap | Preview or execute a token swap | Subcommand: preview or execute. --sell-token, --buy-token, --sell-amount, --chain-id (all required) | | wallet transfer-between | Cross-chain transfer between wallets | Subcommand: preview, execute, or status. See --help |

# Transfer 0.1 ETH
vincent wallet transfer --to 0x1234... --amount 0.1

# Transfer USDC (specify token address)
vincent wallet transfer --to 0x1234... --amount 100 --token 0xa0b8...

# Preview a swap
vincent wallet swap preview --sell-token 0xETH --buy-token 0xUSDC --sell-amount 1 --chain-id 1

# Execute the swap
vincent wallet swap execute --sell-token 0xETH --buy-token 0xUSDC --sell-amount 1 --chain-id 1 --slippage 100

polymarket — Prediction Market Trading

Search markets, place bets, manage orders, and track positions on Polymarket.

| Command | Description | Key Flags | |---|---|---| | polymarket balance | Get USDC balance | --key-id | | polymarket markets | Search or browse markets | --query, --slug, --active, --limit | | polymarket market | Get specific market details | --condition-id (required) | | polymarket orderbook | Get orderbook for a token | --token-id (required) | | polymarket bet | Place a BUY or SELL order | --token-id (required), --side (required), --amount (required), --price | | polymarket holdings | Get portfolio holdings | --key-id | | polymarket open-orders | List active orders | --market | | polymarket trades | Get trade history | --key-id | | polymarket cancel-order | Cancel a specific order | --order-id (required) | | polymarket cancel-all | Cancel all open orders | --key-id | | polymarket redeem | Redeem resolved outcomes | --condition-ids | | polymarket withdraw | Withdraw USDC | --to (required), --amount (required) |

# Search for markets
vincent polymarket markets --query "world cup"

# Browse active markets
vincent polymarket markets --active --limit 10

# Look up a market by slug or URL
vincent polymarket markets --slug "will-bitcoin-hit-100k"

# Place a limit buy at $0.45
vincent polymarket bet --token-id <TOKEN_ID> --side BUY --amount 50 --price 0.45

# Place a market buy
vincent polymarket bet --token-id <TOKEN_ID> --side BUY --amount 50

# Redeem all resolved positions
vincent polymarket redeem

hyperliquid — Hyperliquid Perpetuals Trading

Trade perpetuals, check balances, manage orders, and view positions on Hyperliquid.

Requires a HYPERLIQUID_WALLET secret:

vincent secret create --type HYPERLIQUID_WALLET --memo "My Hyperliquid wallet"

| Command | Description | Key Flags | |---|---|---| | hyperliquid balance | Get account balance | --key-id | | hyperliquid markets | List available markets | --key-id | | hyperliquid orderbook | Get orderbook for a coin | --coin (required), --key-id | | hyperliquid trade | Place a buy or sell order | --coin (required), --is-buy (required), --sz (required), --limit-px (required), --order-type, --reduce-only | | hyperliquid open-orders | List open orders | --coin, --key-id | | hyperliquid trades | Get trade history | --coin, --key-id | | hyperliquid cancel-order | Cancel a specific order | --coin (required), --oid (required), --key-id | | hyperliquid cancel-all | Cancel all open orders | --coin, --key-id |

# Check balance
vincent hyperliquid balance

# List markets
vincent hyperliquid markets

# View BTC orderbook
vincent hyperliquid orderbook --coin BTC

# Place a limit buy: 0.001 BTC at $80000
vincent hyperliquid trade --coin BTC --is-buy true --sz 0.001 --limit-px 80000

# Place a market sell (set price slightly below best bid)
vincent hyperliquid trade --coin ETH --is-buy false --sz 0.01 --limit-px 2900 --order-type market

# Reduce-only close
vincent hyperliquid trade --coin BTC --is-buy false --sz 0.001 --limit-px 79000 --reduce-only true

# Cancel a specific order
vincent hyperliquid cancel-order --coin BTC --oid 12345678

# Cancel all ETH orders
vincent hyperliquid cancel-all --coin ETH

trading-engine — Trading Engine

LLM-powered strategies and automated trade rules (stop-loss, take-profit, trailing stop) for Polymarket positions.

| Command | Description | Key Flags | |---|---|---| | trading-engine status | Get monitoring status | --key-id | | trading-engine create-rule | Create a trading rule | --market-id (required), --token-id (required), --rule-type (required), --trigger-price (required), --trailing-percent | | trading-engine list-rules | List rules | --status | | trading-engine update-rule | Update a rule's trigger price | --rule-id (required), --trigger-price (required) | | trading-engine delete-rule | Delete a rule | --rule-id (required) | | trading-engine positions | Get monitored positions | --key-id | | trading-engine events | Get rule event log | --rule-id, --limit, --offset |

Rule types: STOP_LOSS, TAKE_PROFIT, TRAILING_STOP

# Create a stop-loss at $0.30
vincent trading-engine create-rule \
  --market-id <CONDITION_ID> \
  --token-id <TOKEN_ID> \
  --rule-type STOP_LOSS \
  --trigger-price 0.30

# Create a trailing stop with 10% trail
vincent trading-engine create-rule \
  --market-id <CONDITION_ID> \
  --token-id <TOKEN_ID> \
  --rule-type TRAILING_STOP \
  --trigger-price 0.50 \
  --trailing-percent 10

# List active rules
vincent trading-engine list-rules --status ACTIVE

raw-signer — Raw Message Signing

Sign arbitrary messages using Ethereum or Solana curves.

| Command | Description | Key Flags | |---|---|---| | raw-signer addresses | Get signing addresses (Ethereum + Solana) | --key-id | | raw-signer sign | Sign a hex-encoded message | --message (required), --curve (required) |

# Get signing addresses
vincent raw-signer addresses

# Sign a message with Ethereum curve
vincent raw-signer sign --message 0xdeadbeef --curve ethereum

twitter — Twitter/X Data

Search tweets and look up users and their content.

| Command | Description | Key Flags | |---|---|---| | twitter search | Search tweets | --q (required), --max-results, --start-time, --end-time | | twitter user | Get user profile | --username (required) | | twitter user-tweets | Get user's tweets | --user-id (required), --max-results | | twitter tweet | Get a specific tweet | --tweet-id (required) |

# Search tweets
vincent twitter search --q "AI agents" --max-results 20

# Look up a user
vincent twitter user --username elonmusk

# Get a user's recent tweets
vincent twitter user-tweets --user-id 44196397

brave — Brave Search

Web and news search via Brave Search API.

| Command | Description | Key Flags | |---|---|---| | brave web | Web search | --q (required), --count, --offset, --freshness, --country | | brave news | News search | --q (required), --count, --freshness |

Freshness values: pd (past day), pw (past week), pm (past month), py (past year)

# Web search
vincent brave web --q "latest crypto news" --count 10

# News from the past week
vincent brave news --q "AI regulation" --freshness pw

API Key Management

The CLI stores API keys locally in ~/.openclaw/credentials/ organized by type:

~/.openclaw/credentials/
├── agentwallet/          # EVM_WALLET, POLYMARKET_WALLET, RAW_SIGNER keys
│   ├── <key-id>.json
│   └── ...
├── credentials/          # API_KEY, SSH_KEY, OAUTH_TOKEN, CREDENTIALS keys
│   ├── <key-id>.json
│   └── ...
└── datasources/          # DATA_SOURCES keys
    ├── <key-id>.json
    └── ...

• Auto-discovery: If you have only one key of the required type, commands find it automatically.
• Multiple keys: Use --key-id <ID> to specify which key to use.
• Key files are stored with 0600 permissions (owner read/write only).

Development

# Run in dev mode (no build needed)
npm run dev -- <group> <command> [options]

# Type check
npm run typecheck

# Lint
npm run lint

# Build
npm run build

Architecture

cli/
├── src/
│   ├── index.ts              # Entry point, command dispatch
│   ├── lib/
│   │   ├── args.ts           # Argument parsing (--flag value)
│   │   ├── client.ts         # HTTP client (vincentGet/Post/Delete/Patch)
│   │   ├── keystore.ts       # Local credential storage (~/.openclaw/credentials/)
│   │   └── types.ts          # TypeScript types (SecretType, KeyData, ArgDef)
│   └── commands/
│       ├── brave/            # Brave Search commands
│       ├── hyperliquid/      # Hyperliquid perpetuals trading commands
│       ├── polymarket/       # Polymarket trading commands
│       ├── raw-signer/       # Raw signing commands
│       ├── secret/           # Secret management commands
│       ├── trading-engine/   # Trading engine (strategies + trade rules)
│       ├── twitter/          # Twitter/X data commands
│       └── wallet/           # EVM wallet commands
├── package.json
└── tsconfig.json

Each command exports a run(argv: string[]) function. The entry point dynamically loads the matching command module based on the <group> <command> pair.