> ## 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

> OrbitFlare 全功能命令行：流式传输、查询、脚手架、账户管理与内置 TUI 控制台，尽在终端。

OrbitFlare CLI 是开发者所需能力的单一入口：通过 gRPC 流式传输链上数据、查询区块链、从模板脚手架项目，以及通过交互式控制台管理账户。

<Tip>
  CLI 将凭证存储在操作系统钥匙串中，并支持多个认证配置文件，便于在账户或网络间即时切换。
</Tip>

## 安装

<Tabs>
  <Tab title="Cargo（推荐）">
    ```bash theme={null}
    cargo install orbitflare
    ```
  </Tab>

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

需要 **Rust 1.85+**。验证安装：

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

## 快速开始：已有用户

若你已有 OrbitFlare 账户及 [控制台](https://orbitflare.com/dashboard) 中的 API 密钥：

```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>
  全新安装的配置为空。登录后至少设置 `rpc.url`，以便 `ping` 与 `rpc` 等命令知道连接哪里。端点 URL 见 [控制台](https://orbitflare.com/dashboard) 的 **Services（服务）** 部分。
</Note>

端点 URL 格式如下：

| 协议                | 格式                                         | 示例                                    |
| ----------------- | ------------------------------------------ | ------------------------------------- |
| 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` |

## 快速开始：新用户

<Steps>
  <Step title="创建账户">
    在 [orbitflare.com](https://orbitflare.com) 注册并选择套餐。
  </Step>

  <Step title="认证">
    CLI 支持三种登录方式，按你的工作流选择：

    ```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
    ```

    CLI 在登录过程中会自动获取并存储 RPC 许可证密钥。手动设置：

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

    <Warning>
      请妥善保管 API 密钥与许可证密钥，勿提交到版本库，勿暴露在客户端代码中。
    </Warning>
  </Step>

  <Step title="配置端点">
    全新安装的配置为空。将 CLI 指向 OrbitFlare 端点：

    端点 URL 在 [控制台](https://orbitflare.com/dashboard) 的 **Services（服务）** 部分，格式为 `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
    ```

    全部可用区域端点见 [身份验证与限制](/cn/authentication)。
  </Step>

  <Step title="开始构建">
    ```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>

## 身份验证

凭证安全存储在操作系统钥匙串中。CLI 支持多个命名配置文件，便于管理不同账户或环境。

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

# Switch profile
orbitflare auth switch --profile work

# Log out
orbitflare auth logout
```

### 认证方式

<Tabs>
  <Tab title="API 密钥">
    使用 [控制台](https://orbitflare.com/dashboard) 中的 API 密钥认证。密钥通过 `X-ORBIT-KEY` 标头传给客户 API。

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

  <Tab title="钱包">
    使用 Solana 密钥对签名质询进行认证。若钱包未关联账户，CLI 会引导注册。

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

  <Tab title="设备流程">
    打开浏览器进行类 OAuth 认证，适合交互式使用。

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

    CLI 显示验证 URL 与验证码，轮询完成后自动存储会话令牌。
  </Tab>
</Tabs>

### 密钥解析顺序

1. 命令行上的 `--x-orbit-key` 标志（最高优先级）
2. `--profile` 选择已存储的配置文件
3. `~/.orbitflare/config.yml` 中的默认配置文件

## 命令参考

CLI 顶层命令涵盖认证、配置、区块链查询、实时流式传输、项目脚手架与账户管理。

### 核心命令

| 命令                             | 说明                                    |
| ------------------------------ | ------------------------------------- |
| `auth login`                   | 认证（API 密钥、钱包或设备流程）                    |
| `auth logout`                  | 移除已存储凭证                               |
| `auth status`                  | 显示当前认证状态                              |
| `auth switch --profile <NAME>` | 切换到其他认证配置文件                           |
| `auth set-license-key <KEY>`   | 为当前配置文件存储 RPC 许可证密钥                   |
| `config show`                  | 显示全部配置值                               |
| `config set <KEY> <VALUE>`     | 设置配置项                                 |
| `config remove <KEY> <VALUE>`  | 从列表型配置中移除值                            |
| `config reset`                 | 重置为默认（保留认证）                           |
| `ping`                         | 检查到所有已配置服务的连通性                        |
| `ping --service <SVC>`         | 仅 ping 指定服务（`rpc`、`jetstream`、`grpc`） |
| `docs [TOPIC...]`              | 在浏览器中打开文档                             |
| `plan list`                    | 列出可用 RPC 套餐                           |
| `plan view <SLUG>`             | 查看套餐详情                                |
| `plan compare --all`           | 并排比较全部套餐                              |
| `pay check-balance`            | 查看账户余额                                |
| `pay topup <AMOUNT>`           | 使用 USDC 链上充值余额                        |
| `pay history`                  | 充值 / 入账历史                             |
| `pay purchase <SLUG> <PERIOD>` | 使用余额购买套餐                              |
| `pay order --history`          | 列出订单                                  |
| `pay order <REF>`              | 查看订单详情                                |
| `pay invoice --list`           | 列出发票                                  |
| `pay invoice <REF>`            | 查看发票详情                                |
| `pay renew <INVOICE>`          | 使用余额支付发票（续费）                          |

### RPC 命令

直接从终端查询 Solana 区块链。

```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 命令

通过 WebSocket 订阅实时 Solana pubsub 事件。每个订阅运行至按 `Ctrl+C` 结束，事件到达时打印（使用 `--json` 可获得机器可读输出）。

```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>
```

端点由已配置的 `rpc.url` 推导：`http://` 变为 `ws://`，`https://` 变为 `wss://`。若要对单条命令指定不同主机，传入 `--ws-url`：

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

### 流式传输命令

通过 gRPC 实时流式传输 Solana 数据。两条命令均接受定义过滤器与重连策略的 YAML 配置文件。

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

    Jetstream 提供超低延迟的交易与账户流式传输。

    ```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 提供完整 Geyser 插件数据流，含槽位与区块元数据。

    ```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>

两条流式命令均支持自动端点故障转移与指数退避重连。配置文件中可使用 `${VAR}` 语法引用环境变量。

### 模板命令

从生产级入门模板脚手架项目。

```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
```

模板从 [orbitflare/templates](https://github.com/orbitflare/templates) 仓库拉取并本地缓存，支持离线使用。

### 套餐命令

浏览并比较可用 RPC 套餐。套餐数据本地缓存 6 小时。

```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
```

### 支付命令

管理账户余额、购买套餐与处理发票。仅 `topup` 需要 Solana 钱包 — 其余使用账户余额。

```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>
```

`topup` 默认使用 `~/.config/solana/id.json` 作为钱包密钥文件。使用 `--wallet` 指定其他路径。计费周期：`monthly`、`quarterly`、`semi-annual`、`annual`。

<Note>
  `purchase` 命令会先执行仅校验的 dry-run，展示价格拆分与余额是否充足，再确认。
</Note>

### 控制台

启动交互式 TUI，在终端内管理 OrbitFlare 账户。

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

控制台通过键盘完整访问资料、服务、API 密钥与发票。

<AccordionGroup>
  <Accordion title="导航快捷键">
    | 按键          | 操作           |
    | ----------- | ------------ |
    | `q`         | 退出           |
    | `Esc`       | 返回           |
    | `Tab`       | 切换标签 / 焦点    |
    | `↑↓` / `jk` | 导航           |
    | `Enter`     | 选择 / 展开 / 切换 |
    | `t` / `T`   | 切换主题         |
    | `[`         | 切换侧栏         |
    | `R`         | 刷新数据         |
  </Accordion>

  <Accordion title="服务管理快捷键">
    | 按键  | 标签            | 操作                   |
    | --- | ------------- | -------------------- |
    | `m` | Details       | 切换认证模式（IP / API Key） |
    | `w` | Details       | 切换自动续费               |
    | `r` | Details       | 重新生成许可证密钥            |
    | `n` | IPs / Domains | 切换 Mainnet / Devnet  |
    | `a` | IPs / Domains | 添加 IP 或域名            |
    | `d` | IPs / Domains | 移除 IP 或域名            |
  </Accordion>

  <Accordion title="API 密钥管理快捷键">
    | 按键  | 操作         |
    | --- | ---------- |
    | `c` | 创建新 API 密钥 |
    | `e` | 启用 / 禁用    |
    | `r` | 重新生成密钥     |
    | `x` | 删除密钥       |
    | `a` | 展开时添加 IP   |
    | `d` | 展开时移除 IP   |
  </Accordion>

  <Accordion title="发票与个人资料快捷键">
    | 按键  | 区域       | 操作        |
    | --- | -------- | --------- |
    | `p` | Invoices | 使用账户余额支付  |
    | `e` | Profile  | 编辑姓名与支付钱包 |
  </Accordion>
</AccordionGroup>

## JSON 输出

所有命令支持 `--json` 机器可读输出，便于接入脚本与自动化流水线。

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

示例输出：

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

## 配置

配置存储在 `~/.orbitflare/config.yml`。使用 `config` 命令管理：

```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 端点默认预配置：

* **RPC：** `http://devnet.rpc.orbitflare.com`（回退：`https://api.devnet.solana.com`）
* **gRPC：** `http://devnet.rpc.orbitflare.com:10000`

运行时可用 `--network devnet` 切换。

### 文件位置

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

API 密钥、令牌与许可证密钥存储在**操作系统钥匙串**中，不在磁盘明文保存。

## 全局标志

这些标志适用于每条命令，并在该次调用中覆盖对应配置。

| 标志                     | 说明                                            |
| ---------------------- | --------------------------------------------- |
| `--json`               | 输出原始 JSON                                     |
| `--raw`                | 最小输出，无格式化                                     |
| `--network <NET>`      | 覆盖网络（`mainnet` / `devnet` / `testnet`）        |
| `--commitment <C>`     | 覆盖承诺（`processed` / `confirmed` / `finalized`） |
| `--rpc-url <URL>`      | 覆盖 RPC 端点                                     |
| `--grpc-url <URL>`     | 覆盖 gRPC 端点                                    |
| `--ws-url <URL>`       | 覆盖 WebSocket 端点（默认由 RPC URL 推导）               |
| `--fallback-url <URL>` | 备用 URL（可重复）                                   |
| `--profile <NAME>`     | 使用指定认证配置文件                                    |
| `--quiet`              | 抑制非必要输出                                       |
| `--no-color`           | 禁用彩色输出                                        |

## 完整工作流示例

从安装到查询的完整 walkthrough：

```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
```

## 下一步

<CardGroup cols={2}>
  <Card title="RPC 方法" icon="server" href="/cn/rpc/http">
    浏览完整 Solana RPC 方法参考。
  </Card>

  <Card title="Jetstream 流式传输" icon="bolt" href="/cn/data-streaming/jetstream">
    了解实时 gRPC 数据流。
  </Card>

  <Card title="Yellowstone gRPC" icon="satellite-dish" href="/cn/data-streaming/yellowstone">
    通过 Yellowstone 获取完整 Geyser 插件数据。
  </Card>

  <Card title="入门模板" icon="rectangle-terminal" href="https://github.com/orbitflare/templates">
    浏览生产级项目模板。
  </Card>
</CardGroup>

## 支持

<CardGroup cols={2}>
  <Card title="Discord" icon="discord" href="https://discord.gg/orbitflare">
    加入社区获取帮助与讨论。
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/orbitflare/orbit-cli">
    反馈问题或为 CLI 贡献代码。
  </Card>
</CardGroup>