# 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

```bash
npm install -g @vincentai/cli
```

This installs the `vincent` command globally.

## Quick Start

```bash
# 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.

```bash
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`

```bash
# 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` |

```bash
# 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) |

```bash
# 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:
```bash
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` |

```bash
# 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`

```bash
# 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) |

```bash
# 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) |

```bash
# 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)

```bash
# 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

```bash
# 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.