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: LTS 16.20.2 or higher
• Hedera Account (for mainnet, testnet, or previewnet) or Hedera Local Node (for localnet)

The easiest way to get started with Hiero CLI is to install it globally via NPM:

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

Once installed, you can use the CLI with the hcli command:

# Check available commands
hcli --help

# Example: Check account balance
hcli account balance --account-id 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 (Build custom plugins)

Manual Setup (For Developers)

If you want to contribute to the development of the Hiero CLI or create your own version or plugins, follow these instructions.

Prerequisites

• Node.js installation: LTS 16.20.2 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 available 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 flags are available on all Hiero CLI commands. They control output, help, and versioning, regardless of the specific plugin or command you’re using.

• --format <type>: Controls how command output is formatted.
  Supported values human (default) or json for machine-readable output.
• -h, --help: Displays help information for a command.
• -V, --version: Outputs the installed Hiero CLI version.

Plugins Overview

Credentials Plugin

Manage operator credentials and keys

Network Plugin

Switch networks, manage operator credentials, and check network health

HBAR Plugin

Transfer HBAR between accounts

Account Plugin

Create, import, manage accounts, and view balances

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

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.