hiero-cli

hiero-cli (hcli)

hcli 是一款命令行工具，可用于与 Hedera 区块链交互，管理账户、代币（FT/NFT）、智能合约、共识主题和网络配置。

二进制语法

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）或 tinybars（200000000t）。覆盖 default_max_transaction_fee 配置；0 表示不覆盖

前置条件

执行区块链命令之前：

1. 配置网络：hcli network use --global testnet
2. 设置 operator：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 中的密钥引用
• 账户别名 — 在本地状态中注册的名称

本地状态存储

状态以 JSON 文件形式持久化在 ~/.hiero-cli/state/ 中，每个插件命名空间对应一个文件：

插件	文件
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 的 tinybars，或代币的最小单位）

插件目录

插件	描述	涵盖的任务
account	管理 Hedera 账户	创建、导入、查询余额、列出、查看、更新、删除、清除
hbar	转移 HBAR	转移 HBAR、批准／撤销 HBAR 授权额度
token	管理 FT 和 NFT 代币	create-ft/nft、create-from-file、铸造、销毁、清除、转移、空投、关联、取消关联、冻结／解冻、暂停／恢复、授予／撤销 KYC、授权额度（FT/NFT）、delete-allowance-nft、update-metadata-nft、待处理空投、取消／领取／拒绝空投、列出、查看、导入、删除
topic	Hedera 共识服务	创建、更新、提交／查找消息、导入、列出、删除
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 标头；付款方密钥绝不暴露，由 facilitator 提交
plugin-management	插件生命周期	添加、移除、启用、禁用、列出、重置、查看信息

Agent 指令

执行任何命令之前，请先阅读 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 时返回 HTTP 402，且带有 PAYMENT-REQUIRED 标头，则该端点受 x402 限制。检查标头载荷：如果其 accepts 列出了 hedera:mainnet / hedera:testnet 的 exact 要求，请阅读 references/x402.md 并按照其中的流程操作。Agent 自行发起 HTTP 请求；hcli x402 sign 仅生成 PAYMENT-SIGNATURE 值。如果质询使用非 Hedera 方案，此 CLI 无法为其签名。

找不到或未安装 hcli

如果任何 hcli 命令因“找不到命令”或类似错误而失败，请告知用户：

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