use-circle-cli

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.

Install & verify

# 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

Discoverability: always ask --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.

# 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

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.

Command surface (high-level)

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

Wallet & identity

Cross-chain & on-chain operations

Paid services (x402)

Smart contracts

Transactions

Discovery & tooling

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.

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.

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.

Report friction (feedback)

The CLI can send feedback to Circle with circle feedback submit (--category BUG|QUESTION|FEEDBACK). Submit proactively when the CLI itself causes friction — an unexpected error, output that contradicts --help, or a missing capability — but not for user mistakes or expected validation errors. It requires a mainnet session; never force a login just to file feedback. READ references/cli-operations.md for triggers, guardrails, and the --recent-commands enrichment.

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.
• PROACTIVELY file feedback with circle feedback submit (pick one --category: BUG, QUESTION, or FEEDBACK) when the CLI itself causes friction (unexpected error, confusing output, missing capability). Don't file for user mistakes or expected validation errors, and never force a login just to submit. See Report friction (feedback).

Staying current

Surface version/update guidance to the user when relevant — start of session, after a long gap, or when a command behaves unexpectedly. circle --version surfaces update notices; npm install -g @circle-fin/cli@latest updates the CLI; circle skill update --tool <tool> (or npx skills update) updates installed skills. These mutate the user's system — ask before running them, don't run them unprompted. READ references/cli-operations.md for the exact commands.

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

Alternatives

For the agent-wallet flows, route to the dedicated skill per the Common end-to-end flows table above: use-agent-wallet (setup/login/Terms/create), pay-via-agent-wallet (paid x402 services), fund-agent-wallet (add USDC / Gateway deposit), agent-wallet-policy (spending limits).

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 with Circle SDKs (e.g., @circlefin/app-kit, @circlefin/bridge-kit) or wants architectural guidance (choosing a wallet type, integrating CCTP, deploying contracts).

The CLI is for agent-flow use (an AI agent operating on behalf of a user). The SDK skills are for code-generation use (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.