# @circle-fin/cli 中文文档

规范地址：https://npmcn.com/package/%40circle-fin/cli/

版本：1\.2\.3
npm 元数据更新时间：2026-11-04T23:27:56.580Z
中文译文更新时间：2026-11-09T17:05:06.062Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40circle-fin/cli
原文对照：https://npmcn.com/package/%40circle-fin/cli/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：23.2 MB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.18\.2
- 运行依赖：18 个
- 首次发布：2026-05-09T00:58:22.285Z
- 最新版本发布：2026-11-04T23:27:56.403Z
- 近 30 天下载量：2286（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

Circle CLI——与Circle服务交互的命令行工具.

## 安装

```sh
npm install @circle-fin/cli
```

也可以使用：`pnpm add @circle-fin/cli`、`yarn add @circle-fin/cli`、`bun add @circle-fin/cli`

## README

# 语气

Circle的CLI用于设置代理钱包,用USDC为它提供资金,并用于稳定币动力的工作流程.

学习更多 [特务. circle.com](https://agents.circle.com/)。 。 。 .

## 快速启动

安装 CLI并登录 .

```bash
npm install -g @circle-fin/cli
circle --version
circle wallet login <email>
# Enter the OTP code sent to your email when prompted
circle wallet status
```

### 注销

本届会议的清场:

```bash
circle wallet logout
```

### 检查或创建钱包

检查当前钱包状态 `ARC`数字 :

```bash
circle wallet list --chain ARC --type agent --output json
```

初始代理钱包在登录时提供. 使用 `circle wallet list` 首先检查已有的情况.

在所有支持的链上创建 EVM SCA 钱包批次 :

```bash
circle wallet create
circle wallet create --testnet
circle wallet list --chain ARC --type agent --output json
```

检查钱包余额 :

```bash
circle wallet balance --address <addr> --chain ARC --output json
```

## 发现技能

钱包设置后, 使用 CLI 来发现其他 Circle 技能 :

```bash
circle skill list
circle skill info --name use-circle-cli
```

为当前工具安装技能 :

```bash
circle skill install --tool claude-code --name use-circle-cli
# or --tool cursor, --tool codex
```

## 图标

### 区链

块链命令允许您检查支持的链并配置每个链的 RPC 设置 .

```bash
# Inspect blockchain RPC configuration
circle blockchain config --chain ARC
# List supported blockchains
circle blockchain list
```

### 桥

将USDC从一个支持的区块链移动到另一个带有CCTP的区块链.

```bash
# Show the fee for a bridge route
circle bridge get-fee ARC --chain ARB
# Check the status of a bridge transfer
circle bridge status <burn-tx-hash> --chain ARB
# Bridge USDC from Arbitrum to Arc
circle bridge transfer ARC --amount 1.0 --address <addr> --chain ARB
```

### 合同

合同查询允许您查阅 Circle 合同地址,并在不提交交易的情况下在链式合同状态上阅读.

```bash
# Show Circle contract addresses on a chain
circle contract address usdc --chain ARC
# Query read-only contract state
circle contract query "balanceOf(address)" <addr> --contract <contract> --chain ARC --output json
```

### 网关

网关用于纳米付款,包括将钱包资金存入网关余额并管理该余额.

```bash
# Show the current Gateway balance across all settlement chains
circle gateway balance --address <addr> --chain ARC --all
# Deposit wallet USDC directly on Arc
circle gateway deposit --amount 0.5 --address <addr> --chain ARC --method direct
# Deposit wallet USDC into Gateway for nanopayments
circle gateway deposit --amount 0.5 --address <addr> --chain ARB --method eco
# Withdraw funds from Gateway back to a wallet
circle gateway withdraw --amount 0.1 --address <addr> --chain ARC
```

### 服务

服务会让您发现已支付的x402端点,检查定价,并用钱包估计或执行已支付的请求.

```bash
# Inspect a paid endpoint and its pricing
circle services inspect https://api.example.com/data
# Estimate a paid request before sending it
circle services pay https://api.example.com/data --address <addr> --chain ARC --estimate
# Search for paid x402 services
circle services search "web search"
```

### 交易

交易命令帮助管理已提交的未决交易.

```bash
# Speed up a pending transaction
circle transaction accelerate <transaction-id> --chain ARC
# Cancel a pending transaction
circle transaction cancel <transaction-id> --chain ARC
```

### 钱包

钱包流包括发送USDC,交换被支持的资产,执行链上动作,以及管理钱包地址的支出政策.

```bash
# Execute a write call from the wallet
circle wallet execute "approve(address,uint256)" <spender> <amount> --contract <contract> --address <addr> --chain ARC --estimate
# Swap tokens with Circle Stablecoin Kits
circle wallet swap USDC 1.0 EURC 0.8 --address <addr> --chain ARC
# Move ERC-20 USDC between wallets on Arc
circle wallet transfer <recipient> --amount 1 --token 0x3600000000000000000000000000000000000000 --address <addr> --chain ARC
```

### 限制

限制代理钱包的支出政策,包括剩余预算,转移限制,块列表,以及重设自定义政策. 政策写作需要检察官办公室确认.

```bash
# Show remaining EVM-wide rolling-window policy + budget (daily / weekly / monthly)
circle wallet limit budget --address <addr>
# Set a custom transfer limit — OTP-gated, ephemeral human session
circle wallet limit set --address <addr> --chain ARC \
  --policy-type stablecoin --per-tx 100 --daily 100 --weekly 100 --monthly 100
 # Block specific recipient addresses — OTP-gated
circle wallet limit set --address <addr> --chain ARC \
  --policy-type stablecoin --rule-type recipient-blocklist \
  --targets "[0xBAD1,0xBAD2]"
# Block specific contracts on the contract-execution path — OTP-gated
circle wallet limit set --address <addr> --chain ARC \
  --policy-type contract --rule-type contract-blocklist \
  --targets "[0xCONTRACT]"
# Reset every custom policy on this (wallet, chain) back to defaults — OTP-gated
circle wallet limit reset --address <addr> --chain ARC
```

## 外部钱包

从私人密钥或元句中导入本地钱包 :

```bash
circle wallet import my-wallet --private-key || circle wallet import my-wallet --mnemonic
circle wallet list --chain ARC --type local
```

已导入的本地钱包可以使用基于钱包的命令,如传输,合同执行,桥接等,以及可用本地钱包支持的Gateway流量.

## 测试网基金

在不使用主网资金的情况下尝试 CLI 时使用单独的测试网登录会话 :

```bash
circle wallet login <email> --testnet
circle wallet list --chain ARC-TESTNET
```

测试网和主网会话分别存储.

## 更新

要更新新版本的CLI,运行:

```bash
circle update
```

检查新出版的版本, 如果有, 在运行前提示 `npm install -g @circle-fin/cli@latest` 给你的 过 `--yes` 以跳过提示(在脚本和 CI 有用)。 如果你宁可手工升级,上面的npm命令直接起作用.

## 帮助

使用 `--help` 以查看支持动词、旗帜和示例的全部列表.

```bash
circle --help
circle wallet --help
circle gateway --help
circle services --help
```

## 法律

通过使用 CLI,你同意 [使用条件](https://agents.circle.com/terms-of-use) 财务报告和审定财务报表 [隐私政策](https://www.circle.com/legal/privacy-policy)。 。 。 .

## 常见问题

### @circle-fin/cli 是什么？

Circle CLI——与Circle服务交互的命令行工具\.

### 如何安装 @circle-fin/cli？

在项目目录运行 npm install @circle-fin/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 circle，可以用 npx circle 直接运行。

### @circle-fin/cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @circle-fin/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @circle-fin/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.18\.2。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @circle-fin/cli 可以商用吗？

@circle-fin/cli 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @circle-fin/cli 的下载量有多少？

根据 npm 官方下载统计，@circle-fin/cli 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,286 次，日均约 76 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @circle-fin/cli 还在维护吗？

最新版本 1\.2\.3 发布于 2026/11/05（4 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/05/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。