use-circle-cli

概要

Circle CLI（@circle-fin/cli、コマンドは circle）は、AI エージェント向けの包括的なステーブルコイン CLI です。Circle のエージェント向けスタック全体、すなわちウォレット管理、クロスチェーン送金、有料サービス、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 は自己文書化されています。エージェントが動詞、フラグ、出力形式、コマンドの有無について確信を持てない場合は、必ず最初に該当する範囲で --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 の出力を優先してください。ヘルプテキストにはインストール済みのバージョンが反映されていますが、このスキルの情報は遅れている可能性があります。

コマンド一覧（概要）

ユーザーが通常行いたい操作ごとに整理した、トップレベルのコマンドグループです。

ウォレットと ID

コマンド	機能
circle wallet create	対応する EVM チェーン上に、Circle 管理のエージェントウォレットを作成します
circle wallet login / logout / status	エージェントウォレットでメールアドレスと OTP を使って認証します（非対話型エージェント向けの 2 段階の --init / --otp フロー）
circle wallet list	ウォレットを一覧表示します（--type agent または --type local で絞り込み可能。--chain が必要です）
circle wallet balance	チェーン上のウォレットのトークン残高を表示します
circle wallet transfer	このウォレットから、同じチェーン上の別のアドレスに USDC（または別の対応トークン）を送金します
circle wallet fund	ユーザーがウォレットに資金を追加できるよう、法定通貨のオンランプを開くか、入金用 QR コードを表示します
circle wallet limit show/set/reset	支出ポリシーを確認、変更します（メインネットのみ。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 に移動し、ナノペイメントに利用できるようにします（eco は Arc に到着するまで約 50～60 秒、$0.03 の場合。direct は送金元チェーンに留まります）
circle gateway balance	チェーンごとの Gateway／Nanopayments 残高を表示します
circle gateway withdraw	Gateway の残高をウォレットに戻します（v1 では同一チェーンのみ）

有料サービス（x402）

コマンド	機能
circle services search	キーワードで x402 有料 API マーケットプレイスを検索します
circle services inspect	有料エンドポイントの料金、スキーマ、対応チェーン、決済方式を確認します
circle services pay	x402 による USDC の自動支払いを使って、有料 HTTP リクエストを実行します

スマートコントラクト

コマンド	説明
circle contract address	チェーンごとの Circle コントラクトアドレス（USDC トークン、Gateway など）を表示します
circle contract query	デプロイ済みの任意のコントラクトに対して、読み取り専用の ABI クエリを実行します
circle wallet execute	任意のコントラクトに対して書き込み呼び出し（状態を変更するトランザクション）を実行します

トランザクション

コマンド	説明
circle transaction list	チェーン上のウォレットのトランザクション履歴を表示します
circle transaction cancel	保留中のトランザクションをキャンセルします（nonce の置き換え）
circle transaction accelerate	保留中のトランザクションを高速化します（より高いガス代で置き換え）

検索とツール

コマンド	説明
circle blockchain list	サポート対象のブロックチェーンと、それぞれのデフォルトのパブリック RPC を一覧表示します
circle blockchain config	チェーンごとの RPC オーバーライドを確認または設定します
circle skill list/info/install/update	circlefin/skills カタログから Circle スキルを検索してインストールします
circle feedback submit	CLI 自体に関する製品フィードバック（バグ、質問、UX 上の不便さ）を Circle に送信します。メインネットのセッションが必要です

Circle が機能を追加するにつれて、このリストも増えていきます。不慣れなコマンドについては、<command> --help を実行してください。その内容が正確な情報であり、このドキュメントではなく、インストール済みの CLI を反映しています。

よくあるエンドツーエンドのフロー

よくあるフローには、それぞれ手順全体を扱う専用スキルがあります。ユーザーのタスクが次のいずれかに該当する場合は、記載されたスキルに引き継いでください。

ユーザーの意図	使用するスキル
「Circle をセットアップする／ログインする／エージェントウォレットを作成する」	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 を使用します
「トランザクションを管理する／保留中の tx をキャンセルする」	このスキル — circle transaction list/cancel/accelerate
「アプリで Circle SDK を使って開発する」	SDK 向けの use-* または bridge-* スキルのいずれか（これらはアプリコードの生成用であり、エージェント CLI の使用向けではありません）

タスクに専用スキルが適している場合は、そちらに引き継いでください。注意点や判断フローがあらかじめ組み込まれています（pay-via-agent-wallet や fund-agent-wallet など、一部のスキルには allowed-tools の許可リストも含まれています）。該当するスキルがない場合は、上の表にある高レベルのコマンドで十分に始められます。フラグの詳細については、<command> --help を使用してください。

不便な点を報告する（フィードバック）

CLI から circle feedback submit（--category BUG|QUESTION|FEEDBACK）を使って Circle にフィードバックを送信できます。CLI 自体が不便さの原因となった場合（予期しないエラー、--help の内容と矛盾する出力、機能の不足など）は、積極的に送信してください。ただし、ユーザーのミスや想定どおりの検証エラーについては送信しないでください。メインネットのセッションが必要です。フィードバックを送信するためだけに、決してログインを強制しないでください。送信のきっかけ、ガードレール、および --recent-commands による情報追加については、references/cli-operations.md をお読みください。

ルール

• フラグや出力形式がわからない場合は、必ず <command> --help を実行してください。ヘルプテキストが正確な情報源であり、このスキルではなく、インストールされている CLI のバージョンを反映しています。
• エージェントが出力を解析する必要があるコマンドには、必ず --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 show --init --output json で最新の利用規約を表示し、circle terms accept を実行する前に明示的な同意を得る必要があります。
• circle wallet login でユーザーのメールアドレスを推測したり、ハードコードしたりしてはいけません。
• 秘密鍵、OTP コード、セッショントークンを、使用する瞬間を超えて保存、記録、表示してはいけません。
• ユーザーのウォレット状態の正確な情報源として CLI を扱ってください。残高やトランザクションのステータスを推測せず、CLI に最新の情報を問い合わせてください。
• エージェントのウォレットフローでは、ユーザーが明示的にテストネットを要求しない限り、デフォルトでメインネットを使用してください。支出ポリシーはメインネットのみです。
• ユーザーがすでに依頼した通常のパーミッションレスなタスクは、まず実行してから要約してください。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 エージェントカード（a2a）：https://agents.circle.com/.well-known/a2a.json
• Circle のエージェント向けスキルインデックス：https://agents.circle.com/.well-known/agent-skills/index.json
• npm の CLI パッケージ：@circle-fin/cli

代替手段

エージェントウォレットのフローでは、上記の 一般的なエンドツーエンドのフロー テーブルに従って、専用のスキルに振り分けてください。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 は エージェントフローでの使用（ユーザーに代わって AI エージェントが操作する場合）を目的としています。SDK スキルは コード生成での使用（開発者によるアプリケーションコードの作成を支援する場合）を目的としています。

---

免責事項：このスキルは「現状のまま」提供され、保証はありません。また、Circle Developer Termsが適用されます。生成される出力にはエラーが含まれる場合や、手数料設定オプション（Circle に支払われる手数料を含む）が含まれる場合があります。詳細については、リポジトリのREADMEをご覧ください。