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

# CLI

> 安装并配置 UQPAY CLI，在命令行中管理资源、测试 API。

UQPAY CLI 提供对 Global Account、Card Issuance 和 Payment API 的命令行访问，覆盖全业务线共 100+ 条命令。

<Card title="GitHub" icon="github" href="https://github.com/uqpay/uqpay-cli">
  源码与 Issue
</Card>

<Info>
  CLI 采用 MIT 协议开源，支持 macOS、Linux 和 Windows（amd64 与 arm64）。
</Info>

## 安装

### npm（推荐）

```bash theme={null}
npm install -g @uqpay/cli
```

### 从源码构建

需要 Go 1.21 或更高版本：

```bash theme={null}
git clone https://github.com/uqpay/uqpay-cli.git
cd uqpay-cli
make install
```

### Shell 自动补全

```bash theme={null}
uqpay setup-completion
source ~/.zshrc  # 或 ~/.bashrc
```

## 配置

首次使用先一次性写入凭证：

```bash theme={null}
uqpay config set client-id YOUR_CLIENT_ID
uqpay config set api-key YOUR_API_KEY
uqpay config set env sandbox
```

也可以在单条命令里直接传入凭证：

```bash theme={null}
uqpay --env sandbox --client-id ID --api-key KEY banking balance list
```

或通过环境变量：

| 变量                | 说明                       |
| ----------------- | ------------------------ |
| `UQPAY_CLIENT_ID` | Client ID                |
| `UQPAY_API_KEY`   | API 密钥                   |
| `UQPAY_ENV`       | `sandbox` 或 `production` |
| `UQPAY_OUTPUT`    | 默认输出格式                   |

## 快速上手

```bash theme={null}
# 查询余额
uqpay banking balance list

# 列出卡片
uqpay issuing card list

# 列出 payment intent
uqpay payment intent list
```

## 输出格式

```bash theme={null}
uqpay banking balance list           # 表格（默认）
uqpay banking balance list -o json   # JSON
uqpay banking balance list -o yaml   # YAML
```

## 子账户操作

以 Connected 账户身份执行命令：

```bash theme={null}
uqpay --on-behalf-of <account-id> banking balance list
```

## 调试

使用 `--debug` 标志打印完整的 HTTP 请求和响应：

```bash theme={null}
uqpay --debug banking balance list
```

## AI 代理技能

CLI 在 `skills/` 目录下自带 6 套结构化 skill，让 AI 代理无需额外配置即可驱动 UQPAY API：

| Skill            | 覆盖范围              |
| ---------------- | ----------------- |
| `uqpay-shared`   | 配置、鉴权、全局 flag     |
| `uqpay-banking`  | Global Account 操作 |
| `uqpay-issuing`  | 卡片与持卡人管理          |
| `uqpay-payment`  | 支付处理              |
| `uqpay-connect`  | Connected 账户管理    |
| `uqpay-simulate` | 沙盒模拟              |

和 CLI 一起安装 skill：

```bash theme={null}
npx skills add uqpay/uqpay-cli -y -g
```