Hedera CLI

Introduction to Hedera CLI

The Hedera 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.

Who Is It For?

• Developers Building and Testing: This is ideal for developers looking for a quick way to interact with Hedera to set up a testing environment with multiple accounts, tokens, topics, etc.

• Automation Enthusiasts: If you prefer to integrate simple scripts and command-based automation with your CI/CD pipelines or routine operations, the Hedera CLI offers a clean, command-oriented approach using "script blocks." These allow you to chain commands together and pass variables dynamically between them.

• Experimenters: This is perfect for those who want to validate network behaviors or run quick experiments without delving into Hedera's implementation details.

---

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)

Follow the installation steps in the Hedera CLI repository.

https://github.com/hashgraph/hedera-cli

---

Key Features

Feature 1: Multi-Network Execution

The network use <network>command gives you the ability to switch between different networks if you have configured accounts for each of the Hedera networks.

Feature 2: Script Blocks

Script blocks allow you to chain multiple commands to prepare a testing environment on a specific network. Let's take a look at some examples.

A. Simple account and token creation

The script block switches to the testnet and then creates an account with a randomly generated alias. The command uses the --args parameter to store variables, which we can reference in future commands in the script block. For example, we store the privateKeyof the account as myAdminKey . Next, we create a new token and use the accountAlias variable as the token name. We also set the stored privateKey as the admin key for the token.

{
  "name": "random-token-create",
  "commands": [
    "network use testnet",
    "account create -a random --args privateKey,myAdminKey --args alias,accountAlias",
    "token create -n {{accountAlias}} --symbol rand --decimals 2 --initial-supply 1000 --supply-type infinite --admin-key {{myAdminKey}} --treasury-id 0.0.4536940 --treasury-key 302302[...]"
  ]
}

B. Advanced token creation and transfer

The following example is a bit more complex. Here's a breakdown:

• Create three random accounts and store key variables like the private key, alias, and account ID.

• Create a token called mytoken and use account 1 as the admin key and account 2 as the treasury account. Again, we store the token ID in a variable conveniently called tokenId .

• Associate account 3 with our newly created token and transfer one unit of our token from account 2 to account 3. The wait command has been added to make sure the operation has been completed.

• Let's wait three seconds to make sure the mirror nodes have picked up the balance changes, then look up the balance for account 3 for our newly created token. Finally, we print the stored state for our new token to the terminal.

{
  "name": "transfer",
  "commands": [
    "network use testnet",
    "account create -a random --args privateKey,privKeyAcc1 --args alias,aliasAcc1 --args accountId,idAcc1",
    "account create -a random --args privateKey,privKeyAcc2 --args alias,aliasAcc2 --args accountId,idAcc2",
    "account create -a random --args privateKey,privKeyAcc3 --args alias,aliasAcc3 --args accountId,idAcc3",
    "token create -n mytoken -s MTK -d 2 -i 1000 --supply-type infinite -a {{privKeyAcc1}} -t {{idAcc2}} -k {{privKeyAcc2}} --args tokenId,tokenId",
    "token associate --account-id {{idAcc3}} --token-id {{tokenId}}",
    "token transfer -t {{tokenId}} -b 1 --from {{aliasAcc2}} --to {{aliasAcc3}}",
    "wait 3",
    "account balance --account-id-or-alias {{aliasAcc3}} --token-id {{tokenId}}",
    "state view --token-id {{tokenId}}"
  ]
}

Scripts can also be downloaded from external sources using the state download command to make it easier to set up your Hedera CLI in CI/CD pipelines.

Feature 3: State Management

The Hedera CLI tool tracks state. Each account, token, or topic you create gets stored in its internal state. Additionally, you can assign aliases to each entity type to make it easier to reference them, eliminating the need to remember account IDs or private keys. The tool automatically looks up the account alias in the state and signs a transaction using the found account's private key. This makes it a lot easier to execute commands.

Additionally, you can create state backups or download a state file from an external location. This is useful if you want to use the same base state to run your tests. It also avoids the need to prepare the testing environment manually.

Feature 4: Supports Local Node

You can configure the default account for the Hedera Local Node in your Hedera CLI tool so you can run tests locally on your local node.

💡 Feature Requests?

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

---

Future Roadmap

Upcoming roadmap work includes:

• Telemetry: Collect anonymized data to better understand how developers use the tool to make it better. We only collect commands without parameters or sensitive data. For example, we collect account create or state view .

• Smart Contracts: Deploying and interacting with smart contracts.

• Sign module: Rework the key signing module to make it more flexible.

---

Commands Overview

Setup Commands: Designed to initialize and configure your working environment.

setup init
setup reload

Network Commands: Designed to manage and interact with the different Hedera network environments.

network use
network list

Wait Command: Designed to pause the execution of commands. Useful to wait for mirror nodes to receive data.

wait

Account Commands: Designed to manage accounts.

account create
account balance
account list
account import
account clear
account delete
account view

Token Commands: Designed to create, associate, and transfer tokens.

token create-from-file
token create
token associate
token transfer

Topic Commands: Designed to create topics and retrieve information for topics.

topic create
topic list
topic message submit
topic message find

HBAR Commands: Designed to transfer HBAR.

hbar transfer

Backup Commands: Designed to create state backups.

backup create
backup restore

State Commands: Designed to manage and view state.

state download
state view
state clear

Script Commands: Designed to load and execute scripts.

script load
script list
script delete

---

Additional Resources

• Hedera CLI Repository
• CLI Full List of Commands
• Learn about Script Blocks and how you can use dynamic variables