hiero-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

hiero-cli (hcli)

hcli

is a command-line tool for interacting with the Hedera blockchain — managing accounts, tokens (FT/NFT), smart contracts, consensus topics, and network configuration.

hcli

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

Binary syntax

命令语法

hcli <plugin> <command> [options]

hcli <plugin> <command> [options]

Global flags

全局标志

Flag	Short	Default	Description
`--format`	`-F`	`human`	Output format: `human` or `json`
`--network`	`-N`	active	Override active network for this command
`--payer`	`-P`	operator	Override payer account for this command; defaults to operator if omitted
`--confirm`	`-Y`	`false`	Skip all confirmation prompts
`--max-transaction-fee`	`-M`	config	Max transaction fee ceiling for this run: HBAR (e.g. `20` ) or tinybars ( `200000000t` ). Overrides the `default_max_transaction_fee` config; `0` means no override

标志	简写	默认值	描述
`--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` 表示不覆盖

Prerequisites

前置条件

Before executing blockchain commands:

Configure network:
```
hcli network use --global testnet
```

Set operator:

hcli network set-operator --operator <accountId>:<privateKey>

执行区块链命令之前：

配置网络：
```
hcli network use --global testnet
```

设置operator：

hcli network set-operator --operator <accountId>:<privateKey>

Key formats

密钥格式

Keys and signers accept multiple formats:

{accountId}:{privateKey}

— inline pair, e.g.

0.0.123:abc123...

```
{ed25519|ecdsa}:private:{hex}
```
— raw private key with type prefix
```
{ed25519|ecdsa}:public:{hex}
```
— raw public key (for supply/submit keys)
```
kr_xxx
```
— key reference stored in KMS
account alias — name registered in local state

密钥和签名者支持多种格式：

{accountId}:{privateKey}

— 内联对，例如

0.0.123:abc123...

```
{ed25519|ecdsa}:private:{hex}
```
— 带类型前缀的原始私钥
```
{ed25519|ecdsa}:public:{hex}
```
— 原始公钥（用于供应/提交密钥）
```
kr_xxx
```
— 存储在KMS中的密钥引用
账户别名 — 在本地状态中注册的名称

Local state storage

本地状态存储

State is persisted in

~/.hiero-cli/state/

as JSON files, one per plugin namespace:

Plugin	File
`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`

状态以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`

Amount notation

金额表示法

```
"1"
```
= 1 display unit (e.g. 1 HBAR, or 1 token with decimals applied)
```
"100t"
```
= 100 base/raw units (tinybars for HBAR, smallest token unit)

```
"1"
```
= 1个显示单位（例如1 HBAR，或应用了小数位数的1个代币）
```
"100t"
```
= 100个基础/原始单位（HBAR对应tinybars，即代币最小单位）

Plugin catalog

插件目录

Plugin	Description	Tasks covered
`account`	Manage Hedera accounts	create, import, balance, list, view, update, delete, clear
`hbar`	Transfer HBAR	transfer HBAR, approve/revoke HBAR allowance
`token`	Manage FT & NFT tokens	create-ft/nft, create-from-file, mint, burn, wipe, transfer, airdrop, associate, dissociate, freeze/unfreeze, pause/unpause, grant/revoke KYC, allowance (FT/NFT), delete-allowance-nft, update-metadata-nft, pending-airdrops, cancel/claim/reject-airdrop, list, view, import, delete
`topic`	Hedera Consensus Service	create, update, submit/find messages, import, list, delete
`schedule`	Scheduled transactions	create schedule record, sign pending schedule, delete schedule, verify execution state, list schedules. Use `--scheduled <name>` ( `-X` ) only on commands marked `[scheduled]` in the plugin reference
`contract`	Smart contract lifecycle	compile + deploy Solidity, import, list, delete
`contract-erc20`	ERC-20 contract calls	name, symbol, decimals, balanceOf, transfer, transferFrom, approve, allowance, totalSupply. Requires `contract` plugin (contract must be deployed first)
`contract-erc721`	ERC-721 contract calls	balanceOf, ownerOf, approve, setApprovalForAll, safeTransferFrom, transferFrom, mint, name, symbol, tokenURI, getApproved, isApprovedForAll. Requires `contract` plugin (contract must be deployed first)
`network`	Network configuration	list networks, switch network, set/get operator
`config`	CLI configuration	list, get, set config options
`credentials`	Key/credentials management	generate new key, import existing key, list, remove stored credentials (by id or alias)
`batch`	Batch transactions	create batch, add transactions, execute, list, delete
`swap`	Multi-party asset exchange	create swap, add HBAR/FT/NFT transfers, view, list, execute, delete
`eip712`	EIP-712 typed data signing	`hash` compute digest, `sign-ecdsa` / `sign-ed25519` sign payload (accepts pre-computed hash or domain+types+message), `verify-ecdsa` recover signer EVM address, `verify-ed25519` verify Ed25519 signature against a public key
`x402`	x402 payment signing	sign a `PAYMENT-REQUIRED` challenge into a `PAYMENT-SIGNATURE` header via KMS; payer key never exposed, facilitator submits
`plugin-management`	Plugin lifecycle	add, remove, enable, disable, list, reset, info

插件	描述	涵盖任务
`account`	管理Hedera账户	创建、导入、查询余额、列表、查看、更新、删除、清除
`hbar`	转移HBAR	转移HBAR、批准/撤销HBAR额度
`token`	管理FT和NFT代币	创建FT/NFT、从文件创建、铸造、销毁、擦除、转移、空投、关联、解除关联、冻结/解冻、暂停/恢复、授予/撤销KYC、额度（FT/NFT）、删除NFT额度、更新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`	网络配置	列出网络、切换网络、设置/获取operator
`config`	CLI配置	列出、获取、设置配置项
`credentials`	密钥/凭证管理	生成新密钥、导入现有密钥、列出、删除存储的凭证（按ID或别名）
`batch`	批量交易	创建批量、添加交易、执行、列表、删除
`swap`	多方资产交换	创建交换、添加HBAR/FT/NFT转账、查看、列表、执行、删除
`eip712`	EIP-712类型化数据签名	`hash` 计算摘要， `sign-ecdsa` / `sign-ed25519` 签名payload（支持预计算的哈希或域名+类型+消息）， `verify-ecdsa` 恢复签名者的EVM地址， `verify-ed25519` 验证Ed25519签名与公钥是否匹配
`x402`	x402支付签名	通过KMS将 `PAYMENT-REQUIRED` 挑战签名为 `PAYMENT-SIGNATURE` 头；付款方密钥永不暴露，由协助方提交
`plugin-management`	插件生命周期	添加、移除、启用、禁用、列表、重置、信息

Agent instruction

Agent指令

Before executing any command, read
references/<plugin>.md
for the full command spec, all options, and examples.

Example: to use

hcli token create-ft

, first read

references/token.md

When working with batch commands, read both
references/batch.md
AND the reference for the plugin being batched.

Example: to batch

hcli token mint-ft

, read both

references/batch.md

and

references/token.md

When working with scheduled transactions, read
references/schedule.md
AND the reference for the command being scheduled.

Only commands marked [scheduled] in their reference support

--scheduled <name>

-X

Example: to schedule

hcli token burn-ft

, read both

references/schedule.md

and

references/token.md

执行任何命令之前，请阅读
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 paid endpoints

x402付费端点

If fetching a URL returns HTTP

with a

PAYMENT-REQUIRED

header, the endpoint is x402-gated. Inspect the header payload: if its

accepts

lists a

hedera:mainnet

hedera:testnet

exact

requirement, read
references/x402.md
and follow the flow there. The agent makes the HTTP requests itself;

hcli x402 sign

only produces the

PAYMENT-SIGNATURE

value. If the challenge is for a non-Hedera scheme, this CLI cannot sign it.

如果请求URL返回HTTP

状态码并带有

PAYMENT-REQUIRED

头，则该端点是x402门禁的。检查头payload：如果其

accepts

列表中包含

hedera:mainnet

hedera:testnet

的

exact

要求，请阅读
references/x402.md
并遵循其中的流程。Agent会自行发起HTTP请求；

hcli x402 sign

仅生成

PAYMENT-SIGNATURE

值。如果挑战是针对非Hedera方案的，此CLI无法对其签名。

hcli not found / not installed

未找到hcli / 未安装

If any

hcli

command fails with a "command not found" or similar error, tell the user:

hcli
is not installed or not available in PATH. Docs & quick start: https://www.npmjs.com/package/@hiero-ledger/hiero-cli#quick-start
Install with:
npm install -g @hiero-ledger/hiero-cli
Would you like me to run the install command for you?

Do not run the install automatically — wait for the user's confirmation.

如果任何

hcli

命令失败并出现“command not found”或类似错误，请告知用户：

hcli
未安装或不在PATH中。文档与快速入门：https://www.npmjs.com/package/@hiero-ledger/hiero-cli#quick-start
安装命令：
npm install -g @hiero-ledger/hiero-cli
你是否需要我帮你运行安装命令？

请勿自动运行安装命令 — 请等待用户确认。

Operator not configured

Operator未配置

If a command fails with

CLI operator is not configured

or similar:

Inform the user the operator must be set before running any blockchain command

Guide them:

hcli network set-operator --operator <accountId>:<privateKey>

Retry the original command after operator is set

如果命令失败并出现

CLI operator is not configured

或类似错误：

告知用户在运行任何区块链命令之前必须设置operator

指导他们执行：

hcli network set-operator --operator <accountId>:<privateKey>

设置好operator后重试原始命令

Disabled plugin recovery

禁用插件恢复

If a command fails with

Plugin 'X' is disabled.

Inform the user that the plugin is disabled
Offer to enable it:
```
hcli plugin-management enable --name X
```
Retry the original command after enabling

如果命令失败并出现

Plugin 'X' is disabled.

错误：

告知用户该插件已被禁用
提议启用它：
```
hcli plugin-management enable --name X
```
启用后重试原始命令

Common workflows

常用工作流

Setup (first time)

首次设置

bash

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

bash

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

Create fungible token and transfer

创建同质化代币并转账

bash

undefined

bash

undefined

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

undefined

hcli token transfer-ft --token MTK --to 0.0.67890 --amount 100

undefined

Deploy ERC-20 contract and interact

部署ERC-20合约并交互

bash

undefined

bash

undefined

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

undefined

hcli contract-erc20 transfer --contract myErc20 --to 0.0.67890 --value 50

undefined

Batch multiple token mints

批量铸造多个代币

bash

undefined

bash

undefined

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

undefined

hcli batch execute --name mintBatch

undefined