KADENA CLI

The Kadena CLI embodies our commitment to simplicity, power, and flexibility for developers. It's crafted to streamline your development process, offering direct and efficient access to Kadena's blockchain capabilities. This tool caters to the pragmatic needs of developers by providing a straightforward, command-line interface that integrates seamlessly into your workflow, allowing you to focus on building robust, innovative applications without the overhead of unnecessary complexity. Our philosophy centers on empowering developers with the tools they need to unlock the full potential of the kadena blockchain, in a clear and concise manner.

Welcome to the Kadena CLI guide, your all-encompassing manual for mastering the Kadena command-line interface. This document is designed to unveil the full suite of commands available through Kadena CLI, providing you with the insights necessary to harness its potential fully.

Kadena CLI has one primary entry-point command: kadena, dedicated to application development, offering tools and commands tailored for building and managing Kadena-based applications.

Each command can be made interactive by not filling in the flags. You can prefill a question by filling the flag

The Quiet Mode feature of the Kadena CLI can be used to streamline the automation of tasks, specifically targeting environments where interactive input is impractical, such as continuous integration (CI) systems. By activating Quiet Mode, the CLI suppresses interactive prompts and skips confirmations, allowing commands to execute uninterrupted. This mode ensures that automated processes can run smoothly and efficiently, without the need for manual intervention.

Using --json or --yaml will output relevant command result data in json or yaml format on stdout. This can be used to pipe into a file or other programs. Do be aware that this does not remove the regular logging which happens on stderr. It will not get in the way of piping since that only uses stdout by default. You can disable the other logging by using the KADENA_LOG=output environment variable. This does still print warnings or errors if they are present.

Example usage

Legacy Mode offers a bridge for users requiring compatibility with the previously used crypto algo, particularly for commands related to wallets, keys, and transactions. This mode ensures the output format aligns with earlier standards, facilitating seamless integration with existing workflows and tools such as Chainweaver. It's especially useful when interacting with systems that rely on the legacy format for processing or when maintaining backward compatibility is critical.

Legacy mode is available for the following commands:

Interactive Mode is designed to make command execution more intuitive and user-friendly. When you run a command in the Kadena CLI without specifying all required options, the CLI automatically prompts you to provide the missing inputs. This guided approach helps streamline your workflow and ensures that you provide all necessary information to successfully execute a command.

To use Interactive Mode, simply type a command without its options:

If the CLI is not running in Quiet Mode (--quiet), it will detect the missing elements needed for the command to run and will prompt you interactively to input them. This means you can start a command with minimal initial input and fill in the details as prompted by the CLI.

If you want to add a new wallet but aren't sure of all the required flags and arguments, simply start with:

The CLI will then guide you through the necessary steps, asking for each required piece of information to complete the wallet addition.

Interactive mode is especially useful for new users or those who prefer a more guided approach when using command-line tools. It also serves as a learning tool by demonstrating the required inputs for various commands, enhancing your familiarity with the CLI's functionalities.

Each command is structured as kadena <subject> [...<subject>] <verb> [--flags] [args] apart from some root level defaults.

Available subjects

To get help on a subject use kadena <subject> --help

Tool for setting up and managing the CLI configuration

The kadena config init command is your starting point. It creates a .kadena folder pre configured with default network settings (devnet, mainnet, testnet). You have the flexibility to specify the location of your .kadena folder, making it easier to organize your configurations either in the current working directory or a global directory such as your home directory.

Additionally, this command assists in the creation of your initial wallet and account, setting the stage for your transactions on the Kadena network.

Local: by default the config is written to .kadena and this is accessible from anywhere in this directory. For example running kadena config init in /home/user/projects/my-kadena-project will allow you to access this configuration from anywhere inside that project directory.

Global: if passing the --global (or -g) flag the configuration is stored in your home directory in .config/kadena. This will allow you to use this configuration from anywhere on your system. Do be aware local configurations have priority. You can use kadena config path to validate which path is being used when in a certain directory.

Setup in a the current working directory with a new Wallet and Account:

Setup in the home user directory (~/.config/kadena). This will allow you to use the cli from anywhere and use this configuration.

Setup without creating a Wallet or Account:

Note: All configurations will be stored within the specified .kadena/ folder, ensuring your settings are organized and easily accessible.

Tool to add and manage networks

Example for setting default network:

Example for removing default network:

Passing a network as "none" will remove the default network.

Passing a network as "none" will remove the default network.

Tool to generate and manage wallets

example using wallet with account creation:

Generate a key pair from a wallet mnemonic.

Example generating public keys using a range (you will be prompted for password):

Example passing password from a file:

Example passing password from a standard input (stdin):

Example generating a key at a specific starting index index:

Example single wallet deletion:

Example deletion of all wallets:

Example for listing specific wallet:

Example for listing all wallets:

Export a KeyPair from a wallet unencrypted. Prints to stdout as yaml by default

Example (password will be prompted):

Print as json (password will be prompted):

Tool to generate and manage keys

Generate a plain keypair using a random mnemonic.

Example for listing all keys:

Tool to manage / fund accounts of fungibles (e.g. coin')

Adds a new account with customizable parameters based on the specified type(wallet or manual).

Common Options

These options are required when the account type is set to wallet:

--password-file option is required only when you choose auto generate keys from wallet.

Example for adding an account with wallet type:

Example for adding an account with wallet type and auto generate keys:

As part of manual option only if you want to verify the account details on the blockchain, you need to provide the network and chain-id.

Example for adding an account with manual type and verifying on chain(assume if account already exists on chain):

Example for adding an account with manual type and not verifying on chain:

The kadena account details command retrieves vital information about a specified account on the Kadena blockchain, such as its balance, guard conditions (public keys, predicate), and the account's name.

Single chain ID using an account alias:

Note: Fungible type is retrieved from the account alias file.

Single chain ID using account name:

Note: Specify --fungible if using an account name. Defaults to "coin" if not provided.

You can specify a range of chain IDs to query multiple chains at once. Use a comma for discrete values or a hyphen for a continuous range.

Discrete Chain IDs:

Continuous Range of Chain IDs:

All Chains: Use "all" to query details across all chains.

The kadena account fund command is used to add funds to an account on the testnet or development networks. This command also creates the account if it does not exist. Remember, this operation is not allowed on the mainnet.

If a faucet contract isn't available on the development network for the specified chain ID, you can use the --deploy-faucet option. This will deploy the faucet, allowing you to fund accounts on the development network.

Fund an account on a specific chain:

Fund an account on a devnet with deploying faucet:

Note: To deploy a faucet on the development network, please make sure devnet is running and accessible. To setup devnet, please refer here

You can specify a range of chain IDs to fund an account across multiple chains. Use a comma for discrete values or a hyphen for a continuous range.

Discrete Chain IDs:

Continuous Range of Chain IDs:

All Chains: Use "all" to fund an account across all chains on the testnet.

Example for listing specific account:

Example for listing all accounts:

Example for delete a specific account:

Example for delete all accounts:

Tool for creating and managing transactions

kadena tx add is a powerful command that leverages transaction templates to facilitate the quick and efficient creation of transactions across multiple chains and access patterns. This feature is designed to work with user-supplied values, filling out predefined templates to generate transactions ready for signing and submission.

This command accepts various arguments and options, allowing for detailed customization of the transaction being created. Below is a breakdown of the options available:

In this example, transfer.yaml is the template used to construct the transaction. data.yaml contains the user-supplied values for the template variables. The --network-id specifies which network the transaction is intended for, and --out-file determines where the generated transaction file will be saved.

The kadena tx add command in the Kadena CLI includes a set of default templates that are designed to facilitate the quick and efficient creation of transactions. These templates are integral to the command's functionality and enhance user experience by providing predefined frameworks for common transaction types.

When you use the kadena tx add command for the first time, the CLI automatically creates and stores default templates in the .kadena/transaction-templates directory on your local machine. This directory serves as the central repository for these templates, allowing easy access and customization.

Currently, the CLI comes with two primary default templates:

These templates are designed to cover the most common types of transactions, making it easier for users to execute these operations without the need to write or customize code.

While default templates offer convenience and speed, you might sometimes need to customize or extend these templates to fit specific needs or to handle unique transaction types. The CLI allows you to either modify existing templates or create new ones from scratch and save them in the .kadena/transaction-templates directory.

By understanding and utilizing these default templates, you can significantly streamline your transaction creation processes with the Kadena CLI, making it a powerful tool for managing blockchain transactions efficiently.

Below is a YAML template transfer.yaml that outlines the structure for a coin transfer operation on Kadena. Notice the use of placeholders with prefixes to define expected data types for each field:

This template exemplifies how variables and prefixes guide users in providing the correct types of input values, significantly reducing the potential for errors when the CLI is operated in its interactive mode. In this mode, the prefixes play a crucial role in prompting users for the specific type of information required, ensuring the accuracy and validity of the transaction data. This interactive guidance simplifies the transaction creation process, enhancing the security and reliability of the transactions constructed.

Variables are a critical part of transaction templates, defining the data required to construct a transaction. Users can be prompted for variables missing from the --template-data file or not provided as command-line options. The --holes option is particularly useful for identifying all the variables a template requires.

Variables support specific prefixes (account:, key:, network:, decimal:) to facilitate the correct selection or validation of input values in interactive mode.

account: This prefix is used for variables that should be filled with an account name, guiding users to input valid Kadena account identifiers.

key: Variables with this prefix expect a public key, ensuring that users provide cryptographic keys in the correct format.

network: This prefix is used for specifying the network ID, helping users to select the appropriate network for their transaction.

decimal: For variables that involve numerical values with decimal points, this prefix ensures the format and precision of the input.

In contrast, when operating in non-interactive mode, the system relies on options passed directly via the command line. In this scenario, the values for the transaction are provided as options, and the prefixes are ignored. This means that the responsibility for ensuring the correctness and appropriateness of the input values shifts entirely to the user. It's crucial for users to be mindful of the data types and formats expected by the template to avoid errors. This method allows for a more streamlined and automated approach to transaction creation, suitable for users who prefer script-based automation or who are running the CLI in environments where interactive prompts are not feasible.

Below is a YAML example data.yaml for transfer.yaml that outlines the structure for a template data file.

password will be hidden after entry: --security-password=*

Testing a signed transaction for its viability against a specified network by making a Local call. Using the local API endpoints, you can dry-run Pact smart contracts using actual data in the coin contract tables. This is perfect for checking the viability of your transactions / smart contracts, as well as to check account data without necessarily having to spend tokens.

The kadena tx status command is used to retrieve the status of a transaction on the Kadena blockchain. By providing a transaction request key and specifying the network and chain id, users can query the current state of their transactions. This command supports additional options for polling, allowing for real-time status updates until the transaction is finalized.

To check the status of a transaction, use the following command:

This will return the current status of the transaction identified by the provided request key.

With Polling: To continuously monitor the status of a transaction until it is finalized, add the --poll option:

Polling checks the transaction status in real-time and will keep running until the transaction is confirmed.

The default timeout for polling is 60 seconds, but it will attempt to keep polling until confirmation is achieved.

Example:

Tool for creating dapp projects

It supports a number of well known and widely used frameworks to choose from when starting a new project. The following project templates are currently available: