Skip to content

SKILL.md

Latest commit

 

History

History
185 lines (133 loc) · 13 KB

SKILL.md

File metadata and controls

185 lines (133 loc) · 13 KB
Raw
Error in user YAML: (<unknown>): mapping values are not allowed in this context at line 2 column 68
---
name: hiero-cli
description: Use when user wants to interact with Hedera blockchain: create/transfer
  tokens, manage NFTs, deploy contracts, manage topics, transfer HBAR, configure
  networks. Provides full spec for hcli CLI tool. Trigger keywords: hedera, hiero,
  hbar, token, nft, contract, topic, hcli, ledger
---

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:

  1. Configure network: hcli network use --global testnet
  2. 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
faucet Testnet/previewnet faucet request — disburse up to 100 HBAR to any account ID, EVM address, or alias. Requires Portal PAT configured via hcli config set --portal_pat
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.

hcli not found / not installed

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.

Operator not configured

If a command fails with CLI operator is not configured or similar:

  1. Inform the user the operator must be set before running any blockchain command
  2. Guide them: hcli network set-operator --operator <accountId>:<privateKey>
  3. Retry the original command after operator is set

Disabled plugin recovery

If a command fails with Plugin 'X' is disabled.:

  1. Inform the user that the plugin is disabled
  2. Offer to enable it: hcli plugin-management enable --name X
  3. 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