bybit-cli

Thank you to the creators of krakenfx/kraken-cli for providing the idea and framework for this project. This tool is inspired by their CLI, designed as a mirror for Bybit.

DISCLAIMER: This is an UNOFFICIAL community-maintained CLI and is NOT affiliated with Bybit. Use at your own risk. Trading involves significant risk of loss.

The AI-native CLI for trading crypto on Bybit. Full Bybit V5 API access. Built-in MCP server. Live trading plus spot and futures paper trading. Single binary.

Works with Claude, Cursor, Codex, Copilot, Gemini, and any MCP-compatible agent.

Try these with your AI agent:

"Build me a morning market brief for BTC, ETH, and SOL with trend, volatility, funding, and key levels."

"Watch BTCUSDT and alert me if price breaks above 68,000, drops below 66,000, or gets within 0.25% of either level."

"Create a trade plan for ETHUSDT with an entry, stop, and target, risk only 0.5% of my account, and show me the validate command before placing anything."

"Check my open positions and set a stop-loss at 5% below entry on each one."

"Run a futures paper session on BTCUSDT: initialize 10,000 USDT, go long with 10x leverage, place a reduce-only stop, and show margin plus liquidation risk after each step."

[!CAUTION] Unofficial software. Interacts with the live Bybit exchange and can execute real financial transactions. Read DISCLAIMER.md before using with real funds or AI agents.

Contents

• Installation
• What You Can Trade
• For AI Agents
• Verifying Binaries
• Quick Start
• API Keys & Configuration
• MCP Server
• Paper Trading
• Commands
• Examples
• Agent Skills
• Development
• Contributing
• License & Disclaimer

Installation

Single binary, no runtime dependencies.

Recommended: download, verify, install

Download the release archive for your platform from the GitHub Releases page, verify the checksum or minisign signature, then place bybit or bybit.exe on your PATH.

Example verified install on Linux (x86_64; replace the archive name with the artifact for your platform):

curl -LO https://github.com/kdkiss/bybit-cli/releases/latest/download/bybit-cli-x86_64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/kdkiss/bybit-cli/releases/latest/download/bybit-cli-x86_64-unknown-linux-gnu.tar.gz.minisig
minisign -Vm bybit-cli-x86_64-unknown-linux-gnu.tar.gz -P RWTeznOm/OuBmlyv8EeOQxZOog4NsO014QzO/aS3/+1woRbSPGUy3eEF
tar -xzf bybit-cli-x86_64-unknown-linux-gnu.tar.gz
install -m 755 bybit ~/.local/bin/bybit

On Windows, download the matching .zip plus checksum or .minisig from Releases, verify it, then extract bybit.exe into a directory on PATH.

curl --proto '=https' --tlsv1.2 -LsSf -o bybit-cli-installer.sh https://github.com/kdkiss/bybit-cli/releases/latest/download/bybit-cli-installer.sh
sh bybit-cli-installer.sh

Invoke-WebRequest -Uri https://github.com/kdkiss/bybit-cli/releases/latest/download/bybit-cli-installer.ps1 -OutFile bybit-cli-installer.ps1
powershell -ExecutionPolicy Bypass -File .\bybit-cli-installer.ps1

Verify it works:

bybit market server-time && bybit market tickers --category linear --symbol BTCUSDT

Pre-built archives and installer scripts are available on the GitHub Releases page.

Tagged releases are built with cargo-dist, attested with GitHub build provenance, and published with per-artifact .sha256 files, a unified sha256.sum, SHA256SUMS.txt, and minisig signatures. Maintainers must configure MINISIGN_SECRET_KEY and publish the matching minisign public key before the first public release.

See Verifying Binaries for minisign verification.

git clone https://github.com/kdkiss/bybit-cli
cd bybit-cli
cargo install --path . --locked

cargo build --release
cp target/release/bybit ~/.local/bin/

What You Can Trade

One binary covers Bybit spot, derivatives, earn workflows, streaming, and both paper engines.

Product availability and permissions vary by jurisdiction, account type, and API key scope.

Migrating from kraken-cli conventions? See KRAKEN_COMPAT.md.

For AI Agents

If you're an AI agent or building one, start here:

Core invocation pattern:

bybit <command> [args...] -o json

• stdout is valid JSON on success.
• Exit code 0 means success. Non-zero means failure.
• On failure, the CLI prints a JSON error envelope to stderr.
• stderr may also contain human-oriented diagnostics. Do not discard it if you need machine-readable errors.

Verifying Binaries

Release binaries are signed with minisign. Published artifacts on the GitHub Releases page include checksums and minisign signatures.

Public key:

untrusted comment: minisign public key 9A81EBFCA673CEDE
RWTeznOm/OuBmlyv8EeOQxZOog4NsO014QzO/aS3/+1woRbSPGUy3eEF

Verify a downloaded archive:

minisign -Vm bybit-cli-x86_64-unknown-linux-gnu.tar.gz -P RWTeznOm/OuBmlyv8EeOQxZOog4NsO014QzO/aS3/+1woRbSPGUy3eEF

Install minisign with brew install minisign (macOS) or your Linux package manager.

Quick Start

Getting Started for Humans

If you just want to configure the CLI and start using it interactively:

bybit setup
bybit shell

bybit setup walks through credentials and defaults. bybit shell starts the interactive REPL with history and tab-completion.

Quick Checks

Public market data requires no credentials:

bybit market tickers --category linear --symbol BTCUSDT -o json
bybit market orderbook --category linear --symbol BTCUSDT --limit 10
bybit market kline --category linear --symbol BTCUSDT --interval 60

With authentication:

export BYBIT_API_KEY="your-key"
export BYBIT_API_SECRET="your-secret"

bybit account balance -o json
bybit trade open-orders --category linear -o json
bybit trade buy --symbol BTCUSDT --qty 0.01 --price 50000 --validate

For humans (table output, interactive setup):

bybit setup
bybit market tickers --category linear --symbol BTCUSDT
bybit account balance
bybit shell

API Keys & Configuration

Authenticated commands require a Bybit API key pair. Public market data, spot paper trading, and futures paper trading work without credentials.

Getting API keys

Visit Bybit API Management. Grant minimum required permissions. For read-only monitoring, "Read" is sufficient.

Environment variables (recommended for agents)

export BYBIT_API_KEY="your-key"
export BYBIT_API_SECRET="your-secret"
export BYBIT_TESTNET="true"        # optional: use testnet
export BYBIT_API_URL="https://..."  # optional: override base URL

For local development, bybit-cli also loads .env from the current working directory (or its parents) at startup. Already-exported environment variables keep precedence.

Non-echo secret input (recommended for interactive or shared systems)

printf '%s\n' 'your-secret' | bybit --api-key your-key --api-secret-stdin auth test
bybit --api-key your-key --api-secret-file ~/.config/bybit/api-secret.txt auth test

Config file (for humans)

Stored in your platform config directory:

• Linux: ~/.config/bybit/config.toml
• macOS: ~/Library/Application Support/bybit/config.toml
• Windows: %APPDATA%\bybit\config.toml

Example:

[auth]
api_key = "your-api-key"
api_secret = "your-api-secret"

[settings]
default_category = "linear"
output = "table"
recv_window = 5000
testnet = false

Run bybit setup for interactive configuration.

Credential resolution

Highest precedence first:

1. CLI flags (--api-key, --api-secret)
2. Environment variables (BYBIT_API_KEY, BYBIT_API_SECRET)
3. Config file (platform config path, for example ~/.config/bybit/config.toml on Linux)

Security

• Config file is created with 0600 permissions (owner read/write only) on Unix.
• Secrets are never logged, printed, or included in error messages.
• Prefer --api-secret-stdin or --api-secret-file over --api-secret on interactive or shared systems.
• For automation, prefer environment variables over command-line flags.

MCP Server

Built-in MCP server is available via bybit mcp. It exposes command groups over stdio for MCP-compatible agents. Load agents/mcp-tool-catalog.json for the runtime MCP tool surface, or agents/tool-catalog.json for the broader CLI/agent command catalog.

{
  "mcpServers": {
    "bybit": {
      "command": "bybit",
      "args": ["mcp", "-s", "all"]
    }
  }
}

Gemini CLI users can use the included gemini-extension.json manifest from the repo root to register the same MCP server configuration.

bybit mcp                          # read-only (market, account, paper, futures-paper)
bybit mcp -s all                   # all services, dangerous calls require acknowledged=true
bybit mcp -s all --allow-dangerous # all services, autonomous mode (no per-call confirmation)
bybit mcp -s market,trade,paper,futures-paper
bybit mcp -s funding,reports,futures,subaccount

Available service groups include market, account, trade, position, asset, funding, convert, reports, subaccount, futures, paper, futures-paper, auth, and ws. The server expects the standard MCP initialize plus notifications/initialized handshake; normal MCP clients handle that automatically.

Persisted local state is shared with normal CLI mode: saved credentials, the spot paper journal, the futures paper state, shell history, and the anonymous instance ID persist across MCP tool calls and server restarts until reset or deleted.

Paper Trading

Two independent paper engines cover spot and perpetual futures. No API keys, no account, no real money. Both use live Bybit public market data.

Spot Paper

Spot paper trading provides a safe sandbox for testing spot-style trading logic with market and limit buy / sell flows, local journal state, configurable fees, and slippage.

Market orders (fill immediately at live price):

bybit paper init --usdt 10000
bybit paper buy --symbol BTCUSDT --qty 0.01
bybit paper sell --symbol BTCUSDT --qty 0.005
bybit paper status

Limit orders (fill when market price crosses):

bybit paper buy --symbol BTCUSDT --qty 0.01 --price 50000   # fills when price ≤ 50000
bybit paper sell --symbol BTCUSDT --qty 0.01 --price 60000  # fills when price ≥ 60000
bybit paper orders     # check open limit orders (checks fills at current prices)
bybit paper cancel 1   # cancel order by ID
bybit paper cancel-all # cancel all pending limit orders

Full session:

bybit paper init --usdt 10000 -o json
bybit paper buy --symbol BTCUSDT --qty 0.01 -o json
bybit paper positions -o json
bybit paper history -o json
bybit paper status -o json
bybit paper reset -o json

bybit paper reset can also re-seed the simulator in one step, for example:

bybit paper reset --balance 2500 --settle-coin USDC --taker-fee-bps 10 --maker-fee-bps 2 --slippage-bps 0

All output includes "mode": "paper" in JSON. Limit buys reserve quote balance plus maker fees, limit sells reserve base asset quantity, and pending orders are reconciled when paper read commands run (balance, positions, history, cancelled, orders, or status).

Futures Paper

Near-parity with live bybit futures order flows. Supports all 8 order types (market, limit, post, stop, take-profit, ioc, trailing-stop, fok), leverage preferences, margin tracking, position netting, liquidation simulation, and funding accrual.

Known differences from live futures:

• order-status only reports locally tracked resting open orders by local paper order ID.
• Post-only orders that would cross the spread are cancelled instead of resting.
• Immediate fills use the current bid/ask snapshot; FOK checks order-book depth, but partial fills and depth-weighted slippage are not modeled.
• All fills use the configured futures paper fee rate; live maker/taker fee differences are not simulated separately.

bybit futures paper init --balance 10000 -o json
bybit futures paper buy BTCUSDT 0.01 --leverage 10 --type market -o json
bybit futures paper sell BTCUSDT 0.01 --type limit --price 95000 --reduce-only -o json
bybit futures paper buy BTCUSDT 0.01 --type stop --stop-price <STOP_PRICE> --trigger-signal mark -o json
bybit futures paper positions -o json
bybit futures paper balance -o json
bybit futures paper fills -o json
bybit futures paper status -o json
bybit futures paper reset -o json

All futures paper output includes "mode": "futures_paper" in JSON. Spot paper and futures paper are fully independent; resetting one does not affect the other.

Commands

The CLI exposes 18 top-level commands. The futures paper simulator is a nested namespace under futures. For machine-readable references, load agents/tool-catalog.json for the full CLI/agent command catalog and agents/mcp-tool-catalog.json for the runtime MCP tool surface.

Examples

Conditional order based on live price

PRICE=$(bybit market tickers --category linear --symbol BTCUSDT -o json \
  | jq -r '.list[0].lastPrice')
bybit trade buy --symbol BTCUSDT --qty 0.001 --price "$PRICE" --validate

Real-time price stream

bybit ws ticker --category linear --symbol BTCUSDT -o json | while read -r line; do
  LAST=$(echo "$line" | jq -r '.data.lastPrice // empty')
  [ -n "$LAST" ] && echo "BTC: $LAST"
done

Portfolio snapshot

bybit account balance -o json
bybit position list --category linear -o json | jq '[.list[] | {symbol, side, size, unrealisedPnl}]'

Dead man's switch

bybit trade cancel-after 60

Cancels all open orders if not refreshed within 60 seconds. Pass 0 to disable.

Morning brief

#!/bin/bash
echo "=== Balance ===" && bybit account balance
echo "=== Positions ===" && bybit position list --category linear
echo "=== BTC ===" && bybit market tickers --category linear --symbol BTCUSDT

Agent Skills

Ships with a growing agent skills library. See the full Skills Index.

Examples:

• account-snapshot for a quick balance and positions overview
• bybit-recipe-morning-brief for a reusable multi-market briefing workflow
• bybit-recipe-emergency-flatten for guarded position-exit playbooks

src/
  main.rs         — CLI entry point, clap parsing, exit codes
  lib.rs          — AppContext, Command enum, dispatch, apply_default_category
  auth.rs         — HMAC-SHA256 signing, timestamp, AuthHeaders
  config.rs       — Config file I/O, credential resolution, SecretValue wrapper
  client.rs       — HTTP client with retry, envelope parsing, rustls TLS
  errors.rs       — Unified error types with JSON envelopes
  paper.rs        — Paper trading state machine (market + limit orders)
  futures_paper.rs — Futures paper trading engine (margin, leverage, funding, liquidation)
  shell.rs        — Interactive REPL with rustyline
  telemetry.rs    — Instance ID, agent detection, request metadata
  commands/
    market.rs     — 17 public market data endpoints
    trade.rs      — Order management + batch ops + cancel-after
    account.rs    — Account info, balances, settings
    position.rs   — Position management
    asset.rs      — Asset transfers, deposits, withdrawals
    funding.rs    — Funding and wallet workflow aliases
    subaccount.rs — Master-account subaccount management
    futures.rs    — Derivatives-focused command namespace
    futures_paper.rs — Futures paper trading commands
    reports.rs    — Read-only reporting and history aliases
    websocket.rs  — WebSocket streaming with reconnect
    paper.rs      — Paper trading commands
    auth.rs       — Credential management (set/sign/test/show/reset)
    utility.rs    — Setup wizard
    helpers.rs    — Shared confirm(), build_params()
  mcp/            — MCP server, registry, and schema helpers
  output/
    json.rs       — JSON output
    table.rs      — comfy-table rendering

Development

cargo build                         # dev build
cargo build --release               # optimized build
cargo test                          # all tests
cargo clippy -- -D warnings         # lint
cargo audit -D warnings             # security advisories
cargo fmt                           # format

Live smoke tests are opt-in and do not run during normal cargo test.

BYBIT_RUN_LIVE_PUBLIC=1 cargo test --test live_smoke
BYBIT_RUN_LIVE_PUBLIC=1 BYBIT_RUN_LIVE_WS=1 cargo test --test live_smoke
BYBIT_RUN_LIVE_TESTNET=1 BYBIT_TESTNET_API_KEY=... BYBIT_TESTNET_API_SECRET=... cargo test --test live_smoke
BYBIT_RUN_LIVE_TESTNET=1 BYBIT_RUN_LIVE_WS=1 BYBIT_TESTNET_API_KEY=... BYBIT_TESTNET_API_SECRET=... cargo test --test live_smoke
BYBIT_RUN_LIVE_EARN=1 BYBIT_TESTNET_API_KEY=... BYBIT_TESTNET_API_SECRET=... cargo test --test live_smoke live_testnet_earn_positions_smoke

On PowerShell:

$env:BYBIT_RUN_LIVE_PUBLIC = "1"
cargo test --test live_smoke

$env:BYBIT_RUN_LIVE_TESTNET = "1"
$env:BYBIT_TESTNET_API_KEY = "..."
$env:BYBIT_TESTNET_API_SECRET = "..."
cargo test --test live_smoke

Contributing

Bug reports, feature requests, and pull requests are welcome. See CONTRIBUTING.md for contribution guidelines and repo conventions.

License & Disclaimer

MIT. See LICENSE.

This is unofficial community-maintained software. It interacts with the live Bybit exchange and can result in real financial transactions. Orders, withdrawals, and transfers are irreversible once processed. See DISCLAIMER.md for full terms and risk disclosure.