@hashgraph/hedera-cli
Advanced tools
CLI tool to manage and setup developer environments for Hedera Hashgraph.
Welcome to the Hedera CLI Tool, a powerful and intuitive command-line interface designed to streamline your interactions with the Hedera network. Whether you're a developer needing to set up test environments, automate network-related tasks, or explore the extensive capabilities of the Hedera mainnet and testnet, this tool is your one-stop solution.
The Hedera CLI Tool elegantly addresses the complexities associated with distributed ledger technologies. It simplifies the process of executing actions such as creating new accounts, sending transactions, managing tokens, and associating with existing tokens directly from the CLI. This high level of functionality and ease of use significantly reduces the barrier to entry for developers working on Hedera-based projects.
A key advantage of the Hedera CLI Tool is its potential to enhance your workflow. It's not just about performing individual tasks; it's about integrating these tasks into a larger, more efficient development process. With plans for future integration into Continuous Integration/Continuous Deployment (CI/CD) pipelines, this tool promises to be a versatile asset in the automation and management of Hedera network operations.
🎯 Feature requests can be submitted on the Hedera CLI repository as an issue. Please check the issues before submitting a new one and tag it with the
Feature Requestlabel.
Before proceeding with the installation and setup of the Hedera CLI Tool, ensure the following prerequisites are met:
The Hedera CLI Tool requires Node.js (version LTS 16.20.2 or higher). You can check your current version by running node -v in your terminal. If you do not have Node.js installed, you can download it from Node.js official website.
You will need an account on the Hedera network to interact with the ledger. Follow these steps to set up your account:
OPERATOR_KEY, and the account ID is your OPERATOR_ID. These credentials are essential for authenticating and performing operations using the Hedera CLI Tool.Make sure to securely store your DER encoded private key and account ID, as they are crucial for accessing and managing your Hedera account.
Make sure to clone the repository. You can do this by running the following command in your terminal:
git clone https://github.com/hashgraph/hedera-cli.git
Navigate to the repository folder and install the necessary packages using npm. This sets up everything you need to get started with the Hedera CLI Tool.
cd hedera-cli && npm install
Compile the package to ensure all components are ready for use.
npm run build
Make a copy of the .env.sample file to create your own .env file. This file will store your operator credentials securely.
cp .env.sample .env
Add your operator ID and key for previewnet, testnet, and mainnet. It's not mandatory to set keys for all networks. If you only want to use one network, you can leave the other credentials blank. Make sure that each operator account contains at least 1 Hbar. We've added the default account for the Hiero Local Node.
PREVIEWNET_OPERATOR_KEY=
PREVIEWNET_OPERATOR_ID=
TESTNET_OPERATOR_KEY=
TESTNET_OPERATOR_ID=
MAINNET_OPERATOR_KEY=
MAINNET_OPERATOR_ID=
LOCALNET_OPERATOR_ID=0.0.2
LOCALNET_OPERATOR_KEY=302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137
Next, set up the CLI tool with the command. The --telemetry flag is optional and enables telemetry. By default, telemetry is disabled. Hedera collects anonymous data to improve the CLI tool. For example, it records the command name, not the parameters or any other sensitive information. If you don't want us to collect telemetry data, run the command without the --telemetry flag.
node dist/hedera-cli.js setup init --telemetry
The setup init command will also create the different operator accounts in your address book (dist/state/state.json file) so you can use them in your commands.
You can verify the installation by listing all accounts in your address book. When you first run this command, you'll see the operator keys you've defined.
node dist/hedera-cli.js account list
testnet-operator, 0.0.2224463, ED25519
preview-operator, 0.0.1110, ECDSA
[...]
When first using the network, the CLI tool will use the testnet network. You can switch to the mainnet or other networks like previewnet or localnet using the following command:
node dist/hedera-cli.js network use mainnet
To avoid typing the full command each time, you can set an alias in your shell profile. For example, in bash or Z shell, you can add the following line to your .bashrc/.bash_profile or .zshrc. Replace the path with the absolute path to your hedera-cli installation path.
alias hcli="node /Users/myUser/hedera-cli/dist/hedera-cli.js"
Make sure you reload your shell, whether it's bashrc, zshrc, or another shell profile.
source ~/.bashrc
You can verify the alias by listing all accounts in your address book.
hcli account list
If you haven't added any accounts yet, you should see the same output like in step 5.
You can download example scripts from the examples file and add them to your state. This allows you to quickly test the CLI tool and see how scripting functionality works. You can download the example scripts using the following command:
node dist/hedera-cli.js state download --url https://raw.githubusercontent.com/hashgraph/hedera-cli/main/src/commands/script/examples.json --merge
The Hedera CLI tool can be used to interact with a local Hedera network. This is useful for testing and development purposes. To connect the CLI tool with your local Hedera network, you need to set up a local Hedera network. You can follow the instructions in the Hedera documentation to set up a local Hedera network.
By default, the src/state/config.ts file contains the default configuration for the localnet. You can change the configuration to match your local network by editing the src/state/config.ts file and then setting the operator key and ID using the setup init command. The default configuration for the localnet is:
{
"localNodeAddress": "127.0.0.1:50211",
"localNodeAccountId": "0.0.3",
"localNodeMirrorAddressGRPC": "127.0.0.1:5600"
}
The localnet network can be configured in your .env file, so you can use the setup init command to add the localnet operator key and ID to your state. The default values for the localnet operator key and ID are:
LOCALNET_OPERATOR_ID=0.0.2
LOCALNET_OPERATOR_KEY=302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137
Learn how to use the Hedera CLI Tool by watching the video below.
Video coming soon ⚠️
Let's explore the different commands, their options, and outputs.
Each of the commands can be run with the
--helpflag to display the command's options and usage.Use the
--quietflag to suppress the output of the command or the--verboseflag to display more information.
The setup command is an essential component of the Hedera CLI tool, designed to initialize and configure your working environment. This command facilitates the process of setting up the CLI with your operator key and ID.
setup init
setup reload
1. Initialization: Sets up the CLI with the operator key and ID.
hcli setup init [--telemetry]
Flags:
When executed, the setup command performs several key functions:
Environment Variable Validation:
It reads the PREVIEWNET_OPERATOR_KEY, PREVIEWNET_OPERATOR_KEY, TESTNET_OPERATOR_KEY, TESTNET_OPERATOR_ID, MAINNET_OPERATOR_KEY, MAINNET_OPERATOR_ID, LOCALNET_OPERATOR_ID, and LOCALNET_OPERATOR_KEY variables from the .env file in the root of the CLI project.
State Update:
Once the localnet, previewnet, testnet, and mainnet operator key and ID are validated, these credentials are used to update the dist/state/state.json file, which holds the configuration state of the CLI tool. The command will also add the operator accounts to your address book.
2. Reload Operator Key and Id:
Reload the operator key and ID from the .env file. This command is useful when you add new networks to your .env file and want to update the state, so you can use the new networks.
hcli setup reload [--telemetry]
Flags:
The telemetry command in the Hedera CLI tool is designed to enable or disable telemetry. This feature allows users to opt-in or opt-out of telemetry data collection. Hedera anonymizes data and only records the command name, not the parameters or any other sensitive information. For example, it records account create but not the account alias or ID. The data is used to improve the CLI tool and provide better features and functionality, by trying to understand how users use the CLI. However, the CLI tool uses a UUID to identify the user, so no personal information is collected. This allows us to better understand how users interact with the CLI tool.
telemetry enable
telemetry disable
1. Enable telemetry:
This command enables telemetry and sets the telemetry variable in the state to 1.
hcli telemetry enable
2. Disable telemetry:
This command disables telemetry and sets the telemetry variable in the state to 0.
hcli telemetry disable
The CLI tool uses Hardhat for all smart contract interactions. There are no dedicated commands for smart contracts in the CLI tool. Instead, you can use the Hardhat commands to deploy and interact with smart contracts.
Contracts are stored in the src/contracts folder. You can create a new contract by adding a new file in this folder. By default, you can find an erc20.sol and erc721.sol files.
To deploy a smart contract and interact with it, you can use the Hardhat scripts. The CLI tool stores the scripts in the src/contracts/scripts folder. You can create a new script by adding a new file in this folder. By default, you can find a deploy.js file that demonstrates how to deploy the erc20.sol contract.
Make sure the your hardhat.config.js file is configured correctly to interact with one of the Hedera networks. By default, the CLI tool uses the local network, which is configured for the Hedera Local Node. You can add the mainnet, testnet, or previewnet networks to the Hardhat configuration file.
A sample config is included in the project. If you configure the
mainnet,testnet, orpreviewnetnetworks, make sure to set the operator key and ID in your.envfile in the HEX format. You can see the example config reads the operator key from the.envfile using, for example theprocess.env.TESTNET_OPERATOR_KEY_HEX. Don't forget to set these HEX-based variables in your.envfile.
{
// ... other Hardhat configuration options
defaultNetwork: 'local',
networks: {
/*mainnet: {
url: stateController.default.get('rpcUrlMainnet'),
accounts: [process.env.MAINNET_OPERATOR_KEY_HEX],
chainId: 295,
},*/
/*testnet: {
url: stateController.default.get('rpcUrlTestnet'),
accounts: [process.env.TESTNET_OPERATOR_KEY_HEX],
},*/
/*previewnet: {
url: stateController.default.get('rpcUrlPreviewnet'),
accounts: [process.env.PREVIEWNET_OPERATOR_KEY_HEX],
chainId: 297,
},*/
local: {
url: 'http://localhost:7546',
accounts: [
'0x105d050185ccb907fba04dd92d8de9e32c18305e097ab41dadda21489a211524',
'0x2e1d968b041d84dd120a5860cee60cd83f9374ef527ca86996317ada3d0d03e7'
],
chainId: 298,
},
}
}
Note: If you configure an account but don't provide a URL or accounts array, the CLI tool will fail upon starting. Make sure to provide a valid URL and accounts array for the network you want to use. If you don't want to use a network, leave it commented out.
If you have added new Hardhat scripts to src/contracts/scripts, you need to compile the contracts first. You can do this by running the following command in the root of the CLI tool:
npx hardhat compile
This command compiles the contracts and generates the necessary artifacts in the dist/contracts folder. The compiled contracts will be used by the Hardhat scripts to deploy and interact with the contracts.
To run a script, make sure to point to the dist folder (after running npm run build) and use the hardhat run command. For example, to deploy the erc721.sol contract, you can run the following command in the root of the CLI tool:
npx hardhat run ./dist/contracts/scripts/deploy.js --network local
The script feature let's you execute script blocks. Here's how you can integrate Hardhat commands into the CLI tool's script feature:
"scripts": {
"script-deploy": {
"name": "deploy",
"creation": 1742830623351,
"commands": [
"hardhat compile",
"hardhat run ./dist/contracts/scripts/deploy.js",
"hardhat run ./dist/contracts/scripts/mint.js"
],
"args": {}
}
}
Next, it's possible to store data from Hardhat scripts in the args field of the script block you are executing. For example, this allows you to deploy a smart contract and store the contract address in the args field. You can then reference it as a varaible in other commands in this script block or use it in other Hardhat scripts.
const stateController = require('../../state/stateController.js').default; // default import
async function main() {
const [deployer] = await ethers.getSigners();
console.log('Deploying contracts with the account:', deployer.address);
// The deployer will also be the owner of our token contract
const ERC721Token = await ethers.getContractFactory('ERC721Token', deployer);
const contract = await ERC721Token.deploy(deployer.address);
await contract.waitForDeployment();
const contractAddress = await contract.getAddress();
console.log('ERC721 Token contract deployed at:', contractAddress);
// Store address in script arguments as "erc721address"
stateController.saveScriptArgument('erc721address', contractAddress);
}
main().catch(console.error);
In this example, the erc721address variable is stored in the args object of the script you are executing. You can then use this variable in other scripts by retrieving it again (stateController.getScriptArgument(erc721address)) and using it in your Hardhat scripts.
Don't forget to use .default when importing the stateController in your Hardhat scripts, as shown above.
As mentioned, you can build interesting script blocks that combine regular CLI command and the execution of Hardhat scripts. This allows you to automate the deployment and interaction with smart contracts directly from the CLI tool.
{
"name": "hardhat-deploy",
"commands": [
"hardhat compile",
"hardhat run ./dist/contracts/scripts/deploy.js --network local", // stores the contract ID as "erc721address" in the script args
"account create -a {{erc721address}}" // Create a new account and set the alias name equal to the contract address (just an example)
],
"args": {}
}
The network command in the Hedera CLI tool is designed to manage and interact with different Hedera networks. It allows users to switch between networks and list available networks. This flexibility is crucial for developers who need to test their applications in different network environments.
network use
network list
1. Switching Networks:
This command switches the current network context to the specified network.
hcli network use <name>
Replace <name> with the name of the network you wish to switch to (mainnet, testnet, previewnet, or localnet running the Hedera network locally).
2. Listing Available Networks:
This command lists all available networks you've configured for the CLI tool. It's useful for confirming the network options and ensuring correct network names are used when switching networks.
hcli network list
// Available networks: mainnet, testnet, previewnet, localnet
The network command includes a catch-all for unknown subcommands. If an unrecognized command is entered, it triggers an error message and displays the help text for the network command.
// Invalid network name. Available networks: mainnet, testnet, previewnet, and localnet
The wait command in the Hedera CLI tool is designed to pause the execution of commands for a specified amount of time. This command is useful for waiting for transactions to be confirmed on the network or the mirror node to update before executing subsequent commands.
hcli wait <seconds>
// Example
hcli wait 3
The wait command is used in the examples section below.
The account command in the Hedera CLI tool encompasses a suite of subcommands designed for managing Hedera accounts. These subcommands provide functionalities for creating new accounts, retrieving account balances, listing accounts in the address book, importing existing accounts, and clearing the address book.
account create
account balance
account list
account import
account clear
account delete
account view
1. Create a New Account:
Initializes a new Hedera account with a specified alias, balance, and type. The balance and type are optional and have defaults if not specified. If you set the --alias random flag, the CLI tool will generate a random 20-character long alias.
hcli account create -a,--alias <alias> [-b,--balance <balance>] [-t,--type <type>]
// Example
hcli account create -a alice -b 100000000 -t ECDSA
hcli account create -a random
Flags:
random, the CLI tool will generate a random 20-character long alias.ECDSA or ED25519). Defaults to ED25519.Note: Setting the
<alias>torandomwill generate a random 20-char long alias. This is useful for scripting functionality to avoid running into non-unique alias errors. It's not allowed to use the word operator as an alias or as part of an alias because it's reserved for the operator accounts.
2. Retrieve Account Balance:
Displays the balance of a specified account. Users can choose to view only the Hbar balance or the balance of a specific token. It's not possible to use both options at once.
hcli account balance -a,--account-id-or-alias <accountIdOrAlias> [-h,--only-hbar] [-t,--token-id <tokenId>]
// Output
Balance for account 0.0.5892294:
1000 hbars
Token balances:
0.0.5892308: 2
3. List All Accounts:
Lists all accounts stored in the address book. An optional flag allows displaying private keys.
hcli account list [-p,--private]
// Example output with -p flag
Accounts:
- Alias: bob
Account ID: 0.0.4536938
Type: ECDSA
Private Key: 30300201[...]
Flags:
4. Import an Existing Account:
Allows users to import an existing account into the CLI tool using the account's alias, ID, type, and optionally private key. You can import accounts without a private key, but you won't be able to sign transactions with them.
hcli account import -a,--alias <alias> -i,--id <id> [-k,--key <key>]
// Example
hcli account import -a alice -i 0.0.5892294 -k 30300201[...]
hcli account import -a alice -i 0.0.12450
Flags:
5. Clear All Accounts:
Removes all account information from the address book.
hcli account clear
6. Delete an Account:
Deletes an account from the address book by its alias or ID, don't use both at the same time. If you don't provide an alias or ID, the CLI tool will prompt you to select an account from your address book.
hcli account delete [-a,--alias <alias>] [-i,--id <id>]
Flags:
7. View Account Information:
Displays detailed information about a specified account by its ID. The account can be in the CLI's state or on the Hedera network.
hcli account view -i,--id <id>
// Output
Account: 0.0.5401160
Balance Tinybars: 1000000000
Deleted: false
EVM Address: 0x0000000000000000000000000000000000526a48
Key type: ED25519 - Key: 4832f1d396ff123e4e[...]
Max automatic token associations: 0
Flags:
The token command in the Hedera CLI tool provides functionality for creating, associating, and transferring tokens on the Hedera network. It includes subcommands for creating fungible tokens, associating tokens, and transferring tokens between accounts.
token create-from-file
token create
token associate
token transfer
1. Create Token from File:
This command allows users to create a new token by specifying a JSON file that contains the token's configuration. Files are stored in the dist/input folder of the project using the format token.<filename>.json. Replace <filename> with your desired filename.
hcli token create-from-file -f,--file <filename>
Flags:
A token input file looks like below. You can define all properties you would normally define when using using the SDK to create a token. All of the properties are required except for the min/max values for custom fractional fees. If you don't need a key, leave it as an empty string.
{
"name": "myToken",
"symbol": "MTK",
"decimals": 2,
"supplyType": "finite",
"initialSupply": 1000,
"maxSupply": 1000000,
"keys": {
"supplyKey": "<alias:bob>",
"treasuryKey": "<alias:alice>",
"adminKey": "<newkey:ecdsa:10000>",
"feeScheduleKey": "",
"freezeKey": "",
"wipeKey": "",
"pauseKey": "",
"kycKey": ""
},
"customFees": [
{
"type": "fixed",
"unitType": "token",
"amount": 1,
"denom": "0.0.3609946",
"exempt": true,
"collectorId": "0.0.2221463"
},
{
"type": "fractional",
"numerator": 1,
"denominator": 100,
"exempt": true,
"collectorId": "0.0.2221463"
}
],
"memo": "Test token"
}
Note: that you can use placeholders for all keys on a token. The format
<alias:bob>refers to an account with aliasbobin your address book. It will use Bob's key.You can also tell the CLI tool to create a new account with an account type (
ecdsaored25519) and an initial balance in TinyBars. The<newkey:ecdsa:10000>placeholder creates a new ECDSA account with 10,000 TinyBars and uses its key for the admin key.
Here's how custom fees are defined in the token input file:
"customFees": [
{
"type": "fixed", // Indicates a fixed fee
"unitType": "token", // Indicates the denomination of the fee: "token", "hbar", or "tinybar"
"amount": 1, // Amount of the fee
"denom": "0.0.3609946", // If the unit type is "token", then you need to set a denominating token ID to collect the fees in
"exempt": true, // If true, exempts all the token's fee collector accounts from this fee.
"collectorId": "0.0.2221463" // Sets the fee collector account ID that collects the fee.
},
{
"type": "fractional", // Indicates a fractional fee
"numerator": 1, // Numerator of the fractional fee
"denominator": 100, // Denominator of the fractional fee: 1/100 = 1% fee on the transfer
"min": 1, // Optional: Minimum fee user has to pay
"max": 100, // Optional: Maximum fee user has to pay because fractional fees can become very costly
"exempt": true, // If true, exempts all the token's fee collector accounts from this fee.
"collectorId": "0.0.2221463" // Sets the fee collector account ID that collects the fee.
}
]
2. Create Fungible Token:
Creates a new fungible token with specified properties like name, symbol, treasury ID, treasury key, decimals, initial supply, and admin key.
hcli token create --treasury-id <treasuryId> --treasury-key <treasuryKey> --name <name> --symbol <symbol> --decimals <decimals> --supply-type <supplyType> --initial-supply <initialSupply> --admin-key <adminKey>
Flags:
finite or infinite.Note: It's better to use the
token create-from-fileif you want to set all properties for a token. Thetoken createcommand only allows for a couple of options.
3. Associate Token with Account:
Associates a specified token with an account. Both the token ID and the account ID (or alias) are required.
hcli token associate -a,--account-id <accountId> -t,--token-id <tokenId>
// Example
hcli token associate -a bob -t 0.0.5892309
Flags:
4. Transfer Fungible Token:
Facilitates the transfer of a specified amount of a fungible token from one account to another.
hcli token transfer -t,--token-id <tokenId> --to <to> --from <from> -b,--balance <balance>
Flags:
The topic command in the Hedera CLI tool provides functionality for creating topics and retrieving information about topics on the Hedera network.
topic create
topic list
topic message submit
topic message find
1. Create Topic:
Creates a new topic with a specified memo, submit key, and admin key. If you don't provide any options, a public topic will be generated. Setting the submit key creates a private topic. If you don't set an admin key, the topic is immutable.
hcli topic create [-s,--submit-key <submitKey>] [-a,--admin-key <adminKey>] [--memo <memo>]
Flags:
2. List Topics:
Lists all topics on the Hedera network known by the CLI tool.
hcli topic list
3. Submit Message to Topic:
Submits a message to a specified topic.
hcli topic message submit -t,--topic-id <topicId> -m,--message <message>
Flags:
4. Find Messages for Topic:
Finds messages for a specified topic by its sequence number.
hcli topic message find -t,--topic-id <topicId> [-s,--sequence-number <sequenceNumber>] [--sequence-number-gt <sequenceNumberGreaterThan>] [--sequence-number-lt <sequenceNumberLessThan>] [--sequence-number-gte <sequenceNumberGreaterThanOrEqual>] [--sequence-number-lte <sequenceNumberLessThanOrEqual>] [--sequence-number-eq <sequenceNumberEqual>] [--sequence-number-ne <sequenceNumberNotEqual>]
Flags:
The hbar command in the Hedera CLI tool is designed for transferring hbars between accounts.
hcli hbar transfer -b,--balance <balance> [-f,--from <from>] [-t,--to <to>]
// Example
hcli hbar transfer -f alice -t bob -b 1000
hcli hbar transfer -f alice -t 0.0.12345 -b 1000
Flags:
Note: If you don't specify a
fromortoaccount, the CLI tool will prompt you to select an account from your address book, listed by alias.
The backup command in the Hedera CLI tool is designed for creating backups of the state.json file, which contains configuration and state information.
backup create
backup restore
1. Creating Backup:
This command creates a backup of the state.json file. The backup file is named using a timestamp for easy identification and recovery. The format is: state.backup.<timestamp>.json. The backup is stored in the same dist/state directory as state.json. It's possible to provide a custom name for the backup file: state.backup.<name>.json.
Further, you can also provide a custom path for your backup, which is useful if you want to export a clean testing state in another application that can be used to run E2E tests.
hcli backup create [--path <path>] [--name <name>] [--accounts] [--safe]
// Example
hcli backup create --name e2e --path /Users/myUser/projects/xyz/
hcli backup create --accounts --safe
hcli backup create --safe
Flags:
state.backup.<timestamp>.json.accounts.backup.<timestamp>.json.2. Restoring Backup:
This command restores a backup of the state.json file stored in the same dist/state directory, it can't detect backups stored elsewhere. It only restores state files with the format state.backup.<timestamp>.json. If you don't provide a filename, the CLI tool will list all available backups and ask you to select one.
hcli backup restore -f,--file <filename> [--restore-accounts] [--restore-tokens] [--restore-scripts]
Flags:
Example: You can combine the flags to restore only certain parts of the state. For example, you can restore only the accounts and tokens section of the state by using the following command:
hcli backup restore -f state.backup.1704321015228.json --restore-accounts --restore-tokens
Note: If you don't provide a filename, the CLI tool will list all available backups and ask you to select one. You can still use the flags to restore only certain parts of the state.
The state command in the Hedera CLI tool is designed for managing the state of the CLI tool. It allows users to view the current state, clear the state, and download a new state via a remote URL.
state download
state view
state clear
1. Download State:
Downloads a state file from an external URL and add it to the dist/state.json file. You can use this command to update your state with new accounts, tokens, or scripts. You can choose to overwrite the current state or merge the downloaded state with the current state.
hcli state download --url <url> [--overwrite] [--merge]
Flags:
Format for remote script files:
{
"accounts": {
"myalias": {
"network": "testnet",
"alias": "myalias",
"accountId": "0.0.7426198",
"type": "ecdsa",
"publicKey": "302d300706052b8104000a03220003732a9daae40e2a41ccd10dd35b521cbcafdd4bf906a66e37d0a65512a1d7db23",
"evmAddress": "a5accb5010ad3ee50c66a433d5b8fdfe0d0eab59",
"solidityAddress": "0000000000000000000000000000000000715096",
"solidityAddressFull": "0x0000000000000000000000000000000000715096",
"privateKey": "303002010030[...]"
}
},
"scripts": {
"script-script1": {
"name": "script1",
"commands": [
"account create -a alice",
"account create -a bob"
]
}
},
"tokens": {
"0.0.7426199": {
"network": "testnet",
"associations": [],
"tokenId": "0.0.7426199",
"name": "myToken",
"symbol": "MTK",
"treasuryId": "0.0.7426195",
"decimals": 2,
"initialSupply": 1000,
"supplyType": "finite",
"maxSupply": 1000000,
"keys": {
"adminKey": "303002010030[...]",
"pauseKey": "",
"kycKey": "",
"wipeKey": "",
"freezeKey": "",
"supplyKey": "302e02010030[...]",
"feeScheduleKey": "",
"treasuryKey": "302e02010030[...]"
}
}
},
"topics": {
"0.0.7426199": {
"network": "testnet",
"topicId": "0.0.7426199",
"memo": "Test topic",
"submitKey": "302a300506032b6570032100[...]",
"adminKey": "302a300506032b6570032100[...]"
}
}
}
You can access an example here. You can use it like this:
hcli state download --url https://gist.githubusercontent.com/michielmulders/f8ae878431d3d551ecf5e478e9e96ea5/raw/9d5c0329eb3fe5bfda02b8ec1880c5894bd4539e/stateUpdate.json --overwrite
2. View State:
Displays the current state of the CLI tool.
hcli state view [--accounts] [--tokens] [--scripts] [--account-alias <account-alias>] [--account-id <account-id>] [--token-id <token-id>]
Flags:
3. Clear State:
Clears the state of the CLI tool. This command is useful for resetting the state to its initial state. Depending on the flags provided, it resets the entire state or skips certain parts of the state, such as the accounts, tokens, or scripts sections in your state. For example, this might be useful when you want to reset your state but keep your address book (state.accounts).
hcli state clear [-a,--skip-accounts] [-t,--skip-tokens] [-s,--skip-scripts]
Flags:
The script command in the Hedera CLI tool allows users to load and execute script blocks. This command is particularly useful for automating repetitive tasks or for quickly setting up specific states or environments that have been captured in a script.
script load
script list
script delete
1. Load and Execute Script Blocks:
Loads a script by name from state and sequentially executes each command in the script.
hcli script load -n,--name <name>
Each command is executed via execSync, which runs the command in a synchronous child process.
2. List All Scripts:
Lists all scripts stored in the dist/state.json file.
hcli script list
3. Delete Script:
Deletes a script from the dist/state.json file.
hcli script delete -n,--name <name>
The dynamic variables feature in our script execution command (script load) allows you to store variables during script execution and reference them in other commands within the script. This feature enhances script flexibility and reusability by enabling you to replace options with arguments or state variables, and store and retrieve variables as needed.
Here's a list of all commands and the variables they expose, which you can use in your scripts.
The following example shows how you can use dynamic variables to create a script that creates three accounts, creates a token, associates the token with the third account, and transfers one token from the second account (treasury) to the third account. Then, it displays the token state and the balance of the third account. Often, it will tell you that the third account has a 0 balance because the mirror node hasn't updated yet. When a command fails, the script execution stops and the error is displayed.
{
"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}}"
],
"args": {}
}
Make sure to not use a space between the variable name and the arrow notation (
:). Otherwise, the CLI tool will not recognize the variable.--args alias:aliasAcc1is correct,--args alias : aliasAcc1is not.
The below command shows how to create a new account on testnet with 1 hbar and prints the hbar balance.
{
"name": "account-create",
"commands": [
"network use testnet",
"account create -a random -b 100000000 --type ecdsa --args privateKey:privKeyAcc1 --args alias:aliasAcc1 --args accountId:idAcc1",
"wait 3",
"account balance --account-id-or-alias {{idAcc1}} --only-hbar"
],
"args": {}
}
This example shows how to use Hardhat scripts as part of your flow, mixing it with other commands. It creates a random account, waits for 3 seconds, and then runs a Hardhat script to deploy contracts:
{
"name": "hardhat-deploy",
"commands": [
"account create -a random --args privateKey:privKeyAcc1 --args alias:aliasAcc1 --args accountId:idAcc1",
"wait 3",
"hardhat run ./dist/contracts/scripts/deploy.js --network local"
],
"args": {}
}
Not each command exposes the same variables. Here's a list of commands and the variables they expose, which you can use in your scripts.
| Command | Variables |
|---|---|
account create | alias, accountId, type, publicKey, evmAddress, solidityAddress, solidityAddressFull, privateKey |
account import | alias, accountId, type, publicKey, evmAddress, solidityAddress, solidityAddressFull, privateKey |
account view | accountId, balance, evmAddress, type, maxAutomaticTokenAssociations |
token create | tokenId, name, symbol, treasuryId, adminKey |
token create-from-file | tokenId, name, symbol, treasuryId, treasuryKey, adminKey, pauseKey, kycKey, wipeKey, freezeKey, supplyKey, feeScheduleKey |
topic create | topicId, adminKey, submitKey |
topic message submit | sequenceNumber |
The Hedera CLI tool stores its state in the dist/state/state.json file. This file contains all the information about your accounts, tokens, scripts, and network. You can edit this file manually, but it's not recommended.
Here's an example state:
{
"network": "testnet",
"mirrorNodeLocalnet": "http://localhost:5551/api/v1",
"mirrorNodePreviewnet": "https://previewnet.mirrornode.hedera.com/api/v1",
"mirrorNodeTestnet": "https://testnet.mirrornode.hedera.com/api/v1",
"mirrorNodeMainnet": "https://mainnet.mirrornode.hedera.com/api/v1",
"rpcUrlMainnet": "https://mainnet.hashio.io/api",
"rpcUrlTestnet": "https://testnet.hashio.io/api",
"rpcUrlPreviewnet": "https://previewnet.hashio.io/api",
"rpcUrlLocalnet": "http://localhost:7546",
"telemetryServer": "http://localhost:3000/track",
"localNodeAddress": "127.0.0.1:50211",
"localNodeAccountId": "0.0.3",
"localNodeMirrorAddressGRPC": "127.0.0.1:5600",
"testnetOperatorKey": "",
"testnetOperatorId": "",
"mainnetOperatorKey": "",
"mainnetOperatorId": "",
"previewnetOperatorId": "",
"previewnetOperatorKey": "",
"telemetry": 0,
"scriptExecution": 0,
"scriptExecutionName": "",
"uuid": "",
"accounts": {
"bob": {
"network": "testnet",
"alias": "bob",
"accountId": "0.0.7393086",
"type": "ED25519",
"publicKey": "302a300506032b657003210059b9fc2413aa2a1dccda4b6ea0f99a48414db6f6ad6eb28589bab12f578f8697",
"evmAddress": "",
"solidityAddress": "000000000000000000000000000000000070cf3e",
"solidityAddressFull": "0x000000000000000000000000000000000070cf3e",
"privateKey": "302e0201003005060507c46c02ad871ffc38bb216497c6ac9a34aff3ac637153815a896"
}
},
"scripts": {
"script-test": {
"name": "test",
"creation": 1697103669402,
"commands": [
"network use testnet",
"account create -a random --args privateKey:tokenMichielAdminKey --args alias:accountAlias",
"token create -n {{accountAlias}} -s mm -d 2 -i 1000 --supply-type infinite -a {{tokenMichielAdminKey}} -t 0.0.4536940 -k 302e020100300506032b6568253a539643468dda3128a734c9fcb07a927b3f742719db731f9f50"
],
"args": {}
}
},
"tokens": {
"0.0.7393102": {
"network": "testnet",
"associations": [],
"tokenId": "0.0.7393102",
"name": "myToken",
"symbol": "MTK",
"treasuryId": "0.0.7393093",
"decimals": 2,
"initialSupply": 1000,
"supplyType": "finite",
"maxSupply": 1000000,
"keys": {
"adminKey": "3030020100300506e9fdf92f82267a40c9ce7932d2622ba29aad3d8d7036dbe5d27",
"pauseKey": "",
"kycKey": "",
"wipeKey": "",
"freezeKey": "",
"supplyKey": "302e0201003005002ad871ffc38bb216497c6ac9a34aff3ac637153815a896",
"feeScheduleKey": "",
"treasuryKey": "302e0201003078aede2e6a5c46701d89ab48b3e28a31e50243bd85c19f0"
}
}
}
}
Contributions are welcome. Please see the contributing guide to see how you can get involved in the Hedera Hashgraph repositories. Below you can find some tips specific for this repository.
You can run the application in development mode. It will watch for changes in the src folder and automatically recompile the application while maintaining the dist/state.json file.
To get started, create a new state file called test_state.json in the /src/state/ folder.
cd src/state
touch test_state.json
Next, copy the contents of the src/state/base_state.json file into the test_state.json file.
Once that's done, you can start the application in development mode using the following command:
npm run dev-build
Further, you can lint or format the code using the following commands:
npm run lint
npm run format
How to handle config?
If you add features that affect the initial config, make sure to update both the state/config.ts and types/state.d.ts files.
You need to create a local clone of commander program each time you run a unit test to ensure test encapsulation: const program = new Command();
Use program.parseAsync if you are testing an asynchronous command.
const { Command } = require('commander');
const networkCommands = require("../../commands/network");
const fs = require("fs");
describe("network commands", () => {
describe("network switch command", () => {
test("switching networks successfully", () => {
// Arrange
fs.readFileSync = jest.fn(() => JSON.stringify({ network: "mainnet" })); // Mock fs.readFileSync to return a sample config
fs.writeFileSync = jest.fn(); // Mock fs.writeFileSync to do nothing
//console.log = jest.fn(); // Mock console.log to check the log messages
const program = new Command();
networkCommands(program);
// Act
program.parse(["node", "hedera-cli.js", "network", "use", "testnet"]);
// Assert
const opts = program.opts();
expect(opts.network).toBe("testnet");
// expect(program.args).toEqual(["--type", "order-cake"]);
// Check that console.log was called with the correct message
expect(console.log).toHaveBeenCalledWith("Switched to testnet");
// Check that fs.writeFileSync was called with the updated config
expect(fs.writeFileSync).toHaveBeenCalledWith(
expect.any(String), // path
JSON.stringify({ network: "testnet" }, null, 2),
"utf-8"
);
});
});
describe("network switch ls", () => {
// [...]
});
});
The E2E tests run on localnet and use the state from the dist/state/state.json file.
Dynamic variables are variables that are stored in the state and can be used in scripts. They are useful for storing information that is generated during script execution and can be used in other commands within the script.
To allow processing of dynamic variables in a command, you need to add a single line of code converting the dynamic variables in your options to their actual values. Don't forget to import the dynamicVariablesUtils which holds the replaceOptions function.
import dynamicVariablesUtils from '../../utils/dynamicVariables';
program
.command('create')
.action(async (options: CreateAccountOptions) => {
options = dynamicVariablesUtils.replaceOptions(options);
// [...]
})
To allow dynamic variables in a command, you need to add the --args flag to the command. The --args flag takes a list of arguments that are allowed to be dynamic variables.
program
.command('create')
// ...
.option(
'--args <args>',
'Store arguments for scripts',
(value: string, previous: string) =>
previous ? previous.concat(value) : [value],
[],
)
Further, for each command you want to allow the user to store variables, you need to define a command action. Command actions define the mapping between script commands and the corresponding actions. You can specify actions for different commands and use them when storing variables.
const commandActions: CommandActions = {
account: {
create: {
action: 'accountCreate',
},
import: {
action: 'accountImport',
},
},
token: {
create: {
action: 'tokenCreate',
},
createFromFile: {
action: 'tokenCreateFromFile',
}
},
};
Next, you can define command outputs for your action. Command outputs define the output variables that can be captured and stored for specific actions. You can specify the output variables for each action to use them later in the script.
const commandOutputs: CommandOutputs = {
accountCreate: {
alias: 'alias',
accountId: 'accountId',
type: 'type',
publicKey: 'publicKey',
evmAddress: 'evmAddress',
solidityAddress: 'solidityAddress',
solidityAddressFull: 'solidityAddressFull',
privateKey: 'privateKey',
},
// Define outputs for other actions here
};
Make sure that each property you define exists in the output for the command. Here's the code for the accountCreate command. The accountDetails output contains all the properties defined in the commandOutputs object. If you define a property in the commandOutputs object that doesn't exist in the accountDetails output, the script execution will fail.
.action(async (options: CreateAccountOptions) => {
options = dynamicVariablesUtils.replaceOptions(options);
try {
let accountDetails = await accountUtils.createAccount(
options.balance,
options.type,
options.alias,
);
// Store dynamic variables
dynamicVariablesUtils.storeArgs(
options.args,
dynamicVariablesUtils.commandActions.account.create.action,
accountDetails,
);
} catch (error) {
logger.error(error as object);
}
});
The storeArgs function takes the options.args and the commandAction as arguments. It then stores the output variables in the state according to the user's instructions.
Whenever changing the commandActions or commandOutputs objects, make sure to update the documentation as well.
You can use the logger object to log messages to the console. The logger object is defined in src/utils/logger.ts. It is defined as a singleton which you can import in your files.
import { Logger } from '../../utils/logger';
const logger = Logger.getInstance();
logger.log function.logger.verbose function.logger.error function which has an overload signature
logger.error(error: Error | string): Log a single object or stringlogger.error(error: string, data: object): Log an error string and objectIf you have a question on how to use the product, please see our support guide.
This project is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code of conduct.
FAQs
CLI tool to manage and setup developer environments for Hedera Hashgraph.
The npm package @hashgraph/hedera-cli receives a total of 2 weekly downloads. As such, @hashgraph/hedera-cli popularity was classified as not popular.
We found that @hashgraph/hedera-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 15 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.