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.
Binary syntax
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 |
Prerequisites
Before executing blockchain commands:
- Configure network:
hcli network use --global testnet - Set 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
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 |
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)
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 |
Agent instruction
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.
x402 paid endpoints
If fetching a URL returns HTTP 402 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.
hcli not found / not installed
If any hcli command fails with a "command not found" or similar error, tell the user:
hcliis not installed or not available in PATH. Docs & quick start: https://www.npmjs.com/package/@hiero-ledger/hiero-cli#quick-startInstall with:
npm install -g @hiero-ledger/hiero-cliWould you like me to run the install command for you?
Do not run the install automatically — wait for the user's confirmation.
Operator not configured
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
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
Common workflows
Setup (first time)
hcli network use --global testnet
hcli network set-operator --operator 0.0.12345:302e...privatekey...
Create fungible token and transfer
# 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
Deploy ERC-20 contract and interact
# 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
Batch multiple token mints
# 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