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 and verify

For alpha access, install the Joyride CLI from the package or binary you received from the Joyride team. After installation, verify it is available on your PATH:

joyride --help

If you do not have the alpha package yet, contact engineering@joyride.exchange.

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 creates a paper-trading account with a starting balance of $10,000.00. 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

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

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

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'

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

HTTP commands (snapshots)

Command	Description
`ticker`	Ticker snapshot
`tickers`	All tickers
`price`	Underlying spot price
`history`	OHLCV price history
`market-config`	Exchange configuration
`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 executable is not installed or not on your PATH. Reinstall it from the Joyride alpha package you received 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

​What the CLI does

​Installation

​Prerequisites

​Install and verify

​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

​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

​Live streaming

​Output modes

​Table (default)

​JSON

​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 and verify

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`

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`

Live streaming

Output modes

Table (default)

JSON

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