> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitflare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OrbitFlare CLI

> Full-featured command-line interface for OrbitFlare. Streaming, querying, scaffolding, account management, and a built-in TUI dashboard, all from your terminal.

The OrbitFlare CLI is the single entry point for everything a developer needs: streaming on-chain data via gRPC, querying the blockchain, scaffolding projects from templates, and managing your account through an interactive dashboard.

<Tip>
  The CLI stores credentials in your OS keychain and supports multiple auth profiles, so you can switch between accounts or networks instantly.
</Tip>

## Installation

<Tabs>
  <Tab title="Cargo (recommended)">
    ```bash theme={null}
    cargo install orbitflare
    ```
  </Tab>

  <Tab title="From source">
    ```bash theme={null}
    git clone https://github.com/orbitflare/orbit-cli.git
    cd orbit-cli
    cargo install --path .
    ```
  </Tab>
</Tabs>

Requires **Rust 1.85+**. Verify the installation:

```bash theme={null}
orbitflare --version
```

## Quick Start: Existing Users

If you already have an OrbitFlare account and API key from the [dashboard](https://orbitflare.com/dashboard):

```bash theme={null}
# Authenticate with your API key
orbitflare auth login --x-orbit-key YOUR_API_KEY

# Point the CLI to your RPC endpoint (from your dashboard)
orbitflare config set rpc.url ORBITFLARE_RPC_URL

# Verify everything works
orbitflare ping
orbitflare rpc slot
```

<Note>
  A fresh install starts with an empty config. After login, set at least `rpc.url` so commands like `ping` and `rpc` know where to connect. Your endpoint URLs are available in the **Services** section of your [dashboard](https://orbitflare.com/dashboard).
</Note>

Endpoint URLs follow this format:

| Protocol           | Format                                     | Example                               |
| ------------------ | ------------------------------------------ | ------------------------------------- |
| RPC                | `http://{region}.rpc.orbitflare.com`       | `http://ams.rpc.orbitflare.com`       |
| WS                 | `ws://{region}.rpc.orbitflare.com`         | `ws://ams.rpc.orbitflare.com`         |
| gRPC (Yellowstone) | `http://{region}.rpc.orbitflare.com:10000` | `http://ams.rpc.orbitflare.com:10000` |
| Jetstream          | `http://{region}.jetstream.orbitflare.com` | `http://ams.jetstream.orbitflare.com` |

## Quick Start: New Users

<Steps>
  <Step title="Create an Account">
    Sign up at [orbitflare.com](https://orbitflare.com) and choose a plan.
  </Step>

  <Step title="Authenticate">
    The CLI supports three login methods. Pick the one that suits your workflow:

    ```bash theme={null}
    # API key (from orbitflare.com/dashboard)
    orbitflare auth login --x-orbit-key YOUR_API_KEY

    # Solana wallet keypair
    orbitflare auth login --wallet ~/.config/solana/id.json

    # Device flow (opens browser)
    orbitflare auth login
    ```

    The CLI fetches and stores your RPC license key automatically during login. To set it manually:

    ```bash theme={null}
    orbitflare auth set-license-key YOUR_LICENSE_KEY
    ```

    <Warning>
      Keep your API key and license key secret. Do not commit them to version control or expose them in client-side code.
    </Warning>
  </Step>

  <Step title="Configure Your Endpoints">
    A fresh install starts with an empty config. Point the CLI to your OrbitFlare endpoints:

    Your endpoint URLs are in the **Services** section of your [dashboard](https://orbitflare.com/dashboard). They follow the format `http://{region}.rpc.orbitflare.com`.

    ```bash theme={null}
    # Set your RPC endpoint
    orbitflare config set rpc.url ORBITFLARE_RPC_URL

    # (Optional) Set streaming endpoints
    orbitflare config set grpc.url ORBITFLARE_GRPC_URL
    orbitflare config set jetstream.url ORBITFLARE_JETSTREAM_URL

    # Verify connectivity
    orbitflare ping
    ```

    See [Authentication & Limits](/authentication) for all available region endpoints.
  </Step>

  <Step title="Start Building">
    ```bash theme={null}
    # Query your SOL balance
    orbitflare rpc balance YOUR_WALLET_ADDRESS

    # Get current slot
    orbitflare rpc slot

    # Scaffold a project
    orbitflare template --list
    orbitflare template --install solana-copy-trader

    # Launch the TUI dashboard
    orbitflare dashboard
    ```
  </Step>
</Steps>

## Authentication

Credentials are stored securely in your OS keychain. The CLI supports multiple named profiles so you can manage separate accounts or environments.

```bash theme={null}
# Check current auth status
orbitflare auth status

# Switch profile
orbitflare auth switch --profile work

# Log out
orbitflare auth logout
```

### Auth Methods

<Tabs>
  <Tab title="API Key">
    Authenticate with your API key from the [dashboard](https://orbitflare.com/dashboard). The key is passed via the `X-ORBIT-KEY` header to the Customer API.

    ```bash theme={null}
    orbitflare auth login --x-orbit-key YOUR_API_KEY
    ```
  </Tab>

  <Tab title="Wallet">
    Authenticate by signing a challenge with your Solana keypair. If the wallet is not linked to an account, the CLI will walk you through registration.

    ```bash theme={null}
    orbitflare auth login --wallet ~/.config/solana/id.json
    ```
  </Tab>

  <Tab title="Device Flow">
    Opens your browser for OAuth-style authentication. Ideal for interactive use.

    ```bash theme={null}
    orbitflare auth login
    ```

    The CLI displays a verification URL and code, polls for completion, then stores the session token automatically.
  </Tab>
</Tabs>

### Key Resolution Order

1. `--x-orbit-key` flag on the command (highest priority)
2. `--profile` flag to select a stored profile
3. Default profile in `~/.orbitflare/config.yml`

## Command Reference

The CLI has top-level commands spanning authentication, configuration, blockchain queries, real-time streaming, project scaffolding, and account management.

### Core Commands

| Command                        | Description                                          |
| ------------------------------ | ---------------------------------------------------- |
| `auth login`                   | Authenticate (API key, wallet, or device flow)       |
| `auth logout`                  | Remove stored credentials                            |
| `auth status`                  | Show current authentication status                   |
| `auth switch --profile <NAME>` | Switch to a different auth profile                   |
| `auth set-license-key <KEY>`   | Store RPC license key for current profile            |
| `config show`                  | Display all configuration values                     |
| `config set <KEY> <VALUE>`     | Set a configuration value                            |
| `config remove <KEY> <VALUE>`  | Remove a value from a list config                    |
| `config reset`                 | Reset config to defaults (preserves auth)            |
| `ping`                         | Check connectivity to all configured services        |
| `ping --service <SVC>`         | Ping a specific service (`rpc`, `jetstream`, `grpc`) |
| `docs [TOPIC...]`              | Open documentation in your browser                   |
| `plan list`                    | List available RPC plans                             |
| `plan view <SLUG>`             | View plan details                                    |
| `plan compare --all`           | Compare all plans side by side                       |
| `pay check-balance`            | Check account balance                                |
| `pay topup <AMOUNT>`           | Top up balance with USDC (on-chain)                  |
| `pay history`                  | Top-up / credit history                              |
| `pay purchase <SLUG> <PERIOD>` | Purchase a plan from balance                         |
| `pay order --history`          | List orders                                          |
| `pay order <REF>`              | View order details                                   |
| `pay invoice --list`           | List invoices                                        |
| `pay invoice <REF>`            | View invoice details                                 |
| `pay renew <INVOICE>`          | Pay invoice from balance (renewal)                   |

### RPC Commands

Query the Solana blockchain directly from your terminal.

```bash theme={null}
orbitflare rpc account <ADDRESS>
orbitflare rpc tokens <WALLET>
orbitflare rpc balance <ADDRESS>
orbitflare rpc tx <SIGNATURE>
orbitflare rpc history <WALLET> --limit 20
orbitflare rpc program-accounts <PROGRAM_ID> --limit 10
orbitflare rpc slot
orbitflare rpc epoch
orbitflare rpc blockhash
orbitflare rpc stats
orbitflare rpc priority-fees --account <ADDRESS>
orbitflare rpc raw '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[]}'
```

### WebSocket Commands

Subscribe to live Solana pubsub events over WebSocket. Each subscription runs until you press `Ctrl+C` and prints events as they arrive (use `--json` for machine-readable output).

```bash theme={null}
# Live slot updates
orbitflare ws slot

# Account changes for a specific address
orbitflare ws account <ADDRESS>

# Transaction logs mentioning one or more addresses (omit --mentions for all)
orbitflare ws logs --mentions <ADDRESS> --mentions <ANOTHER>

# Confirmation of a single transaction signature
orbitflare ws signature <SIGNATURE>
```

The endpoint is derived from your configured `rpc.url`: `http://` becomes `ws://` and `https://` becomes `wss://`. To target a different host for a single command, pass `--ws-url`:

```bash theme={null}
orbitflare ws slot --ws-url ws://ams.rpc.orbitflare.com
```

### Streaming Commands

Stream real-time Solana data over gRPC. Both commands take a YAML config file that defines your filters and reconnection strategy.

<Tabs>
  <Tab title="Jetstream">
    ```bash theme={null}
    orbitflare jet --config stream.yml
    ```

    Jetstream provides ultra-low-latency transaction and account streaming.

    ```yaml stream.yml theme={null}
    transactions:
      pump_trades:
        account_include:
          - "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"

    accounts:
      my_wallet:
        account:
          - "YOUR_WALLET_ADDRESS"

    reconnect:
      initial_delay_ms: 100
      max_delay_ms: 30000
      multiplier: 2.0
      max_retries: 0    # 0 = unlimited
    ```
  </Tab>

  <Tab title="Yellowstone gRPC">
    ```bash theme={null}
    orbitflare grpc --config grpc-stream.yml
    ```

    Yellowstone provides the complete Geyser plugin data stream including slots and block metadata.

    ```yaml grpc-stream.yml theme={null}
    transactions:
      jupiter_swaps:
        account_include:
          - "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"
        vote: false
        failed: false

    slots:
      all_slots:
        filter_by_commitment: true

    commitment: confirmed

    reconnect:
      initial_delay_ms: 100
      max_delay_ms: 30000
      multiplier: 2.0
      max_retries: 0
    ```
  </Tab>
</Tabs>

Both streaming commands support automatic endpoint failover and exponential backoff reconnection. Environment variables can be used in config files with `${VAR}` syntax.

### Template Commands

Scaffold projects from production-ready starter templates.

```bash theme={null}
# List all templates
orbitflare template --list

# Filter by language
orbitflare template --list --filter rust

# View template details
orbitflare template --view solana-copy-trader

# Install a template
orbitflare template --install solana-copy-trader --dir ./my-bot
```

Templates are fetched from the [orbitflare/templates](https://github.com/orbitflare/templates) repository and cached locally for offline use.

### Plan Commands

Browse and compare available RPC plans. Plan data is cached locally for 6 hours.

```bash theme={null}
# List all plans (sorted by price)
orbitflare plan list

# View plan details
orbitflare plan view <SLUG>

# Compare all plans side by side
orbitflare plan compare --all

# Compare specific plans
orbitflare plan compare dev growth
```

### Payment Commands

Manage your account balance, purchase plans, and handle invoices. Only `topup` requires a Solana wallet — everything else uses your account balance.

```bash theme={null}
# Check account balance
orbitflare pay check-balance

# Top up balance with USDC (on-chain)
orbitflare pay topup <AMOUNT> --wallet ~/.config/solana/id.json

# Top-up / credit history
orbitflare pay history

# Purchase a plan from balance
orbitflare pay purchase <SLUG> <PERIOD> --coupon <CODE>

# View orders
orbitflare pay order --history
orbitflare pay order <REFERENCE>

# View invoices
orbitflare pay invoice --list
orbitflare pay invoice <REFERENCE>

# Pay an invoice from balance (renewal)
orbitflare pay renew <INVOICE_REF>
```

The `topup` command defaults to `~/.config/solana/id.json` for the wallet keypair. Use `--wallet` to specify a different path. Billing periods: `monthly`, `quarterly`, `semi-annual`, `annual`.

<Note>
  The `purchase` command runs a dry-run validation first, showing you the pricing breakdown and whether your balance is sufficient before confirming.
</Note>

### Dashboard

Launch an interactive TUI for managing your OrbitFlare account without leaving the terminal.

```bash theme={null}
orbitflare dashboard
```

The dashboard provides full keyboard-driven access to your profile, services, API keys, and invoices.

<AccordionGroup>
  <Accordion title="Navigation keybinds">
    | Key         | Action                   |
    | ----------- | ------------------------ |
    | `q`         | Quit                     |
    | `Esc`       | Back                     |
    | `Tab`       | Switch tab / focus       |
    | `↑↓` / `jk` | Navigate                 |
    | `Enter`     | Select / expand / toggle |
    | `t` / `T`   | Cycle theme              |
    | `[`         | Toggle sidebar           |
    | `R`         | Refresh data             |
  </Accordion>

  <Accordion title="Service management keybinds">
    | Key | Tab           | Action                          |
    | --- | ------------- | ------------------------------- |
    | `m` | Details       | Toggle auth mode (IP / API Key) |
    | `w` | Details       | Toggle auto-renewal             |
    | `r` | Details       | Regenerate license key          |
    | `n` | IPs / Domains | Switch Mainnet / Devnet         |
    | `a` | IPs / Domains | Add IP or domain                |
    | `d` | IPs / Domains | Remove IP or domain             |
  </Accordion>

  <Accordion title="API key management keybinds">
    | Key | Action                    |
    | --- | ------------------------- |
    | `c` | Create new API key        |
    | `e` | Toggle enabled / disabled |
    | `r` | Regenerate key            |
    | `x` | Delete key                |
    | `a` | Add IP (when expanded)    |
    | `d` | Remove IP (when expanded) |
  </Accordion>

  <Accordion title="Invoice & profile keybinds">
    | Key | Section  | Action                       |
    | --- | -------- | ---------------------------- |
    | `p` | Invoices | Pay with account balance     |
    | `e` | Profile  | Edit name and payment wallet |
  </Accordion>
</AccordionGroup>

## JSON Output

All commands support `--json` for machine-readable output, making the CLI easy to integrate into scripts and automation pipelines.

```bash theme={null}
orbitflare rpc slot --json
orbitflare rpc balance Gh9ZwEm... --json
orbitflare auth status --json
```

Example output:

```json theme={null}
{
  "confirmed": 312849571,
  "finalized": 312849539
}
```

## Configuration

Configuration is stored in `~/.orbitflare/config.yml`. Manage it with the `config` command:

```bash theme={null}
# View current config
orbitflare config show

# Set network
orbitflare config set network devnet

# Set RPC endpoint
orbitflare config set rpc.url http://ams.rpc.orbitflare.com

# Set gRPC and Jetstream endpoints
orbitflare config set grpc.url http://ams.rpc.orbitflare.com:10000
orbitflare config set jetstream.url http://ams.jetstream.orbitflare.com

# Set commitment level
orbitflare config set commitment finalized

# Change TUI theme
orbitflare config set theme dracula

# Set template repository
orbitflare config set templates.repo https://github.com/your-org/templates

# Reset to defaults
orbitflare config reset
```

Devnet endpoints are preconfigured by default:

* **RPC:** `http://devnet.rpc.orbitflare.com` (fallback: `https://api.devnet.solana.com`)
* **gRPC:** `http://devnet.rpc.orbitflare.com:10000`

Use `--network devnet` to switch at runtime.

### File Locations

```bash theme={null}
~/.orbitflare/
├── config.yml                  # Main configuration
├── templates_cache.json        # Template registry cache
└── cache/
    └── rpc-plans.json          # Plans cache (6-hour TTL)
```

API keys, tokens, and license keys are stored in your **OS Keychain**, not on disk.

## Global Flags

These flags work with every command and override the corresponding config value for that invocation.

| Flag                   | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| `--json`               | Output raw JSON                                               |
| `--raw`                | Minimal output, no formatting                                 |
| `--network <NET>`      | Override network (`mainnet` / `devnet` / `testnet`)           |
| `--commitment <C>`     | Override commitment (`processed` / `confirmed` / `finalized`) |
| `--rpc-url <URL>`      | Override RPC endpoint                                         |
| `--grpc-url <URL>`     | Override gRPC endpoint                                        |
| `--ws-url <URL>`       | Override WebSocket endpoint (default: derived from RPC URL)   |
| `--fallback-url <URL>` | Fallback URLs (repeatable)                                    |
| `--profile <NAME>`     | Use a specific auth profile                                   |
| `--quiet`              | Suppress non-essential output                                 |
| `--no-color`           | Disable colored output                                        |

## Full Workflow Example

A complete walkthrough from installation to querying:

```bash theme={null}
# 1. Install the CLI
cargo install orbitflare

# 2. Authenticate
orbitflare auth login --x-orbit-key YOUR_API_KEY

# 3. Configure endpoints (from your dashboard)
orbitflare config set rpc.url ORBITFLARE_RPC_URL
orbitflare config set grpc.url ORBITFLARE_GRPC_URL

# 4. Verify connectivity
orbitflare ping

# 5. Query the blockchain
orbitflare rpc slot
orbitflare rpc balance YOUR_WALLET_ADDRESS

# 6. Scaffold a project
orbitflare template --install solana-copy-trader --dir ./my-bot

# 7. Stream real-time data
orbitflare jet --config stream.yml
```

## What's Next?

<CardGroup cols={2}>
  <Card title="RPC Methods" icon="server" href="/rpc/http">
    Explore the full Solana RPC method reference.
  </Card>

  <Card title="Jetstream Streaming" icon="bolt" href="/data-streaming/jetstream">
    Learn about real-time gRPC data streaming.
  </Card>

  <Card title="Yellowstone gRPC" icon="satellite-dish" href="/data-streaming/yellowstone">
    Complete Geyser plugin data via Yellowstone.
  </Card>

  <Card title="Starter Templates" icon="rectangle-terminal" href="https://github.com/orbitflare/templates">
    Browse production-ready project templates.
  </Card>
</CardGroup>

## Support

<CardGroup cols={2}>
  <Card title="Discord" icon="discord" href="https://discord.gg/orbitflare">
    Join the community for help and discussions.
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/orbitflare/orbit-cli">
    Report issues or contribute to the CLI.
  </Card>
</CardGroup>