CLI Guide - Joyride Docs

What the CLI does

The CLI is the fastest way to:

create and manage Solana wallets for trading
inspect active instruments and options chains
get quotes and order book snapshots
place and cancel paper-trading orders
review balances, positions, and trade history
stream live market data in the terminal

Both human-readable table output and machine-readable JSON output are supported on every command. Current mode: Paper trading only. No real money at risk.

Installation

Prerequisites

Node.js >= 20.0.0

Install

npm install -g joyride-cli

This installs the joyride CLI and the bundled MCP server. Verify it’s working:

joyride --help

Uninstall

npm uninstall -g joyride-cli

Setup and authentication

First-run setup

The first time you run any command, an interactive setup wizard launches:

$ joyride chain SOL

┌  Joyride CLI Setup
│
◇  WebSocket URL
│  wss://joyride.exchange/api/v1
│
◇  HTTP API URL
│  https://joyride.exchange/api
│
◇  How would you like to set up your wallet?
│  Create new wallet / Import existing wallet
│
◇  Enter passphrase to encrypt wallet:
│  ********
│
◇  Wallet created: GmQo...9wC8
│
◇  Default asset
│  SOL
│
└  Configuration saved!

Or run the wizard explicitly:

joyride setup

Authentication model

The CLI authenticates to the Joyride API using a Solana wallet via SIWS (Sign-In with Solana). Your wallet’s private key is encrypted with a passphrase and stored locally as a keystore file. The first successful Joyride authentication seeds your paper-trading account with $10,000.00 in paper USDC. This auto-seed is active until the Season 1 competition launches on 2026-05-05 UTC; after launch, funding requires an invite code. The CLI resolves wallet credentials in this order:

JOYRIDE_PRIVATE_KEY env var — Base58-encoded private key (bypasses keystore entirely)
Keystore + JOYRIDE_KEYSTORE_PASSWORD env var — decrypts the keystore automatically
Keystore + interactive passphrase prompt — prompts in TTY mode

For scripting and automation, set the env var to avoid interactive prompts:

export JOYRIDE_KEYSTORE_PASSWORD="your-passphrase"

Config file

Config is saved to ~/.joyride/config.toml:

[auth]
wallet_address = "GmQozSzrtMjXt5F1Bed8Vrt55zCbiga8vDZr47RX9wC8"

[defaults]
asset = "SOL"
mode = "paper"
output = "table"

[connection]
ws_url = "wss://joyride.exchange/api/v1"
http_url = "https://joyride.exchange/api"

You can edit this file directly instead of re-running setup.

Configuration priority

Settings resolve in this order (highest priority first):

CLI flags (--gateway, --http, --asset, --output)
Environment variables (JOYRIDE_WS_URL, JOYRIDE_HTTP_URL, JOYRIDE_PRIVATE_KEY, JOYRIDE_KEYSTORE_PASSWORD)
Config file (~/.joyride/config.toml)
Defaults (wss://joyride.exchange/api/v1, https://joyride.exchange/api)

Instrument ID format

All instrument IDs follow this pattern:

{ASSET}_USDC-{DMMMYY}-{STRIKE}-{C|P}

Component	Description	Examples
`ASSET`	Underlying asset	`SOL`, `BTC`, `ETH`
`DMMMYY`	Expiry date (1- or 2-digit day)	`3MAR26`, `27FEB26`
`STRIKE`	Strike price (integer USD)	`75`, `100`, `200`
`C\|P`	Option type	`C` (call), `P` (put)

Examples:

SOL_USDC-3MAR26-75-C — SOL $75 call expiring Mar 3, 2026
SOL_USDC-27FEB26-100-P — SOL $100 put expiring Feb 27, 2026

Use joyride chain SOL to see all available instruments and their valid IDs. Joyride currently offers same-day (0DTE) options. Instruments expire at end of day and refresh daily.

Command reference

Wallet management

`joyride wallet create`

Generate a new Solana wallet, encrypt it with a passphrase, and save it locally.

$ joyride wallet create
◇  Enter passphrase to encrypt wallet: ********
◇  Confirm passphrase: ********

⚠  BACKUP YOUR PRIVATE KEY — write it down or save it in a password manager.
   Do not share it. Do not send it over email or chat.
   If you lose your passphrase and keystore, this is your only recovery path.

◇  5Kd8F...base58-private-key

ℹ  To recover this wallet later: joyride wallet import --private-key <key>

  Address   GmQozSzrtMjXt5F1Bed8Vrt55zCbiga8vDZr47RX9wC8
  Keystore  /Users/you/.joyride/wallets/GmQo...9wC8.json
  Active    Yes (auto-selected as first wallet)

The first wallet you create is automatically set as the active wallet.

`joyride wallet import`

Import a wallet from a Base58-encoded private key.

# Interactive
$ joyride wallet import

# Non-interactive
$ joyride wallet import --private-key 5Kd8F...

Flag	Required	Description
`--private-key <key>`	No	Base58-encoded private key. Prompted if omitted.

`joyride wallet list`

List all wallets in the keystore directory.

$ joyride wallet list
┌──────────────────────────────────────────────┬────────┐
│ Address                                      │ Active │
├──────────────────────────────────────────────┼────────┤
│ GmQozSzrtMjXt5F1Bed8Vrt55zCbiga8vDZr47RX9wC8 │ ✓      │
│ 7nYB...second-wallet                         │        │
└──────────────────────────────────────────────┴────────┘

`joyride wallet show`

Show the active wallet address and keystore path.

$ joyride wallet show
  Wallet           GmQozSzrtMjXt5F1Bed8Vrt55zCbiga8vDZr47RX9wC8
  Keystore         /Users/you/.joyride/wallets/GmQo...9wC8.json
  Keystore exists  Yes

`joyride wallet use <address>`

Switch the active wallet.

$ joyride wallet use 7nYB...second-wallet
✔ Active wallet set to 7nYB...second-wallet

Market data

`joyride chain <asset>`

List all options contracts for an asset. Start here to see available instruments.

$ joyride chain SOL
✔ 72 instruments found
┌────────────────────────┬────────┬─────────┬──────┬───────────┬──────────┐
│ Instrument             │ Strike │ Expiry  │ Type │ Tick Size │ Min Size │
├────────────────────────┼────────┼─────────┼──────┼───────────┼──────────┤
│ SOL_USDC-3MAR26-75-C   │    $75 │ 3MAR26  │ CALL │     $0.01 │      0.1 │
│ SOL_USDC-3MAR26-75-P   │    $75 │ 3MAR26  │ PUT  │     $0.01 │      0.1 │
│ ...                    │        │         │      │           │          │
└────────────────────────┴────────┴─────────┴──────┴───────────┴──────────┘

Transport: WebSocket

`joyride quote <instrument>`

Get the current best bid, ask, and mid price.

$ joyride quote SOL_USDC-3MAR26-75-C
✔ Quote fetched
┌──────────────────────┬───────┬───────┬───────┐
│ Instrument           │ Bid   │ Ask   │ Mid   │
├──────────────────────┼───────┼───────┼───────┤
│ SOL_USDC-3MAR26-75-C │ $3.50 │ $5.00 │ $4.25 │
└──────────────────────┴───────┴───────┴───────┘

If the book is empty, bid/ask/mid show -. Transport: WebSocket

`joyride book <instrument>`

Show bid and ask price levels with sizes.

$ joyride book SOL_USDC-3MAR26-75-C
✔ Order book fetched
Order Book: SOL_USDC-3MAR26-75-C

   Bids                    Asks
   $3.50  ×  2.0           $5.00  ×  1.0
   $3.00  ×  5.0           $5.50  ×  3.0

Flag	Description
`--depth <levels>`	Number of price levels (default: 10)
`--live`	Stream real-time updates (press Ctrl+C to exit)

Transport: WebSocket

`joyride ticker <instrument>`

Get last price, volume, and open interest. Transport: HTTP

`joyride tickers`

Summary of all instruments with recent activity. Transport: HTTP

`joyride price <asset>`

Current spot price for the underlying asset.

$ joyride price SOL

Transport: HTTP

`joyride history <instrument>`

OHLCV candle data for an instrument.

$ joyride history SOL_USDC-3MAR26-75-C
$ joyride history SOL_USDC-3MAR26-75-C --start 2026-03-03 --end 2026-03-04

Flag	Description
`--start <YYYY-MM-DD>`	Start date
`--end <YYYY-MM-DD>`	End date

Transport: HTTP

`joyride market-config`

Exchange-level settings (tick sizes, contract sizes, trading hours). Transport: HTTP

`joyride greeks [instrument]`

Mark price, implied volatility, and Greeks (delta, gamma, theta, vega, rho) for one or all instruments. Output also includes the mark source (confidence level for the mark IV) and probability of profit (pop).

# All instruments
$ joyride greeks

# Single instrument
$ joyride greeks SOL_USDC-3MAR26-75-C

Column	Description
`Mark`	Theoretical option price in USD. Adaptive precision is used for sub-cent values.
`IV`	Mark implied volatility
`Mark Source`	Derivation source: `two_sided_mid`, `carry_forward`, or `surface_fallback`
`POP`	Probability of profit
`Delta` / `Gamma` / `Theta` / `Vega` / `Rho`	Per-unit sensitivities

Transport: HTTP

Trading

`joyride order place`

Place a limit or market order.

# Limit order: sell 1 contract at $5.00
$ joyride order place --instrument SOL_USDC-3MAR26-75-C --side sell --size 1 --price 5
✔ Order placed
┌────────────┬──────────────────────┐
│ Order ID   │ 1994754              │
├────────────┼──────────────────────┤
│ Instrument │ SOL_USDC-3MAR26-75-C │
├────────────┼──────────────────────┤
│ Side       │ Sell                 │
├────────────┼──────────────────────┤
│ Type       │ limit                │
├────────────┼──────────────────────┤
│ Price      │ $5.00                │
├────────────┼──────────────────────┤
│ Size       │ 1                    │
├────────────┼──────────────────────┤
│ Status     │ open                 │
└────────────┴──────────────────────┘

# Market order (no --price)
$ joyride order place --instrument SOL_USDC-3MAR26-75-C --side sell --size 1

Flag	Required	Description
`--instrument <id>`	Yes	Instrument ID
`--side <buy\|sell>`	Yes	Order side
`--size <contracts>`	Yes	Number of contracts (decimals allowed, e.g. `0.5`)
`--price <usd>`	No	Limit price in USD. Omit for market order.

Market orders execute immediately at the best available price. If no counterparty exists, the order is cancelled. Transport: WebSocket

`joyride order list`

List open orders.

$ joyride order list
✔ 2 open order(s)
┌──────────┬──────────────────────┬──────┬───────┬──────┬────────┐
│ Order ID │ Instrument           │ Side │ Price │ Size │ Status │
├──────────┼──────────────────────┼──────┼───────┼──────┼────────┤
│ 1994754  │ SOL_USDC-3MAR26-75-C │ Sell │ $5.00 │    1 │ open   │
│ 1995088  │ SOL_USDC-3MAR26-75-P │ Buy  │ $2.00 │    1 │ open   │
└──────────┴──────────────────────┴──────┴───────┴──────┴────────┘

Transport: WebSocket

`joyride order status <orderId>`

Check order status. Checks open orders first, then falls back to order history. Transport: WebSocket + HTTP (fallback)

`joyride order cancel <orderId>`

Cancel a specific order.

$ joyride order cancel 1994754 --instrument SOL_USDC-3MAR26-75-C

Flag	Required	Description
`--instrument <id>`	Yes	Instrument ID of the order

Transport: WebSocket

`joyride order cancel-all`

Cancel all open orders.

$ joyride order cancel-all
$ joyride order cancel-all --instrument SOL_USDC-3MAR26-75-C

Transport: WebSocket

`joyride order history`

All orders including filled, cancelled, and expired. Transport: HTTP

Account

`joyride balance`

Account balance.

$ joyride balance
✔ Balance fetched
┌───────────┬────────────┐
│ Available │ $10,000.00 │
├───────────┼────────────┤
│ Locked    │ $0.00      │
├───────────┼────────────┤
│ Total     │ $10,000.00 │
└───────────┴────────────┘

Transport: WebSocket

`joyride account`

Combined balance and positions overview. Transport: HTTP

`joyride positions`

Open positions with optional PnL metrics.

$ joyride positions
$ joyride positions --metrics   # Include PnL, breakeven, current value

Transport: HTTP

`joyride trades`

Trade history. Add --live <instrument> for a real-time feed.

$ joyride trades
$ joyride trades --live SOL_USDC-3MAR26-75-C

Transport: HTTP (snapshot), WebSocket (live)

`joyride profiles`

List all user profiles (usernames and avatars). Transport: HTTP

MCP server management

`joyride mcp install`

Configure the Joyride MCP server in an AI client. This is the easiest way to connect Joyride to Claude Code, Cursor, or Codex.

$ joyride mcp install --client claude    # Claude Code
$ joyride mcp install --client cursor    # Cursor
$ joyride mcp install --client codex     # Codex

Flag	Required	Description
`--client <client>`	Yes	Target client: `claude`, `codex`, or `cursor`
`--force`	No	Overwrite existing config if already configured

Requires an active session (joyride login). See the MCP Server Guide for full details.

`joyride mcp uninstall`

Remove the Joyride MCP server from an AI client.

$ joyride mcp uninstall --client claude

Safe to run even if joyride is not currently configured.

`joyride mcp serve`

Start the MCP server directly (stdio transport). This is called automatically by AI clients — you typically don’t need to run it yourself.

$ joyride mcp serve

Live streaming

Two commands support live-updating terminal UIs powered by Ink. Press Ctrl+C to exit.

# Live order book with colored bids/asks and spread
joyride book SOL_USDC-3MAR26-75-C --live

# Scrolling trade feed
joyride trades --live SOL_USDC-3MAR26-75-C

`joyride watch <channel> [argument]`

Subscribe to a WebSocket channel and stream events as JSON lines (one event per line) to stdout. Designed for piping into jq, log files, or downstream agents. Reconnects automatically on transient disconnects. Press Ctrl+C to exit.

# Public channels (no auth required)
joyride watch spot SOL
joyride watch book SOL_USDC-3MAR26-75-C
joyride watch book SOL_USDC-3MAR26-75-C --depth 5
joyride watch trades SOL_USDC-3MAR26-75-C
joyride watch tickers SOL_USDC-3MAR26-75-C

# Private channels (require an active session via joyride login)
joyride watch orders
joyride watch fills

# Pipe into jq for live filtering
joyride watch trades SOL_USDC-3MAR26-75-C | jq 'select(.size > 1)'

Channel	Argument	Auth	Description
`spot`	`<asset>`	No	Real-time spot price for the underlying (`SOL`, `BTC`, `ETH`)
`book`	`<instrument>`	No	Order book updates (snapshots and deltas)
`trades`	`<instrument>`	No	Public trade feed
`tickers`	`<instrument>`	No	Best bid/ask, spread, mid, and spot for the instrument
`orders`	—	Yes	Order status updates for the authenticated user
`fills`	—	Yes	Trade fills for the authenticated user

Flag	Description
`--depth <levels>`	Number of price levels for the `book` channel (default: 10). Ignored on other channels.

If orders or fills is used without an active session, the command exits immediately with a clear error. Run joyride login first. Transport: WebSocket

Output modes

Every command supports two output formats:

Table (default)

Human-readable tables with formatting and colors.

$ joyride balance

JSON

Machine-readable JSON for scripts, pipes, and AI agents.

$ joyride balance --output json
$ joyride balance -o json

# Pipe to jq
$ joyride order list --output json | jq '.[].instrumentId'

Session expiry metadata

When --output json is used and an active session is loaded, object-typed JSON responses are enriched with a _session field containing the absolute session expiry timestamp. Long-running agents can read this to refresh proactively before the session expires (and the next request returns 401).

{
  "available": "10000.00",
  "locked": "0.00",
  "total": "10000.00",
  "_session": {
    "expiresAt": "2026-05-26T00:00:00.000Z"
  }
}

Field	Type	Description
`_session.expiresAt`	string (ISO 8601)	Absolute UTC timestamp when the current session expires. Compare against the current time to decide whether to re-run `joyride login`.

Notes:

Enrichment only applies when output mode is json. Table output is unaffected.
Only object-typed JSON payloads are enriched. Array-typed responses (positions, chain, order list, etc.) are left as-is so consumers can keep iterating with the same shape.
If no session is loaded (e.g. before joyride login has run), the _session field is omitted. Treat its absence as a non-error.
The previously-considered _session.expiresIn field is intentionally not emitted — use expiresAt and compute the remaining time at read-time to avoid drift between command execution and output consumption.

Global flags

These flags work on every command:

Flag	Short	Description
`--output <format>`	`-o`	`table` (default) or `json`
`--verbose`	`-v`	Enable verbose logging
`--gateway <url>`		Override WebSocket URL
`--http <url>`		Override HTTP REST URL
`--asset <asset>`		Override default asset (`SOL`, `BTC`, `ETH`)
`--version`	`-V`	Show CLI version
`--help`	`-h`	Show help

Transport reference

The CLI uses two transports to communicate with the Joyride API.

WebSocket commands (real-time)

Command	Description
`chain`	List available instruments
`quote`	Best bid/ask/mid
`book`	Order book snapshot or live stream
`order place`	Place limit or market order
`order cancel`	Cancel an order
`order cancel-all`	Cancel all orders
`order list`	List open orders
`balance`	Account balance
`trades --live`	Live trade feed
`watch`	Stream any channel as JSON lines

HTTP commands (snapshots)

Command	Description
`ticker`	Ticker snapshot
`tickers`	All tickers
`price`	Underlying spot price
`history`	OHLCV price history
`market-config`	Exchange configuration
`greeks`	Mark, IV, mark source, POP, and Greeks
`account`	Account summary
`positions`	Open positions
`trades`	Trade history
`profiles`	User profiles
`order history`	Full order history
`order status`	Falls back to HTTP if not in open orders

Production endpoints:

WebSocket: wss://joyride.exchange/api/v1
HTTP: https://joyride.exchange/api

Troubleshooting

`zsh: command not found: joyride`

The CLI is not installed or not on your PATH. Run npm install -g joyride-cli and restart your shell.

Setup wizard hangs or won’t accept input

The wizard requires an interactive terminal (TTY). It won’t work when piped or in CI. Run joyride setup directly in your terminal.

`iter.next is not a function`

Your installed CLI version is out of date. Upgrade to the latest Joyride CLI package or binary provided for the alpha.

Passphrase prompted on every command

Each CLI invocation is a separate process. To avoid repeated prompts, export the passphrase:

export JOYRIDE_KEYSTORE_PASSWORD="your-passphrase"

Or use JOYRIDE_PRIVATE_KEY to bypass the keystore entirely.

Quote shows all dashes

The order book is empty — no bids or asks are resting. This is normal on a thin paper trading market. Try joyride chain SOL to find instruments with activity.

HTTP commands fail

Check your config:

cat ~/.joyride/config.toml

Verify http_url is correct and the endpoint is running. WebSocket commands will still work without HTTP.

Orders disappear immediately

0DTE options expire at end of day. If instruments have expired, orders may be automatically cancelled. Use joyride chain SOL to check current expiry dates.

Debug mode

JOYRIDE_DEBUG=1 joyride quote SOL_USDC-3MAR26-75-C 2>debug.log
cat debug.log

Logs all incoming WebSocket message types and payloads to stderr.

Guides

Documentation Index

​What the CLI does

​Installation

​Prerequisites

​Install

​Uninstall

​Setup and authentication

​First-run setup

​Authentication model

​Config file

​Configuration priority

​Instrument ID format

​Command reference

​Wallet management

​joyride wallet create

​joyride wallet import

​joyride wallet list

​joyride wallet show

​joyride wallet use <address>

​Market data

​joyride chain <asset>

​joyride quote <instrument>

​joyride book <instrument>

​joyride ticker <instrument>

​joyride tickers

​joyride price <asset>

​joyride history <instrument>

​joyride market-config

​joyride greeks [instrument]

​Trading

​joyride order place

​joyride order list

​joyride order status <orderId>

​joyride order cancel <orderId>

​joyride order cancel-all

​joyride order history

​Account

​joyride balance

​joyride account

​joyride positions

​joyride trades

​joyride profiles

​MCP server management

​joyride mcp install

​joyride mcp uninstall

​joyride mcp serve

​Live streaming

​joyride watch <channel> [argument]

​Output modes

​Table (default)

​JSON

​Session expiry metadata

​Global flags

​Transport reference

​WebSocket commands (real-time)

​HTTP commands (snapshots)

​Troubleshooting

​zsh: command not found: joyride

​Setup wizard hangs or won’t accept input

​iter.next is not a function

​Passphrase prompted on every command

​Quote shows all dashes

​HTTP commands fail

​Orders disappear immediately

​Debug mode

What the CLI does

Installation

Prerequisites

Install

Uninstall

Setup and authentication

First-run setup

Authentication model

Config file

Configuration priority

Instrument ID format

Command reference

Wallet management

`joyride wallet create`

`joyride wallet import`

`joyride wallet list`

`joyride wallet show`

`joyride wallet use <address>`

Market data

`joyride chain <asset>`

`joyride quote <instrument>`

`joyride book <instrument>`

`joyride ticker <instrument>`

`joyride tickers`

`joyride price <asset>`

`joyride history <instrument>`

`joyride market-config`

`joyride greeks [instrument]`

Trading

`joyride order place`

`joyride order list`

`joyride order status <orderId>`

`joyride order cancel <orderId>`

`joyride order cancel-all`

`joyride order history`

Account

`joyride balance`

`joyride account`

`joyride positions`

`joyride trades`

`joyride profiles`

MCP server management

`joyride mcp install`

`joyride mcp uninstall`

`joyride mcp serve`

Live streaming

`joyride watch <channel> [argument]`

Output modes

Table (default)

JSON

Session expiry metadata

Global flags

Transport reference

WebSocket commands (real-time)

HTTP commands (snapshots)

Troubleshooting

`zsh: command not found: joyride`

Setup wizard hangs or won’t accept input

`iter.next is not a function`

Passphrase prompted on every command

Quote shows all dashes

HTTP commands fail

Orders disappear immediately

Debug mode