ritmex-bot/cli-guide.en.md

ritmex-bot CLI User Guide (English)

This guide documents the ritmex-bot command mode (agent-friendly mode), which lets you run structured trading operations without entering the Ink interactive menu.

1. Scope

ritmex-bot CLI command mode covers:

• Exchange listing and capability checks
• Market data (ticker / depth / kline)
• Account and position queries
• Open/create/cancel/cancel-all order operations
• Strategy execution (including dry-run)

This mode is suitable for:

• Manual terminal usage
• npx / bunx invocation
• Programmatic AI-agent workflows (recommended with --json)

2. Installation and Run Modes

2.1 Global install (recommended)

npm install -g ritmex-bot
ritmex-bot doctor

2.2 Quick run without install

npx ritmex-bot doctor
bunx ritmex-bot doctor

2.3 Local dependency

npm install ritmex-bot
npx ritmex-bot doctor

2.4 Run from repository source

bun run index.ts doctor
bun run index.ts market ticker --exchange binance --symbol BTCUSDT

Note: bin/ritmex-bot launches the entrypoint via bun run, so Bun must be available in the runtime environment.

3. Command Shape

ritmex-bot <root-command> <action> [options]

Supported root commands:

• help
• doctor
• exchange
• market
• account
• position
• order
• strategy

Quick help:

ritmex-bot help
ritmex-bot market ticker --help

4. Global Options

Option	Short	Description	Default
--exchange	-e	Exchange ID override	Existing env resolution
--symbol	-	Trading symbol (pass-through)	Existing env resolution
--json	-j	JSON output	false
--dry-run	-d	Simulate write operations	false
--timeout	-t	Timeout in milliseconds	25000
--help	-h	Show command help	false

5. Environment Variables and Symbol Rules

Command mode follows these constraints:

• No new environment variables are introduced.
• No existing environment-variable names are modified.
• Runtime values are read directly from the current CLI environment.
• If --exchange is not provided, exchange resolution follows the existing logic (for example EXCHANGE / TRADE_EXCHANGE).
• If --symbol is not provided, symbol resolution follows the existing exchange-specific env logic.
• Symbols are never normalized or rewritten by command mode.

That means symbol variants such as BTCUSDT, BTCUSDC, spot/perp pairs, and venue-specific naming are fully controlled by your existing environment configuration.

6. Command Reference

6.1 doctor

Checks effective exchange/symbol setup and runtime adapter capabilities.

ritmex-bot doctor
ritmex-bot doctor --exchange binance --symbol BTCUSDT --json

6.2 exchange

List supported exchanges

ritmex-bot exchange list

Inspect exchange capabilities

ritmex-bot exchange capabilities --exchange standx

If runtime adapter initialization fails, CLI falls back to static capability metadata (source: "static") and includes a warning.

6.3 market

market ticker

ritmex-bot market ticker --exchange binance --symbol BTCUSDT

market depth

ritmex-bot market depth --exchange binance --symbol BTCUSDT --levels 10

--levels is optional; when provided, depth levels are truncated to that value.

market kline

ritmex-bot market kline --exchange binance --symbol BTCUSDT --interval 1m --limit 50

Arguments:

• --interval is required
• --limit is optional (keeps the latest N candles)

6.4 account and position

Account snapshot

ritmex-bot account snapshot --exchange standx
ritmex-bot account summary --exchange standx

summary is an alias of snapshot.

Position list

ritmex-bot position list --exchange standx
ritmex-bot position list --exchange standx --symbol BTC-USD

If --symbol is provided, result positions are filtered by that symbol.

6.5 order

Open orders

ritmex-bot order open --exchange binance --symbol BTCUSDT

Create order

ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000

Create-order arguments:

Option	Required	Description
--side	Yes	buy / sell
--type	Yes	limit / market / stop / trailing-stop / close
--quantity or --qty	Yes	Order quantity
--price	Required for limit	Limit price
--stop-price	Required for stop	Stop trigger price
--activation-price	Required for trailing-stop	Trailing-stop activation price
--callback-rate	Required for trailing-stop	Trailing-stop callback rate
--time-in-force	No	GTC / IOC / FOK / GTX
--reduce-only	No	true/false
--close-position	No	true/false
--trigger-type	No	UNSPECIFIED / TAKE_PROFIT / STOP_LOSS
--sl-price	No	Stop-loss price (router applies venue capability rules)
--tp-price	No	Take-profit price (router applies venue capability rules)

Examples:

# Market order
ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type market --qty 0.01

# Stop order
ritmex-bot order create --exchange binance --symbol BTCUSDT --side sell --type stop --qty 0.01 --stop-price 86000

# Trailing-stop order
ritmex-bot order create --exchange binance --symbol BTCUSDT --side sell --type trailing-stop --qty 0.01 --activation-price 91000 --callback-rate 0.2

# Close intent order (defaults reduceOnly/closePosition in route layer)
ritmex-bot order create --exchange binance --symbol BTCUSDT --side sell --type close --qty 0.01

Cancel order

ritmex-bot order cancel --exchange binance --symbol BTCUSDT --order-id 123456

Cancel all orders

ritmex-bot order cancel-all --exchange binance --symbol BTCUSDT

If forceCancelAllOrders is available on the adapter, CLI uses it first; otherwise it falls back to standard cancel-all behavior.

6.6 strategy

Run strategy

ritmex-bot strategy run --strategy maker --exchange standx --silent

Supported strategy IDs:

• trend
• swing
• guardian
• maker
• maker-points
• offset-maker
• liquidity-maker
• basis
• grid

Supported aliases:

• offset -> offset-maker
• makerpoints / maker_points -> maker-points
• liquidity / liquiditymaker / liquidity_maker -> liquidity-maker

Extra options:

• --silent (short form -q) for quieter strategy startup logs
• --dry-run to propagate simulation mode into strategy execution

7. --dry-run Behavior

With --dry-run enabled:

• order create / order cancel / order cancel-all do not send real write operations.
• Response includes dryRunActions so you can inspect the simulated intent.
• strategy run receives dry-run mode in the strategy runner.
• Read-only commands (market/account/position queries) keep normal behavior.

Example:

ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000 --dry-run --json

8. Unsupported Features

Exchange capabilities are intentionally not forced into a fake unified surface. If a venue does not support a feature, CLI returns UNSUPPORTED directly.

Typical cases:

• Exchange does not implement queryOpenOrders
• Exchange does not implement queryAccountSnapshot
• Exchange-specific order type limitations

Callers should handle UNSUPPORTED as a first-class outcome.

9. Output and Exit Codes

9.1 Human-readable output (default)

Success:

[OK] market-ticker
time: 2026-02-27T12:00:00.000Z
exchange: binance
symbol: BTCUSDT
dryRun: false
...

Failure:

[ERROR] order-open
time: 2026-02-27T12:00:00.000Z
code: UNSUPPORTED
message: queryOpenOrders is not supported on exchange 'aster'
retryable: false

9.2 JSON output (--json)

Success payload:

{
  "success": true,
  "command": "market-ticker",
  "exchange": "binance",
  "symbol": "BTCUSDT",
  "dryRun": false,
  "ts": "2026-02-27T12:00:00.000Z",
  "data": {}
}

Failure payload:

{
  "success": false,
  "command": "order-open",
  "exchange": "aster",
  "symbol": "BTCUSDT",
  "dryRun": false,
  "ts": "2026-02-27T12:00:00.000Z",
  "error": {
    "code": "UNSUPPORTED",
    "message": "queryOpenOrders is not supported on exchange 'aster'",
    "retryable": false
  }
}

9.3 Exit codes

Exit Code	Meaning
0	Success
2	Invalid arguments (INVALID_ARGS)
3	Missing environment setup (MISSING_ENV)
5	Unsupported feature (UNSUPPORTED)
6	Exchange execution error (EXCHANGE_ERROR)
7	Timeout (TIMEOUT)

10. Recommended AI-Agent Flow

# 1) Check venue capabilities
ritmex-bot exchange capabilities --exchange binance --json

# 2) Fetch market state
ritmex-bot market ticker --exchange binance --symbol BTCUSDT --json

# 3) Validate order parameters with dry-run
ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000 --dry-run --json

# 4) Submit live order after validation (remove --dry-run)
ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000 --json

11. Compatibility With Existing Features

Command mode does not break existing interactive or legacy startup flows:

• bun run index.ts still opens the Ink menu
• bun run index.ts --strategy trend --silent still starts strategy directly
• Command mode is used only when the first argument matches command roots (for example market, order, strategy)

If you already run the project with current env variables and strategy configs, command mode can be adopted incrementally with no env-key migration.