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

# Clink CLI

> 使用 clink-cli 在命令行中初始化 customer wallet、管理绑卡链接、发起支付、退款并查看风控规则。

`clink-cli` 是 Clink customer wallet API 的命令行工具。你可以用它初始化 customer wallet profile、打开绑卡或管理卡页面、发起支付、创建退款，以及查看风控规则。

<Warning>
  **安全提示：** CLI 可能会把 customer 凭证保存到本地 profile。不要提交 `~/.clink-cli/config.json`，也不要分享 `customer-api-key` 等敏感值。
</Warning>

<Card title="NPM Package" icon="npm" href="https://www.npmjs.com/package/@clink-ai/clink-cli">
  在 npmjs.com 查看该包
</Card>

## 环境要求

* Node.js `>=20`
* 可以访问目标 Clink API 环境

默认 Base URL：

```text theme={null}
https://api.clinkbill.com
```

## 安装

全局安装 CLI：

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

不全局安装，直接运行：

```bash theme={null}
npx clink-cli --help
```

所有命令都以这个格式开始：

```bash theme={null}
clink-cli <command> [subcommand] [options]
```

## 快速开始

### 1. 初始化钱包

第一次使用先执行一次，创建或激活 customer wallet，并把凭证保存到本地：

```bash theme={null}
clink-cli wallet init --email user@example.com --name "Alice"
```

查看当前保存的 profile：

```bash theme={null}
clink-cli wallet status --format pretty
```

本地配置文件路径：

```text theme={null}
~/.clink-cli/config.json
```

### 2. 打开卡相关页面

获取原始 binding link：

```bash theme={null}
clink-cli card binding-link
```

打开新增卡页面：

```bash theme={null}
clink-cli card setup-link --open
```

打开管理卡页面：

```bash theme={null}
clink-cli card modify-link --open
```

### 3. 查看本地缓存的支付方式

查看支付方式列表：

```bash theme={null}
clink-cli card list --format pretty
```

查看单个支付方式：

```bash theme={null}
clink-cli card get --payment-instrument-id pi_xxx
```

说明：

* 新增卡、修改卡、删除卡都在网页端完成，不在 CLI 里直接执行。
* `card list` 和 `card get` 读取的是本地缓存。
* `card binding-link`、`card setup-link`、`card modify-link` 会刷新本地支付方式缓存。

### 4. 发起支付

商户模式支付：

```bash theme={null}
clink-cli pay \
  --merchant-id merchant_xxx \
  --amount 10.00 \
  --currency USD \
  --payment-instrument-id pi_xxx
```

Session 模式支付：

```bash theme={null}
clink-cli pay --session-id sess_xxx --payment-instrument-id pi_xxx
```

如果不传 `--payment-instrument-id`，`pay` 会使用本地缓存里默认的支付方式。

### 5. 退款

创建全额退款：

```bash theme={null}
clink-cli refund create --order-id order_xxx
```

查询退款状态：

```bash theme={null}
clink-cli refund get --refund-id rfd_xxx
```

### 6. 查看风控规则

获取当前风控规则：

```bash theme={null}
clink-cli risk-rule get --format pretty
```

打开风控规则页面：

```bash theme={null}
clink-cli risk-rule link --open
```

## 常见用法

使用指定 profile：

```bash theme={null}
clink-cli wallet init --profile buyer-2 --email user2@example.com --name "Bob"
clink-cli wallet status --profile buyer-2 --format pretty
```

覆盖 base URL：

```bash theme={null}
clink-cli wallet status --base-url https://uat-api.clinkbill.com
```

只打印请求，不真正执行：

```bash theme={null}
clink-cli pay \
  --merchant-id merchant_xxx \
  --amount 10.00 \
  --currency USD \
  --payment-instrument-id pi_xxx \
  --dry-run
```

## 命令总览

命令分组：

* `clink-cli wallet init`
* `clink-cli wallet status`
* `clink-cli card binding-link`
* `clink-cli card setup-link`
* `clink-cli card modify-link`
* `clink-cli card list`
* `clink-cli card get --payment-instrument-id <id>`
* `clink-cli risk-rule get`
* `clink-cli risk-rule link`
* `clink-cli pay --merchant-id <id> --amount <amount> --currency <currency>`
* `clink-cli pay --session-id <id>`
* `clink-cli refund create --order-id <id>`
* `clink-cli refund get --refund-id <id>`
* `clink-cli config set <key> <value>`
* `clink-cli config get`
* `clink-cli config unset <key>`

查看帮助：

```bash theme={null}
clink-cli --help
clink-cli wallet --help
clink-cli card --help
clink-cli refund --help
```

## 配置

常用配置命令：

```bash theme={null}
clink-cli config get
clink-cli config set base-url https://uat-api.clinkbill.com
clink-cli config set customer-id cus_xxx --profile buyer-2
clink-cli config set customer-api-key sk_test_xxx --profile buyer-2
clink-cli config unset customer-api-key --profile buyer-2
```

支持的配置项：

* `base-url`
* `customer-id`
* `customer-api-key`
* `default-open-links`
* `email`
* `name`

优先级：

1. 命令行参数
2. 环境变量
3. 本地保存的 profile 配置

环境变量：

* `CLINK_BASE_URL`
* `CLINK_CUSTOMER_ID`
* `CLINK_CUSTOMER_API_KEY`

## 全局参数

* `--format <json|pretty>`
* `--dry-run`
* `--open`
* `--profile <name>`
* `--base-url <url>`
* `--customer-id <id>`
* `--customer-api-key <key>`
* `--timeout <ms>`
* `--help`