hiero-cli

hiero-cli (hcli)

hcli は、アカウント、トークン（FT/NFT）、スマートコントラクト、コンセンサストピック、ネットワーク設定を管理するための、Hedera ブロックチェーン操作用コマンドラインツールです。

バイナリの構文

hcli <plugin> <command> [options]

グローバルフラグ

フラグ	短縮形	デフォルト	説明
--format	-F	human	出力形式：human または json
--network	-N	active	このコマンドで使用するアクティブなネットワークを上書きします
--payer	-P	operator	このコマンドで使用する支払者アカウントを上書きします。省略した場合は operator がデフォルトです
--confirm	-Y	false	すべての確認プロンプトをスキップします
--max-transaction-fee	-M	config	今回の実行での最大トランザクション手数料の上限：HBAR（例：20）または tinybar（200000000t）。default_max_transaction_fee 設定を上書きします。0 は上書きしないことを意味します

前提条件

ブロックチェーンのコマンドを実行する前に、次の操作を行います。

1. ネットワークを設定します：hcli network use --global testnet
2. オペレーターを設定します：hcli network set-operator --operator <accountId>:<privateKey>

キーの形式

キーと署名者には、複数の形式を使用できます。

• {accountId}:{privateKey} — インラインのペア。例：0.0.123:abc123...
• {ed25519|ecdsa}:private:{hex} — タイプのプレフィックス付きの生の秘密鍵
• {ed25519|ecdsa}:public:{hex} — 生の公開鍵（supply/submit キー用）
• kr_xxx — KMS に保存されたキー参照
• アカウントエイリアス — ローカル状態に登録された名前

ローカル状態の保存

状態は ~/.hiero-cli/state/ に、プラグインの名前空間ごとに 1 つの JSON ファイルとして永続化されます。

プラグイン	ファイル
account	account-accounts-storage.json
token	token-tokens-storage.json
topic	topic-topics-storage.json
batch	batch-batches-storage.json
swap	swap-storage.json
contract	contract-contracts-storage.json
schedule	schedule-transactions-storage.json
network	network-config-storage.json
config	config-storage.json
plugin-management	plugin-management-storage.json
credentials (KMS)	kms-credentials-storage.json, kms-secrets-encrypted-storage.json

金額の表記

• "1" = 表示単位で 1（例：1 HBAR、または小数桁を適用した 1 トークン）
• "100t" = 基本単位／最小単位で 100（HBAR の場合は tinybar、トークンの場合は最小単位）

プラグインカタログ

プラグイン	説明	対応タスク
account	Hedera アカウントを管理する	作成、インポート、残高確認、一覧表示、表示、更新、削除、クリア
hbar	HBAR を送金する	HBAR の送金、HBAR の使用許可の承認／取り消し
token	FT・NFT トークンを管理する	create-ft/nft、create-from-file、mint、burn、wipe、transfer、airdrop、associate、dissociate、freeze/unfreeze、pause/unpause、KYC の付与／取り消し、使用許可（FT/NFT）、delete-allowance-nft、update-metadata-nft、pending-airdrops、cancel/claim/reject-airdrop、一覧表示、表示、インポート、削除
topic	Hedera Consensus Service	作成、更新、メッセージの送信／検索、インポート、一覧表示、削除
schedule	スケジュール済みトランザクション	スケジュールレコードの作成、保留中のスケジュールへの署名、スケジュールの削除、実行状態の検証、スケジュールの一覧表示。プラグインリファレンスで [scheduled] とマークされたコマンドでのみ --scheduled <name>（-X）を使用してください
contract	スマートコントラクトのライフサイクル	Solidity のコンパイルとデプロイ、インポート、一覧表示、削除
contract-erc20	ERC-20 コントラクトの呼び出し	name、symbol、decimals、balanceOf、transfer、transferFrom、approve、allowance、totalSupply。contract プラグインが必要です（先にコントラクトをデプロイする必要があります）
contract-erc721	ERC-721 コントラクトの呼び出し	balanceOf、ownerOf、approve、setApprovalForAll、safeTransferFrom、transferFrom、mint、name、symbol、tokenURI、getApproved、isApprovedForAll。contract プラグインが必要です（先にコントラクトをデプロイする必要があります）
network	ネットワーク設定	ネットワークの一覧表示、ネットワークの切り替え、オペレーターの設定／取得
config	CLI 設定	設定オプションの一覧表示、取得、設定
credentials	キー／認証情報の管理	新しいキーの生成、既存キーのインポート、保存済み認証情報の一覧表示、削除（ID またはエイリアス指定）
batch	トランザクションの一括処理	バッチの作成、トランザクションの追加、実行、一覧表示、削除
swap	複数当事者間の資産交換	スワップの作成、HBAR／FT／NFT の送金追加、表示、一覧表示、実行、削除
eip712	EIP-712 型付きデータへの署名	hash でダイジェストを計算、sign-ecdsa／sign-ed25519 でペイロードに署名（事前計算済みハッシュ、または domain+types+message を受け付けます）、verify-ecdsa で署名者の EVM アドレスを復元、verify-ed25519 で公開鍵に対する Ed25519 署名を検証
x402	x402 支払いへの署名	KMS 経由で PAYMENT-REQUIRED チャレンジに署名し、PAYMENT-SIGNATURE ヘッダーを生成します。支払者のキーは公開されず、ファシリテーターが送信します
plugin-management	プラグインのライフサイクル	追加、削除、有効化、無効化、一覧表示、リセット、情報表示

エージェントへの指示

コマンドを実行する前に、必ず references/<plugin>.md を読み、コマンドの仕様、すべてのオプション、使用例を確認してください。

例：hcli token create-ft を使用するには、まず references/token.md を読んでください。

バッチコマンドを使用する場合は、references/batch.md と、バッチ処理するプラグインのリファレンスの両方を読んでください。

例：hcli token mint-ft をバッチ処理するには、references/batch.md と references/token.md の両方を読んでください。

スケジュールされたトランザクションを使用する場合は、references/schedule.md と、スケジュールするコマンドのリファレンスを読んでください。

リファレンスで [scheduled] とマークされているコマンドのみが、--scheduled <name> / -X に対応しています。

例：hcli token burn-ft をスケジュールするには、references/schedule.md と references/token.md の両方を読んでください。

x402 有料エンドポイント

URL の取得時に、PAYMENT-REQUIRED ヘッダーを伴う HTTP 402 が返された場合、そのエンドポイントは x402 で保護されています。ヘッダーのペイロードを確認し、accepts に hedera:mainnet / hedera:testnet の exact 要件が含まれている場合は、references/x402.md を読み、そこに記載された手順に従ってください。HTTP リクエストはエージェント自身が実行し、hcli x402 sign は PAYMENT-SIGNATURE の値のみを生成します。チャレンジが Hedera 以外のスキームを対象としている場合、この CLI では署名できません。

hcli が見つからない／インストールされていない場合

hcli コマンドが「command not found」などのエラーで失敗した場合は、ユーザーに次のように伝えてください。

hcli がインストールされていないか、PATH から利用できません。 ドキュメントとクイックスタート：https://www.npmjs.com/package/@hiero-ledger/hiero-cli#quick-start

次のコマンドでインストールできます。

npm install -g @hiero-ledger/hiero-cli

インストールコマンドを実行しましょうか？

ユーザーの確認を待ち、自動でインストールを実行しないでください。

オペレーターが設定されていない場合

コマンドが CLI operator is not configured などのエラーで失敗した場合：

1. ブロックチェーン関連のコマンドを実行する前に、オペレーターを設定する必要があることをユーザーに伝えます
2. 次のコマンドを案内します：hcli network set-operator --operator <accountId>:<privateKey>
3. オペレーターの設定後、元のコマンドを再試行します

無効なプラグインの復旧

コマンドが Plugin 'X' is disabled. で失敗した場合：

1. プラグインが無効であることをユーザーに伝えます
2. 次のコマンドで有効化することを提案します：hcli plugin-management enable --name X
3. プラグインの有効化後、元のコマンドを再試行します

よくあるワークフロー

セットアップ（初回）

hcli network use --global testnet
hcli network set-operator --operator 0.0.12345:302e...privatekey...

代替可能トークンの作成と転送

# 1. Create token
hcli token create-ft --token-name "MyToken" --symbol MTK --decimals 2 --initial-supply 1000000

# 2. Associate recipient account
hcli token associate --token MTK --account 0.0.67890:302e...key...

# 3. Transfer tokens
hcli token transfer-ft --token MTK --to 0.0.67890 --amount 100

ERC-20 コントラクトのデプロイと操作

# 1. Deploy built-in ERC-20 template
hcli contract create --name myErc20 --default erc20 --constructor-parameter "MyToken" --constructor-parameter "MTK"

# 2. Check balance
hcli contract-erc20 balance-of --contract myErc20 --account 0.0.12345

# 3. Transfer via contract
hcli contract-erc20 transfer --contract myErc20 --to 0.0.67890 --value 50

複数のトークンをまとめてミント

# 1. Create batch
hcli batch create --name mintBatch --key 0.0.12345:302e...key...

# 2. Add transactions to batch (using --batch flag on batchify-compatible commands)
hcli token mint-ft --token MTK --amount 1000 --supply-key 0.0.12345:302e...key... --batch mintBatch

# 3. Execute batch
hcli batch execute --name mintBatch