Overview

Introduction to Hiero CLI

The Hiero CLI is a command‑line interface that offers a simple way to interact with the Hedera network. It consolidates many common network operations into easy-to‑use commands so you can:

• Test your Hedera applications quickly.
• Automate repetitive tasks without writing bulky code.
• Simplify key management, letting you focus on building and scaling your solutions.

---

Getting Started

Prerequisites:

• Node.js installation: 18.0.0 or higher
• Hedera Account (for mainnet, testnet, or previewnet) or Hedera Local Node (for localnet)

Install the CLI globally with npm:

npm install -g @hiero-ledger/hiero-cli

On macOS you can also install with Homebrew:

brew install hiero-ledger/tools/hiero-cli

Once installed, use the hcli command:

# Check available commands
hcli --help

# Example: Check account balance
hcli account balance --account 0.0.123456

# Example: Transfer HBAR
hcli hbar transfer --to 0.0.123456 --amount 10

First-time setup (Initialization):

When you run any command that requires an operator (like transferring HBAR or creating tokens) in interactive mode, the CLI will automatically launch an initialization wizard to guide you through configuring the operator account, private key, and settings. In script mode (non-interactive), an error will be thrown instead, requiring you to use hcli network set-operator to configure the operator first.

Manual Setup (For Developers)

Manual Setup (For Developers)

If you want to contribute to the development of the Hiero CLI or run it from source, follow these instructions.

Prerequisites

• Node.js installation: 18.0.0 or higher
• Hedera Account (for mainnet, testnet, or previewnet) or Hedera Local Node (for localnet)
• Git

Step 1: Clone the repository

git clone https://github.com/hiero-ledger/hiero-cli.git

Step 2: Install dependencies

cd hiero-cli
npm install

Step 3: Build the package

npm run build

Step 4: CLI Initialization

The Hiero CLI initializes automatically when you run any command. The CLI loads default plugins and registers their commands. No manual setup is required.

When you first run the CLI, it will:

• Load all default plugins from dist/plugins/
• Initialize the Core API with the selected output format
• Register all plugin commands
• Use testnet as the default network

Note: There is a test plugin in the repository that is required for running integration tests.

You can verify the installation by checking available commands:

node dist/hiero-cli.js --help

Step 5: Set Up Operator Credentials

To interact with Hedera networks, you need to configure operator credentials for each network you want to use. Use the network plugin’s set-operator command:

# Set operator for testnet using account name (if already imported)
node dist/hiero-cli.js network set-operator --operator my-testnet-account --network testnet

# Set operator for testnet using account-id:private-key pair
node dist/hiero-cli.js network set-operator --operator 0.0.123456:302e020100300506032b657004220420... --network testnet

# Set operator for mainnet
node dist/hiero-cli.js network set-operator --operator 0.0.123456:302e020100300506032b657004220420... --network mainnet

The operator credentials are stored in the CLI’s state management system. Make sure that each operator account contains at least 1 HBAR for transaction fees.

Step 6: Setting Up an Alias (Optional)

To avoid typing the full command each time, you can set an alias in your shell profile. Replace the path with the absolute path to your hiero-cli installation.

macOS / Linux (bash/zsh)

Add the following line to your ~/.bashrc, ~/.bash_profile, or ~/.zshrc:

alias hcli="node /path/to/hiero-cli/dist/hiero-cli.js"

Then reload your shell:

# For bash
source ~/.bashrc

# or
source ~/.bash_profile

# For zsh
source ~/.zshrc

Windows (PowerShell)

Add the following line to your PowerShell profile. First, open PowerShell and check if your profile exists:

# Check if profile exists
Test-Path $PROFILE

# If it doesn't exist, create it
New-Item -ItemType File -Path $PROFILE -Force

Then add the following function to your profile:

function hcli {
node C:\path\to\hiero-cli\dist\hiero-cli.js @args
}

Then reload your PowerShell:

. $PROFILE

Now you can use hcli with arguments just like on Unix systems.

Global Flags

These options are defined on the root hcli program (see hcli --help). They work together with each command’s own flags.

• --format <type>: Output format: human (default) or json for machine-readable output.
• -N, --network <network>: Target network: testnet, mainnet, previewnet, or localnet. Runs the command against this network without necessarily changing your saved default (see the Network plugin for switching defaults).
• -P, --payer <payer>: Payer for transactions in this command: account alias, or account-id:private-key format. Overrides the default operator as payer when supported by the command.
• --confirm: Skip interactive confirmation prompts for commands that would otherwise ask for confirmation (for example, some delete operations).
• -h, --help: Show help for the current command.
• -V, --version: Print the installed Hiero CLI version.

Configuration and State

Runtime state (accounts, tokens, operator settings, and other plugin data) is stored under your home directory by default:

• Default directory: ~/.hiero-cli/state/

Each plugin uses its own JSON files there. You normally should not edit them by hand.

Key storage supports two modes:

• local — keys stored in plain text in the state directory (typical for development)
• local_encrypted — keys encrypted with AES-256-GCM before storage (stronger protection)

Set the default storage mode with the Config plugin:

hcli config set -o default_key_manager -v local
hcli config set -o default_key_manager -v local_encrypted

Override per command with --key-manager where the command supports it (for example account import or network set-operator). Details are covered in the plugin reference pages.

Local Hedera Network (Localnet)

To use the CLI against a local Hedera node, configure an operator for localnet and select that network. Default connection settings shipped with the CLI match the usual local node layout (see src/core/services/network/network.config.ts in the Hiero CLI repository).

Example:

hcli network set-operator --operator 0.0.2:302e020100300506032b65700123456789132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137 --network localnet
hcli network use --global localnet

Use an operator key and account ID that match your local node setup; the values above are only an illustration from the Hiero CLI README.

Plugins Overview

The CLI loads a fixed set of default plugins. The pages below document the shipped plugins and their CLI commands.

Network Plugin

Switch networks, manage operator credentials, and check network health

Credentials Plugin

Manage operator credentials and keys

Account Plugin

Create, import, manage accounts, and view balances

HBAR Plugin

Transfer HBAR between accounts

Token Plugin

Create, associate, and transfer tokens

Topic Plugin

Create topics and manage topic messages

Config Plugin

Inspect and update CLI configuration values

Plugin Management Plugin

Add, remove, enable/disable, and inspect plugins

Batch Plugin

Create, execute, list, and delete batches of Hedera transactions

Schedule Plugin

Create, sign, delete, and verify Hedera scheduled transactions

Contract Plugin

Compile, deploy, import, list, and delete Solidity smart contracts

Contract ERC-20 Plugin

Call ERC-20 view and state-changing functions on deployed contracts

Contract ERC-721 Plugin

Call ERC-721 view and state-changing functions on deployed NFT contracts

Scripting

Once you’re familiar with the available CLI commands, you can take the next step with scripting. Scripting is especially useful for CI/CD pipelines, setting up test environments, and automating repeated workflows.

Scripting Quickstart

Learn how to create your first script using Hiero CLI commands.

Contributing

💡 Feature Requests?

Feel free to contribute to the Hiero CLI or submit a feature request or bug via the issues tab.