Back to Details

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

钱包与身份

CommandWhat 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

跨链与链上操作

CommandWhat 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）

CommandWhat 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

智能合约

CommandWhat 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

交易管理

CommandWhat 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

功能探索与工具

CommandWhat 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 intentSkill 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
circle --version

Update the CLI

更新CLI

npm install -g @circle-fin/cli@latest
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>
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

参考链接

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。