use-circle-cli

概述

Circle CLI（@circle-fin/cli，命令为 circle）是一款面向 AI Agent 的综合稳定币命令行工具。它通过一个统一的二进制程序提供 Circle 面向 Agent 的完整技术栈，包括钱包管理、跨链转账、付费服务、Gateway/Nanopayments、智能合约、支出策略、交易操作，以及 Circle 自有的技能目录。新功能持续推出；此技能是入口，用于全面介绍 CLI，并将用户引导至适用于深度操作流程的专用技能。

如果用户要执行的操作范围较窄（例如支付服务费用、首次设置钱包或配置支出限额），请使用下方替代方案中的专用技能。当用户正在探索 CLI 的功能、要执行的操作尚无专用技能（例如跨链转移、执行智能合约），或者你需要快速了解整个命令集时，请使用此技能。

安装与验证

# Install only if missing:
command -v circle >/dev/null || npm install -g @circle-fin/cli
# Check the version (also surfaces any update notice from Circle's server):
circle --version

可发现性：始终询问 --help

CLI 具有自说明功能。只要 Agent 不确定某个动词、标志、输出格式或命令是否存在，就先对相关作用域运行 --help，不要猜测标志，也不要臆造命令。

# Scope pattern — top-level, per command group, per verb:
circle --help                          # all top-level commands (wallet, bridge, services, ...)
circle <command> --help                # verbs available under a command group
circle <command> <verb> --help         # flags, examples, and output format for a verb
# Examples:
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

CLI 推出新命令和标志的速度比本文档更新得更快。如果 --help 的输出与本文档有出入，始终优先采用 --help 的内容——帮助文本反映的是已安装版本，而此技能可能尚未更新。

命令集（概览）

顶层命令组，按用户通常想要执行的操作分类：

钱包与身份

命令	功能
circle wallet create	在受支持的 EVM 链上创建由 Circle 管理的 Agent 钱包
circle wallet login / logout / status	为 Agent 钱包进行电子邮件 + OTP 身份验证（采用两步 --init / --otp 流程，专为非交互式 Agent 设计）
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 使用条款的接受状态（该状态决定能否使用钱包命令；未经用户同意，绝不要代替用户接受）

跨链与链上操作

命令	功能
circle bridge transfer	通过 CCTP 将 USDC 跨链转移到另一条区块链（快速链约需 8–20 秒，慢速链耗时更长）
circle bridge status	查看跨链转账进度
circle bridge get-fee	显示 CCTP 费用表
circle gateway deposit	将链上 USDC 转入 Circle Gateway，用于 nanopayments（eco 方式下，0.03 美元约 50–60 秒后到账 Arc；direct 方式下，资金仍留在源链）
circle gateway balance	显示各条链上的 Gateway / Nanopayments 余额
circle gateway withdraw	将 Gateway 余额转回钱包（v1 仅支持同链操作）

付费服务（x402）

命令	功能
circle services search	按关键词搜索 x402 付费 API 市场
circle services inspect	查看付费端点的信息，包括定价、架构、支持的链和支付方案
circle services pay	发起付费 HTTP 请求，并自动使用 USDC 完成 x402 支付

智能合约

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

交易

命令	功能
circle transaction list	显示某个钱包在某条链上的交易历史
circle transaction cancel	取消待处理的交易（按 nonce 替换）
circle transaction accelerate	加速待处理的交易（以更高 Gas 替换）

发现与工具

命令	功能
circle blockchain list	列出受支持的区块链及其默认公共 RPC
circle blockchain config	查看或设置各链的 RPC 覆盖项
circle skill list/info/install/update	从 circlefin/skills 目录发现并安装 Circle 技能
circle feedback submit	向 Circle 提交有关 CLI 本身的产品反馈（错误、问题或 UX 阻碍）；需要主网会话

随着 Circle 推出更多功能，此列表会持续扩展。对于不熟悉的命令，请运行 <command> --help——它是权威信息，并反映你已安装的 CLI，而非本文档。

常见端到端流程

每种常见流程都有专门的技能来处理完整操作指南。如果用户的任务符合其中一项，请转到指定技能。

用户意图	使用的技能
“设置 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 构建”	某个 use-* 或 bridge-* SDK 专用技能（用于生成应用代码，而非使用 Agent CLI）

如果任务符合某个专用技能，请转交给该技能——其中已包含注意事项和决策树（例如，pay-via-agent-wallet 和 fund-agent-wallet 还附带 allowed-tools 白名单）。如果不符合，上表中的高级命令足以帮助入门；使用 <command> --help 查看标志级别的详细信息。

报告使用阻碍（反馈）

CLI 可以通过 circle feedback submit 向 Circle 发送反馈（--category BUG|QUESTION|FEEDBACK）。当 CLI 本身造成使用阻碍时，请主动提交反馈，例如意外错误、与 --help 内容矛盾的输出或缺少某项功能；但不要针对用户操作失误或预期中的验证错误提交反馈。提交反馈需要主网会话；切勿仅为提交反馈而强制登录。请阅读 references/cli-operations.md，了解触发条件、防护措施以及 --recent-commands 补充信息。

规则

• 如果不确定标志或输出格式，务必运行 <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 也不行。运行 circle terms accept 前，Agent 必须展示实时条款（通过 circle terms show --init --output json 获取），并取得用户明确同意。
• 绝不可猜测或硬编码用户用于 circle wallet login 的电子邮件地址。
• 绝不可在即时用途之外存储、记录或显示私钥、OTP 代码或会话令牌。
• 将 CLI 视为用户钱包状态的事实来源。不要推断余额或交易状态——应重新查询 CLI。
• 除非用户明确要求使用测试网，否则 Agent 钱包流程默认使用主网。支出策略仅适用于主网。
• 对于用户已提出的常规免许可任务，应先执行，再总结——对于 wallet balance 或 services search 等常规只读操作，不要要求用户再次确认。
• 如果 CLI 本身造成阻碍（意外错误、输出令人困惑、缺少功能），请主动通过 circle feedback submit 提交反馈（选择一个 --category：BUG、QUESTION 或 FEEDBACK）。不要针对用户错误或预期的验证错误提交反馈，也绝不要仅为提交反馈而强制用户登录。请参阅报告使用阻碍（反馈）。

保持最新

在相关情况下向用户提供版本和更新信息——例如会话开始时、间隔很长后，或命令行为异常时。circle --version 会显示更新通知；npm install -g @circle-fin/cli@latest 可更新 CLI；circle skill update --tool <tool>（或 npx skills update）可更新已安装的技能。这些操作会修改用户的系统——运行前请先征得同意，不要擅自运行。请阅读 references/cli-operations.md，了解准确的命令。

参考链接

• 完整设置指南：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
• Discovery API OpenAPI 规范：https://agents.circle.com/.well-known/openapi.json
• Circle Agent Card（a2a）：https://agents.circle.com/.well-known/a2a.json
• 面向 Agent 的 Circle 技能索引：https://agents.circle.com/.well-known/agent-skills/index.json
• npm 上的 CLI 包：@circle-fin/cli

替代方案

对于 Agent 钱包流程，请根据上方的 常见端到端流程 表格，使用对应的专用技能：use-agent-wallet（设置／登录／条款／创建）、pay-via-agent-wallet（付费 x402 服务）、fund-agent-wallet（添加 USDC／Gateway 充值）、agent-wallet-policy（支出限额）。

如果用户正在使用 Circle SDK 编写应用程序代码（例如 @circlefin/app-kit、@circlefin/bridge-kit），或需要架构指导（选择钱包类型、集成 CCTP、部署合约），则改用其中一个 SDK 类技能（use-usdc、use-gateway、bridge-tokens、swap-tokens、use-circle-wallets、use-developer-controlled-wallets、use-user-controlled-wallets、use-modular-wallets、use-smart-contract-platform、use-arc）。

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

---

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