use-circle-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overview

概述

The Circle CLI (

@circle-fin/cli

, command

circle

) is a holistic stablecoin CLI for AI agents. It surfaces Circle's full agent-facing stack — wallet management, cross-chain transfers, paid services, Gateway/Nanopayments, smart contracts, spending policy, transaction operations, and Circle's own skill catalog — through one consistent binary. New capabilities ship continuously; this skill is the front door that introduces the CLI broadly and routes to specialized skills for deep flows.

If the user is doing something narrow (paying for a service, setting up the wallet for the first time, configuring a spending limit), use one of the dedicated skills under Alternatives below. Use this skill when the user is exploring what the CLI can do, when they're doing something that doesn't have its own dedicated skill yet (e.g., bridging, smart contract execution), or when you need a quick orientation across the full command surface.

Circle CLI（

@circle-fin/cli

，命令为

circle

）是一款面向AI Agent的全方位稳定币CLI工具。它通过统一的二进制文件，呈现Circle面向Agent的完整技术栈——包括钱包管理、跨链转账、付费服务、Gateway/小额支付、智能合约、支出策略、交易操作以及Circle自身的技能目录。新功能会持续推出；本技能是广泛介绍CLI并引导至专业技能以处理深度流程的入口。

如果用户的操作较为具体（如支付服务费用、首次设置钱包、配置支出限额），请使用下方替代方案中的专用技能。当用户在探索CLI的功能、进行尚无专用技能支持的操作（如跨链桥接、智能合约执行），或需要快速了解整个命令体系时，使用本技能。

Install & verify

安装与验证

bash

which circle || command -v circle
circle --version   # also surfaces any update notice from Circle's server

If not installed:

bash

npm install -g @circle-fin/cli

bash

which circle || command -v circle
circle --version   # 同时显示Circle服务器推送的更新通知

若未安装：

bash

npm install -g @circle-fin/cli

Discoverability: always ask

--help

功能探索：始终使用

--help

The CLI is self-documenting. Whenever the agent is unsure about a verb, flag, output shape, or whether a command exists, run
--help
on the relevant scope first — don't guess flags, don't invent commands.

bash

circle --help                          # top-level command list
circle <command> --help                # verbs available under a command group
circle <command> <verb> --help         # flags, examples, and output format for a specific verb

Examples:

bash

circle --help                          # all top-level commands (wallet, bridge, services, ...)
circle wallet --help                   # all verbs under `wallet`
circle services pay --help             # flags and examples for `circle services pay`
circle bridge transfer --help          # flags and output shape for cross-chain bridging

The CLI ships new commands and flags faster than this document. Always prefer
--help
output over what's documented here when they disagree — the help text reflects the installed version, this skill might lag.

CLI自带文档说明。当Agent对某个动词、标志、输出格式或命令是否存在不确定时，请先在相关范围内运行
--help
——不要猜测标志，不要自创命令。

bash

circle --help                          # 顶级命令列表
circle <command> --help                # 命令组下可用的动词
circle <command> <verb> --help         # 特定动词的标志、示例和输出格式

示例：

bash

circle --help                          # 所有顶级命令（wallet、bridge、services等）
circle wallet --help                   # `wallet`下的所有动词
circle services pay --help             # `circle services pay`的标志和示例
circle bridge transfer --help          # 跨链桥接的标志和输出格式

CLI的新命令和标志更新速度快于此文档。当帮助文本与本文档内容不一致时，始终以
--help
的输出为准——帮助文本反映的是已安装版本，而本技能可能存在滞后。

Command surface (high-level)

命令体系（概览）

Top-level command groups, organized by what the user typically wants to do:

顶级命令组按用户常见操作场景分类：

Wallet & identity

钱包与身份

Command	What it does
`circle wallet create`	Create a Circle-managed agent wallet on supported EVM chains
`circle wallet login` / `logout` / `status`	Email + OTP authentication for the agent wallet (two-step `--init` / `--otp` flow designed for non-interactive agents)
`circle wallet list`	List wallets (filter by `--type agent` or `--type local` , requires `--chain` )
`circle wallet balance`	Show token balances for a wallet on a chain
`circle wallet transfer`	Send USDC (or another supported token) from this wallet to another address on the same chain
`circle wallet fund`	Open a fiat on-ramp or render a deposit QR code so the user can fund the wallet
`circle wallet limit show/set/reset`	View and change spending policy (mainnet only; set/reset require human OTP)
`circle wallet execute`	Execute a smart contract function (any chain Circle supports)
`circle terms show/accept/reset`	Manage Circle CLI Terms of Use acceptance (gates wallet commands; never accept on the user's behalf without consent)

命令	功能
`circle wallet create`	在支持的EVM链上创建由Circle托管的Agent钱包
`circle wallet login` / `logout` / `status`	Agent钱包的邮箱+OTP认证（为非交互式Agent设计的两步 `--init` / `--otp` 流程）
`circle wallet list`	列出钱包（可通过 `--type agent` 或 `--type local` 筛选，需指定 `--chain` ）
`circle wallet balance`	显示钱包在某条链上的代币余额
`circle wallet transfer`	从当前钱包向同链上的其他地址发送USDC（或其他支持的代币）
`circle wallet fund`	打开法币充值通道或生成存款二维码，方便用户为钱包充值
`circle wallet limit show/set/reset`	查看和修改支出策略（仅主网可用；设置/重置需人工OTP验证）
`circle wallet execute`	执行智能合约函数（Circle支持的所有链均可）
`circle terms show/accept/reset`	管理Circle CLI服务条款的接受状态（会限制钱包相关命令；未经用户同意，绝不能代用户接受条款）

Cross-chain & on-chain operations

跨链与链上操作

Command	What it does
`circle bridge transfer`	Bridge USDC to another blockchain via CCTP (~8–20s on fast chains, longer on slow chains)
`circle bridge status`	Check progress of a bridge transfer
`circle bridge get-fee`	Show CCTP fee schedule
`circle gateway deposit`	Move on-chain USDC into Circle Gateway for nanopayments (eco lands on Polygon ~50-60s for $0.03; direct stays on source chain)
`circle gateway balance`	Show Gateway / Nanopayments balance per chain
`circle gateway withdraw`	Move Gateway balance back to a wallet (same-chain only in v1)

命令	功能
`circle bridge transfer`	通过CCTP将USDC跨链至其他区块链（快速链约8-20秒，慢速链耗时更长）
`circle bridge status`	查看跨链桥接转账的进度
`circle bridge get-fee`	显示CCTP费用标准
`circle gateway deposit`	将链上USDC转入Circle Gateway用于小额支付（生态链存入Polygon约50-60秒，费用0.03美元；直接存入则保留在原链）
`circle gateway balance`	显示各链上Gateway/小额支付的余额
`circle gateway withdraw`	将Gateway余额转回钱包（v1版本仅支持同链操作）

Paid services (x402)

付费服务（x402）

Command	What it does
`circle services search`	Search the x402 paid-API marketplace by keyword
`circle services inspect`	Inspect a paid endpoint — pricing, schema, supported chains, payment scheme
`circle services pay`	Make a paid HTTP request with automatic x402 payment in USDC

命令	功能
`circle services search`	通过关键词搜索x402付费API市场
`circle services inspect`	查看付费端点详情——定价、schema、支持的链、支付方案
`circle services pay`	自动以USDC完成x402支付并发起付费HTTP请求

Smart contracts

智能合约

Command	What it does
`circle contract address`	Show Circle contract addresses (USDC token, Gateway, etc.) per chain
`circle contract query`	Read-only ABI query against any deployed contract
`circle wallet execute`	Execute a write call against any contract (state-changing transaction)

命令	功能
`circle contract address`	显示各链上Circle合约的地址（USDC代币、Gateway等）
`circle contract query`	对已部署合约进行只读ABI查询
`circle wallet execute`	对合约执行写入调用（会改变链上状态的交易）

Transactions

交易管理

Command	What it does
`circle transaction list`	Show transaction history for a wallet on a chain
`circle transaction cancel`	Cancel a pending transaction (replace-by-nonce)
`circle transaction accelerate`	Speed up a pending transaction (replace-with-higher-gas)

命令	功能
`circle transaction list`	显示钱包在某条链上的交易历史
`circle transaction cancel`	取消待处理交易（通过替换nonce实现）
`circle transaction accelerate`	加速待处理交易（通过提高Gas费实现）

Discovery & tooling

功能探索与工具

Command	What it does
`circle blockchain list`	List supported blockchains with their public RPC defaults
`circle blockchain config`	Inspect or set per-chain RPC overrides
`circle skill list/info/install/update`	Discover and install Circle skills from the `circlefin/skills` catalog

This list will keep growing as Circle ships more capabilities. For any unfamiliar command, run
<command> --help
— it is authoritative and reflects the CLI you have installed, not this document.

命令	功能
`circle blockchain list`	列出支持的区块链及其默认公共RPC节点
`circle blockchain config`	查看或设置各链的RPC节点覆盖配置
`circle skill list/info/install/update`	发现并安装 `circlefin/skills` 目录中的Circle技能

随着Circle推出更多功能，此列表会持续更新。对于任何不熟悉的命令，请运行
<command> --help
——这是权威来源，反映的是你已安装的CLI版本，而非本文档。

Common end-to-end flows

常见端到端流程

For each common flow, there's a dedicated skill that handles the full walkthrough. If the user's task matches one of these, route to the named skill.

User intent	Skill to use
"Set up Circle / log in / create an agent wallet"	`use-agent-wallet`
"Pay for a service / call a paid API / use the x402 marketplace"	`pay-via-agent-wallet`
"Fund my wallet / add USDC / deposit into Gateway"	`fund-agent-wallet`
"Set / change spending limits / view current caps"	`agent-wallet-policy`
"Bridge USDC to another chain (CLI)"	This skill — `circle bridge transfer` is the right command
"Execute a smart contract / read a contract"	This skill — `circle wallet execute` for writes, `circle contract query` for reads
"Manage transactions / cancel a pending tx"	This skill — `circle transaction list/cancel/accelerate`
"Build with Circle SDKs in an app"	One of the SDK-flavored `use-` or `bridge-` skills (those are for app code generation, not agent CLI use)

If the task fits a dedicated skill, hand off there — that skill has the gotchas and decision trees baked in (some, like

pay-via-agent-wallet

and

fund-agent-wallet

, also ship

allowed-tools

whitelists). If it doesn't, the high-level commands in the table above are enough to get started; use

<command> --help

for flag-level detail.

每个常见流程都有对应的专用技能处理完整操作流程。如果用户的任务符合以下场景，请引导至指定技能。

用户意图	使用的技能
"设置Circle/登录/创建Agent钱包"	`use-agent-wallet`
"支付服务费用/调用付费API/使用x402市场"	`pay-via-agent-wallet`
"为钱包充值/添加USDC/存入Gateway"	`fund-agent-wallet`
"设置/修改支出限额/查看当前上限"	`agent-wallet-policy`
"将USDC跨链至其他链（CLI）"	本技能—— `circle bridge transfer` 是正确命令
"执行智能合约/读取合约数据"	本技能——写入操作使用 `circle wallet execute` ，读取操作使用 `circle contract query`
"管理交易/取消待处理交易"	本技能—— `circle transaction list/cancel/accelerate`
"在应用中使用Circle SDK开发"	某款SDK专属的 `use-` 或 `bridge-` 技能（这些技能用于生成应用代码，而非Agent CLI使用）

如果任务适合专用技能，请转交至该技能——这些技能已内置各种注意事项和决策逻辑（部分技能如

pay-via-agent-wallet

和

fund-agent-wallet

还包含

allowed-tools

白名单）。如果不适合，上述表格中的高级命令足以入门；如需标志级细节，请使用

<command> --help

。

Bridging and smart contracts

跨链桥接与智能合约

For cross-chain USDC, run

circle bridge --help

and

circle bridge transfer --help

. For ABI-level read and write calls, run

circle contract query --help

and

circle wallet execute --help

. The CLI's

--help

output is the source of truth for flag positions and ABI conventions — don't guess.

对于跨链USDC操作，请运行

circle bridge --help

和

circle bridge transfer --help

。对于ABI级别的读写调用，请运行

circle contract query --help

和

circle wallet execute --help

。CLI的

--help

输出是标志位置和ABI规范的权威来源——不要猜测。

Rules

规则

ALWAYS run
```
<command> --help
```
when you're unsure about flags or output shape — the help text is authoritative and reflects the installed CLI version, not this skill.
ALWAYS pass
```
--output json
```
for commands whose output the agent needs to parse.

ALWAYS pass

--chain

when running

circle wallet list

circle wallet balance

circle wallet transfer

circle bridge transfer

circle gateway *

circle contract *

, and

circle transaction *

. If unsure which chain to use, run

circle blockchain list

first.

NEVER accept Circle's Terms of Use on the user's behalf — even with
```
CIRCLE_ACCEPT_TERMS=1
```
. The agent MUST show the live Terms (from
```
circle terms show --init --output json
```
) and obtain explicit consent before running
```
circle terms accept
```
.
NEVER guess or hardcode the user's email address for
```
circle wallet login
```
.
NEVER store, log, or display private keys, OTP codes, or session tokens beyond their immediate use.
Treat the CLI as the source of truth for the user's wallet state. Don't infer balances or transaction status — query the CLI fresh.
Default to mainnet for the agent wallet flow unless the user explicitly requests testnet. Spending policy is mainnet-only.
For routine permissionless tasks the user has already asked for, act first and summarize after — don't ask for re-confirmation on routine read-only operations like
```
wallet balance
```
or
```
services search
```
.

当对标志或输出格式不确定时，务必运行
```
<command> --help
```
——帮助文本是权威来源，反映的是已安装的CLI版本，而非本技能。
对于Agent需要解析输出的命令，务必添加
```
--output json
```
参数。

运行

circle wallet list

、

circle wallet balance

、

circle wallet transfer

、

circle bridge transfer

、

circle gateway *

、

circle contract *

和

circle transaction *

时，务必指定

--chain

参数。若不确定使用哪条链，请先运行

circle blockchain list

。

绝不能代用户接受Circle的服务条款——即使使用
```
CIRCLE_ACCEPT_TERMS=1
```
参数。Agent必须显示实时条款（通过
```
circle terms show --init --output json
```
获取）并获得用户明确同意后，才能运行
```
circle terms accept
```
。
绝不能猜测或硬编码用户的邮箱地址用于
```
circle wallet login
```
。
除即时使用外，绝不能存储、记录或显示私钥、OTP验证码或会话令牌。
将CLI视为用户钱包状态的权威来源。不要推断余额或交易状态——应通过CLI实时查询。
除非用户明确要求测试网，否则Agent钱包流程默认使用主网。支出策略仅在主网可用。
对于用户已请求的常规无权限任务，先执行再总结——对于
```
wallet balance
```
或
```
services search
```
等常规只读操作，无需再次确认。

Staying current

保持版本更新

Surface these to the user when relevant — start of session, after a long gap, or when a command behaves unexpectedly.

bash

undefined

在相关场景下向用户展示以下命令——如会话开始时、长时间间隔后或命令行为异常时。

bash

undefined

Check the CLI version (also surfaces any update notice from Circle's server)

检查CLI版本（同时显示Circle服务器推送的更新通知）

circle --version

Update the CLI

更新CLI

npm install -g @circle-fin/cli@latest

Update Circle's installed skills (pick the host matching the runtime: claude-code, cursor, codex, opencode, amp, or another tool name)

更新已安装的Circle技能（选择与运行环境匹配的宿主：claude-code、cursor、codex、opencode、amp或其他工具名称）

circle skill update --tool <tool>

Universal fallback (works on any host the open

skills

registry supports)

通用更新方案（适用于开放

skills

注册表支持的所有宿主）

npx skills update


These commands are idempotent (re-running is safe). But `npm install -g`, `circle skill update`, and `npx skills update` all mutate the user's system — ask the user before running any of them, don't run them unprompted.

npx skills update


这些命令是幂等的（重复运行安全）。但`npm install -g`、`circle skill update`和`npx skills update`都会修改用户系统——运行前请询问用户，不要未经提示直接运行。

Reference Links

参考链接

Full setup walkthrough: https://agents.circle.com/skills/setup.md
Circle Developer Docs: https://developers.circle.com/llms.txt — Always read this when looking for source documentation on Circle products
x402 protocol concepts: https://developers.circle.com/gateway/nanopayments/concepts/x402
Service Discovery skill (paid services walkthrough): https://agents.circle.com/services/SKILL.md
Discovery API OpenAPI spec: https://agents.circle.com/.well-known/openapi.json
Circle Agent Card (a2a): https://agents.circle.com/.well-known/a2a.json
Circle agent-facing skill index: https://agents.circle.com/.well-known/agent-skills/index.json
CLI package on npm:
```
@circle-fin/cli
```

完整设置指南：https://agents.circle.com/skills/setup.md
Circle开发者文档：https://developers.circle.com/llms.txt ——查找Circle产品的官方文档时，请始终参考此链接
x402协议概念：https://developers.circle.com/gateway/nanopayments/concepts/x402
服务发现技能（付费服务指南）：https://agents.circle.com/services/SKILL.md
发现API OpenAPI规范：https://agents.circle.com/.well-known/openapi.json
Circle Agent Card（a2a）：https://agents.circle.com/.well-known/a2a.json
Circle面向Agent的技能索引：https://agents.circle.com/.well-known/agent-skills/index.json
npm上的CLI包：
```
@circle-fin/cli
```

Alternatives

替代方案

Trigger the

use-agent-wallet

skill instead when:

The user wants to install the CLI, log in, accept Terms, create a wallet, check balance, or otherwise bootstrap the agent wallet.

The user mentions

circle wallet status

circle wallet login

circle wallet create

Trigger the

pay-via-agent-wallet

skill instead when:

The user wants to call, pay for, or use a paid x402 service.
The user mentions
```
circle services search/inspect/pay
```
specifically.

Trigger the

fund-agent-wallet

skill instead when:

The user wants to add USDC to the wallet (fiat on-ramp, crypto deposit, Gateway deposit, withdrawal).
The user mentions deposit, fiat on-ramp, fiat purchase, QR-code transfer, or Gateway deposit.

Trigger the

agent-wallet-policy

skill instead when:

The user wants to view, set, or reset spending limits on the agent wallet.
The user mentions per-tx / daily / weekly / monthly caps, spending policy, or wallet rules.

Trigger one of the SDK-flavored skills (

use-usdc

use-gateway

bridge-stablecoin

swap-tokens

use-circle-wallets

use-developer-controlled-wallets

use-user-controlled-wallets

use-modular-wallets

use-smart-contract-platform

use-arc

) instead when:

The user is writing application code that uses Circle SDKs (e.g.,

@circlefin/app-kit

@circlefin/bridge-kit

@circle-fin/developer-controlled-wallets

The user wants architectural guidance on choosing a wallet type, integrating CCTP into a web app, or deploying contracts via Circle's Smart Contract Platform.

The CLI is for agent-flow use (an AI agent operating on behalf of a user). The SDK skills are for code-generation use (the agent is helping a developer write application code).

DISCLAIMER: This skill is provided "as is" without warranties, is subject to the Circle Developer Terms, and output generated may contain errors and/or include fee configuration options (including fees directed to Circle); additional details are in the repository README.

当出现以下情况时，请触发

use-agent-wallet

技能：

用户希望安装CLI、登录、接受条款、创建钱包、查询余额或进行其他Agent钱包初始化操作。

用户提及

circle wallet status

、

circle wallet login

、

circle wallet create

。

当出现以下情况时，请触发

pay-via-agent-wallet

技能：

用户希望调用、支付或使用付费x402服务。
用户明确提及
```
circle services search/inspect/pay
```
。

当出现以下情况时，请触发

fund-agent-wallet

技能：

用户希望为钱包添加USDC（法币充值、加密货币存款、Gateway存款、提现）。
用户提及存款、法币充值、法币购买、二维码转账或Gateway存款。

当出现以下情况时，请触发

agent-wallet-policy

技能：

用户希望查看、设置或重置Agent钱包的支出限额。
用户提及单笔交易/每日/每周/每月限额、支出策略或钱包规则。

当出现以下情况时，请触发某款SDK专属技能（

use-usdc

、

use-gateway

、

bridge-stablecoin

、

swap-tokens

、

use-circle-wallets

、

use-developer-controlled-wallets

、

use-user-controlled-wallets

、

use-modular-wallets

、

use-smart-contract-platform

、

use-arc

）：

用户正在编写应用代码并使用Circle SDK（如

@circlefin/app-kit

、

@circlefin/bridge-kit

、

@circle-fin/developer-controlled-wallets

）。

用户需要关于选择钱包类型、在Web应用中集成CCTP或通过Circle智能合约平台部署合约的架构指导。

CLI适用于Agent流程场景（AI Agent代表用户操作）。SDK技能适用于代码生成场景（Agent帮助开发者编写应用代码）。

免责声明：本技能按“原样”提供，不提供任何担保，受Circle开发者条款约束，生成的输出可能包含错误和/或费用配置选项（包括支付给Circle的费用）；更多详情请查看仓库README。

use-circle-cli

Original

Translation

Overview

概述

Install & verify

安装与验证

Discoverability: always ask --help

功能探索：始终使用--help

Command surface (high-level)

命令体系（概览）

Wallet & identity

钱包与身份

Cross-chain & on-chain operations

跨链与链上操作

Paid services (x402)

付费服务（x402）

Smart contracts

智能合约

Transactions

交易管理

Discovery & tooling

功能探索与工具

Common end-to-end flows

常见端到端流程

Bridging and smart contracts

跨链桥接与智能合约

Rules

规则

Staying current

保持版本更新

Check the CLI version (also surfaces any update notice from Circle's server)

检查CLI版本（同时显示Circle服务器推送的更新通知）

Update the CLI

更新CLI

Update Circle's installed skills (pick the host matching the runtime: claude-code, cursor, codex, opencode, amp, or another tool name)

更新已安装的Circle技能（选择与运行环境匹配的宿主：claude-code、cursor、codex、opencode、amp或其他工具名称）

Universal fallback (works on any host the open skills registry supports)

通用更新方案（适用于开放skills注册表支持的所有宿主）

Reference Links

参考链接

Alternatives

替代方案

Discoverability: always ask
`--help`

功能探索：始终使用
`--help`

Universal fallback (works on any host the open
`skills`
registry supports)

通用更新方案（适用于开放
`skills`
注册表支持的所有宿主）