# Hiero CLI > Use when user wants to interact with Hedera blockchain: create/transfer tokens, manage NFTs, deploy contracts, manage topics, transfer HBAR, sign x402 payment challenges, configure networks. ALSO use when an HTTP request returns 402 with a PAYMENT-REQUIRED header for the Hedera x402 scheme (or the user wants to pay an x402-gated endpoint on Hedera): read references/x402.md for the full GET→402→sign→retry flow. Provides full spec for hcli CLI tool. Trigger keywords: hedera, hiero, hbar, token, nft, contract, topic, x402, 402, payment-required, hcli, ledger - Skill: `hedera-dev/hiero-cli` (Agent Skill, multi-file: 19 files) - Install (CLI): `npx skillmds@latest add hedera-dev/hiero-cli` - Raw SKILL.md: https://api.skillmd.com/api/skills/hedera-dev/hiero-cli/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: hedera-dev (https://skillmd.com/u/hedera-dev) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/hedera-dev/hiero-cli --- # 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 [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 :` ## 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 ` (`-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/.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 ` / `-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: > `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 :` 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) ```bash hcli network use --global testnet hcli network set-operator --operator 0.0.12345:302e...privatekey... ``` ### Create fungible token and transfer ```bash # 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 ```bash # 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 ```bash # 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 ```