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.
- 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.
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.
{% @github-files/github-code-block url="https://github.com/hashgraph/hedera-cli" %}
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.
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.
{% code overflow="wrap" %}
{
"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[...]"
]
}{% endcode %}
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
mytokenand use account 1 as the admin key and account 2 as the treasury account. Again, we store the token ID in a variable conveniently calledtokenId. - 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.
{% code overflow="wrap" %}
{
"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}}"
]
}{% endcode %}
{% hint style="success" %}
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.
{% endhint %}
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.
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.
{% hint style="info" %}
Feel free to contribute to the Hedera CLI or submit a feature request or bug via the issues tab. {% endhint %}
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 createorstate view. - Smart Contracts: Deploying and interacting with smart contracts.
- Sign module: Rework the key signing module to make it more flexible.
Setup Commands: |
Network Commands: |
Wait Command: |
Account Commands: |
Token Commands: |
Topic Commands: |
HBAR Commands: |
Backup Commands: |
State Commands: |
Script Commands: |
- Hedera CLI Repository
- CLI Full List of Commands
- Learn about Script Blocks and how you can use dynamic variables