npm package: @nadohq/nado-cli
Description: CLI for the Nado Protocol
Latest version: 0.1.3

# nado-cli

![version](https://img.shields.io/npm/v/@nadohq/nado-cli?color=blue)
![platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)

CLI for the [Nado Protocol](https://nado.xyz) — perpetual futures, spot trading, and liquidity provision on the Ink blockchain.

Full protocol access. Mainnet and testnet. Cross and isolated margin.

Pair with [`@nadohq/nado-mcp`](https://github.com/nadohq/nado-mcp) for MCP server support in Cursor, Claude, Codex, Copilot, Gemini, Goose, and other agents.

> [!CAUTION]
> Experimental software. Interacts with the live Nado Protocol on the Ink blockchain and can execute real financial transactions including leveraged perpetual futures. Read [DISCLAIMER.md](DISCLAIMER.md) before using with real funds or AI agents.

## Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [What You Can Trade](#what-you-can-trade)
- [Commands](#commands)
- [Configuration](#configuration)
- [For AI Agents](#for-ai-agents)
- [Examples](#examples)
- [Development](#development)
- [Disclaimer](#disclaimer)

## Installation

Requires [Bun](https://bun.sh) or [Node.js](https://nodejs.org/) 18+.

### bun

```bash
bun install -g @nadohq/nado-cli
```

### npm

```bash
npm install -g @nadohq/nado-cli
```

### Run without installing

```bash
bunx @nadohq/nado-cli --help
# or
npx @nadohq/nado-cli --help
```

Verify it works:

```bash
nado --version
nado market list --format json
```

<details>
<summary>Build from source</summary>

```bash
git clone https://github.com/nadohq/nado-cli.git
cd nado-cli
bun install
bun run build
bun link        # makes `nado` available globally
```

</details>

## Quick Start

Public market data requires no credentials:

```bash
nado market list                              # All available markets
nado market price BTC                         # Best bid/ask
nado market tickers --market perp             # 24h perp tickers
nado market candles BTC --period 3600         # 1h OHLCV candles
nado market orderbook BTC --depth 20          # Orderbook depth
```

With authentication (see [Configuration](#configuration)):

```bash
nado account summary                          # Balances, health, positions
nado trade long BTC 0.01                      # Market long BTC-PERP
nado trade buy ETH 1.0                        # Market buy ETH spot
nado trade close BTC                          # Close a position
```

For humans (interactive setup, REPL):

```bash
nado setup                                    # 1-click trading wizard
nado shell                                    # Interactive REPL
nado account summary                          # Table output by default
```

## What You Can Trade

One CLI covers perps, spot, and liquidity provision on the Nado Protocol.

| Asset class | Description | Margin | Example |
|---|---|---|---|
| **Perpetual futures** | BTC, ETH, SOL, and more | Cross or isolated, configurable leverage | `nado trade long BTC 0.01 -m isolated --leverage 10` |
| **Spot** | Buy and sell tokens directly | — | `nado trade buy ETH 1.0 -p 2500` |
| **NLP vault** | Provide liquidity, earn yield | — | `nado nlp mint 1000` |

Spot product IDs are even (0, 2, 4…). Perp product IDs are odd (1, 3, 5…). Product 0 is USDT0 (the quote token). Use `nado market list` to discover all available markets and their product IDs.

## Commands

~40 commands across 8 groups.

| Group | Commands | Auth | Description |
|-------|----------|------|-------------|
| market | 7 | No | Prices, orderbook, candles, funding, tickers |
| account | 6 | Yes | Balances, positions, orders, history, fees, stats |
| trade | 14 | Yes | Long, short, buy, sell, close, cancel, TWAP, triggers, TP/SL |
| funds | 3 | Yes | Deposit, withdraw, transfer between subaccounts |
| nlp | 5 | Yes | NLP vault: info, balance, mint, burn, snapshots |
| auth | 3 | Mixed | Credential management, linked signers |
| setup | 1 | No | Interactive 1-click trading wizard |
| shell | 1 | No | Interactive REPL |

14 commands are write operations (orders, closes, cancels, deposits, withdrawals, transfers, mints, burns). All write commands show a confirmation summary before executing. Use `-y` / `--force` to skip confirmations (use with caution).

<details>
<summary>Full command reference</summary>

### Market Data (Public)

| Command | Description |
|---------|-------------|
| `nado market list` | List all available markets |
| `nado market price <MARKET>` | Best bid/ask for a market |
| `nado market prices <MARKET...>` | Bid/ask for multiple markets |
| `nado market orderbook <MARKET> [--depth 10] [--watch]` | Orderbook depth (with optional live WebSocket mode) |
| `nado market candles <MARKET> [--period 3600] [--limit 20]` | OHLCV candlestick data |
| `nado market funding <MARKET>` | Current funding rate for a perp market |
| `nado market tickers [--market spot\|perp]` | 24h ticker data for all markets |

### Account Data (Private)

| Command | Description |
|---------|-------------|
| `nado account summary` | Subaccount summary with balances and health |
| `nado account positions` | All open perp positions (cross and isolated) |
| `nado account orders [MARKET...]` | Open orders (all or filtered by market) |
| `nado account history [--limit 100] [--product-ids BTC,ETH]` | Historical orders (filled, cancelled, expired) |
| `nado account fees` | Maker/taker fee rates |
| `nado account stats [--days 30] [--product-ids BTC]` | Trading statistics over a time period |

### Trading (Private)

| Command | Description |
|---------|-------------|
| `nado trade long <MARKET> <AMOUNT> [-p PRICE] [-m cross\|isolated] [--leverage N] [--tp PRICE] [--sl PRICE]` | Perp long order |
| `nado trade short <MARKET> <AMOUNT> [-p PRICE] [-m cross\|isolated] [--leverage N] [--tp PRICE] [--sl PRICE]` | Perp short order |
| `nado trade buy <MARKET> <AMOUNT> [-p PRICE] [--no-borrow]` | Spot buy order |
| `nado trade sell <MARKET> <AMOUNT> [-p PRICE] [--no-borrow]` | Spot sell order |
| `nado trade tp <MARKET> <TRIGGER_PRICE> [AMOUNT] [-p PRICE]` | Take-profit on existing position |
| `nado trade sl <MARKET> <TRIGGER_PRICE> [AMOUNT] [-p PRICE]` | Stop-loss on existing position |
| `nado trade close <MARKET> [--slippage PCT]` | Close an open position |
| `nado trade close-all [--side long\|short] [--product-ids IDS]` | Close all open positions |
| `nado trade cancel <MARKET> <DIGEST...>` | Cancel specific orders by digest |
| `nado trade cancel-all <MARKET>` | Cancel all orders and triggers for a market |
| `nado trade cancel-trigger <MARKET> <DIGEST...>` | Cancel specific trigger orders |
| `nado trade cancel-trigger-all <MARKET>` | Cancel all trigger orders for a market |
| `nado trade cancel-and-place <MARKET> <SIDE> <AMOUNT> --cancel-digests D --cancel-market M [-p PRICE]` | Atomic cancel + place |
| `nado trade twap <MARKET> <SIDE> <AMOUNT> <DURATION_MIN> [--interval SEC]` | TWAP order split across time |
| `nado trade trigger <MARKET> <SIDE> <AMOUNT> --trigger-price P --trigger-type TYPE [-p PRICE]` | Conditional trigger order |

### Funds (Private)

| Command | Description |
|---------|-------------|
| `nado funds deposit <AMOUNT> [--product-id 0]` | Deposit collateral from wallet into subaccount |
| `nado funds withdraw <AMOUNT> [--product-id 0]` | Withdraw collateral from subaccount to wallet |
| `nado funds transfer <AMOUNT> [--from NAME] [--to NAME]` | Transfer USDT0 between subaccounts |

### NLP Vault (Private)

| Command | Description |
|---------|-------------|
| `nado nlp info` | NLP vault pool info and current state |
| `nado nlp balance` | Locked/unlocked NLP balances |
| `nado nlp mint <AMOUNT>` | Deposit USDT0 to mint NLP tokens |
| `nado nlp burn <AMOUNT>` | Burn NLP tokens to withdraw USDT0 |
| `nado nlp snapshots [--granularity 86400] [--limit 100]` | Historical vault snapshots |

### Auth & Utility

| Command | Description |
|---------|-------------|
| `nado auth set [KEY] [VALUE]` | Configure credentials and defaults |
| `nado auth whoami` | Show current identity and config |
| `nado auth link-signer <ADDRESS>` | Link a signer for 1-click trading |
| `nado setup` | Interactive 1-click trading setup wizard |
| `nado shell` | Interactive REPL with tab completion and history |

</details>

## Configuration

Settings are resolved with this precedence: **CLI flags > environment variables > config file > defaults**.

### Config file

Store credentials in `~/.config/nado/config.toml`:

```toml
[default]
data_env = "nadoMainnet"        # nadoMainnet | nadoTestnet
subaccount_name = "default"

[credentials]
private_key = "0x..."
subaccount_owner = "0x..."      # only needed when using a linked signer
```

Or use the interactive wizard: `nado setup` or `nado auth set`.

### Environment variables

| Variable | Description |
|---|---|
| `PRIVATE_KEY` | Wallet or linked signer private key |
| `SUBACCOUNT_OWNER` | Explicit subaccount owner address |
| `SUBACCOUNT_NAME` | Subaccount name (default: `"default"`) |
| `DATA_ENV` | `nadoMainnet` or `nadoTestnet` |
| `RPC_URL` | Custom RPC endpoint |
| `NADO_FORMAT` | Default output format: `table` or `json` |

### Global CLI flags

```
--format <format>       Output format: table or json
--network <network>     Data environment: nadoMainnet or nadoTestnet
--owner <address>       Subaccount owner address
--subaccount <name>     Subaccount name
-y, --force             Skip confirmation prompts
--dry-run               Show what would be executed without submitting
```

Output defaults to `table` in a terminal (TTY) and `json` when piped.

### Security

- Config file is created with restricted permissions
- Private keys are never logged, printed in output, or included in error messages
- Use linked signers (1-click trading via `nado setup`) instead of your main wallet key
- The linked signer is a hot key with limited scope — your main wallet key is never stored
- For automation, prefer environment variables over config files
- The `--dry-run` flag lets you inspect what would execute without submitting transactions

## For AI Agents

If you're an AI agent or building one, the CLI is designed for structured, programmatic use:

```bash
nado <command> [args...] --format json 2>/dev/null
```

- stdout is always valid JSON on success or a structured error on failure.
- Exit code 0 means success. Non-zero means failure.
- stderr carries diagnostics only. Never parse stderr for data.
- All write operations show a confirmation summary. Use `-y` to skip for automation.
- Market resolution is flexible: use symbols (`BTC`, `ETH`), full names (`BTC-PERP`), or product IDs (`1`, `2`).

**Agent invocation pattern:**

```bash
# Read operations — no confirmation needed
nado market price BTC --format json 2>/dev/null
nado account summary --format json 2>/dev/null

# Write operations — use -y to skip interactive confirmation
nado trade long BTC 0.01 -y --format json 2>/dev/null
nado trade close BTC -y --format json 2>/dev/null
```

## Examples

### Market long with TP/SL

```bash
nado trade long BTC 0.01 --tp 75000 --sl 60000
```

### Isolated margin with leverage

```bash
nado trade long SOL 10 -m isolated --leverage 5
```

### Limit order

```bash
nado trade short ETH 0.5 -p 2500 --tif post_only
```

### TWAP over 10 minutes

```bash
nado trade twap BTC long 0.1 10 --interval 30
```

### Quick portfolio check (JSON, pipe to jq)

```bash
nado account summary --format json | jq '.health'
nado account positions --format json | jq '.crossPositions'
```

### Live orderbook streaming

```bash
nado market orderbook BTC --watch
```

### Paper-style exploration (testnet)

```bash
nado --network nadoTestnet account summary
nado --network nadoTestnet trade long BTC 0.01
```

### Interactive REPL

```bash
nado shell
```

```
nado> market price BTC
┌────────────┬─────────┬───────┬───────┐
│ Market     │ Product │ Bid   │ Ask   │
├────────────┼─────────┼───────┼───────┤
│ BTC-PERP   │ 2       │ 72410 │ 72411 │
└────────────┴─────────┴───────┴───────┘
nado> account fees
nado> help
nado> exit
```

<details>
<summary>Output & Errors</summary>

### JSON (`--format json`)

The primary output format for agents. Every command returns valid JSON on stdout.

```bash
nado market price BTC --format json
```

### Table (`--format table`)

Human-readable tables. Default when running in a terminal (TTY).

```
┌────────────┬─────────┬───────┬───────┐
│ Market     │ Product │ Bid   │ Ask   │
├────────────┼─────────┼───────┼───────┤
│ BTC-PERP   │ 2       │ 72410 │ 72411 │
└────────────┴─────────┴───────┴───────┘
```

### Auto-detection

When stdout is a TTY, output defaults to `table`. When piped (`| jq .`), it defaults to `json`. Override with `--format`.

### Write operation confirmations

All write operations (orders, cancels, deposits, withdrawals, transfers, mints, burns) display a summary and prompt for confirmation before executing:

```
  Long 0.01 BTC-PERP
  Type:     market
  Margin:   cross
  Slippage: 2%

  Proceed? (y/N)
```

Use `-y` / `--force` to skip. Use `--dry-run` to see the summary without executing.

</details>

<details>
<summary>Troubleshooting</summary>

**"Private key not configured" or authentication errors**

Run `nado setup` to configure 1-click trading, or set `PRIVATE_KEY` and `SUBACCOUNT_OWNER` environment variables. Verify with `nado auth whoami`.

**"No market found" for a symbol**

Use `nado market list` to see all available markets. You can use symbols (`BTC`), names (`BTC-PERP`), or product IDs (`1`).

**Transaction fails or reverts**

Check your subaccount balance with `nado account summary`. Ensure sufficient margin for the order size and leverage. For deposits, ensure your wallet has the token balance and enough native token for gas.

**Orderbook errors on some products**

Some protocol products (e.g. NLP pool token) exist on-chain but have no orderbook. The CLI handles this gracefully when querying all markets.

**Shell history not saving**

History is stored in `~/.config/nado/history`. Ensure the directory exists and is writable.

</details>

## Development

```bash
bun install          # install dependencies
bun run dev          # watch mode (rebuilds on change)
bun run build        # production build
bun run test         # run tests
bun run typecheck    # type checking
bun run lint         # lint + format
```

## Disclaimer

See [DISCLAIMER.md](DISCLAIMER.md).