IOTA Keytool CLI
The IOTA CLI keytool command provides several command-level access for the management and generation of addresses, as well as working with private keys, or signatures. For example, a user could export a private key from the IOTA Wallet and import it into the local IOTA CLI wallet using the iota keytool import [...] command.
Check IOTA CLI installation
Before you can use the IOTA CLI, you must install it. To check if the CLI exists on your system, open a terminal or console and type the following command:
iota --version
If the terminal or console responds with a version number, you already have the IOTA CLI installed.
If the command is not found, follow the instructions in Install IOTA to get the IOTA CLI on your system.
Commands
Usage: iota keytool [OPTIONS] <COMMAND>
Commands:
update-alias Update an old alias to a new one. If a new alias is not provided, a random one will be generated
convert Convert private key in Hex or Base64 to new format (Bech32 encoded 33 byte flag || private key starting with "iotaprivkey"). Hex private key format import and
export are both deprecated in IOTA Wallet and IOTA CLI Keystore. Use `iota keytool import` if you wish to import a key to IOTA Keystore
decode-or-verify-tx Given a Base64 encoded transaction bytes, decode its components. If a signature is provided, verify the signature against the transaction and output the result
decode-multi-sig Given a Base64 encoded MultiSig signature, decode its components. If tx_bytes is passed in, verify the multisig
generate Generate a new keypair with key scheme flag {ed25519 | secp256k1 | secp256r1} with optional derivation path, default to m/44'/4218'/0'/0'/0' for ed25519 or
m/54'/4218'/0'/0/0 for secp256k1 or m/74'/4218'/0'/0/0 for secp256r1. Word length can be { word12 | word15 | word18 | word21 | word24} default to word12 if not
specified
import Add a new key to IOTA CLI Keystore using either the input mnemonic phrase or a Bech32 encoded 33-byte `flag || privkey` starting with "iotaprivkey", the key
scheme flag {ed25519 | secp256k1 | secp256r1} and an optional derivation path, default to m/44'/4218'/0'/0'/0' for ed25519 or m/54'/4218'/0'/0/0 for secp256k1
or m/74'/4218'/0'/0/0 for secp256r1. Supports mnemonic phrase of word length 12, 15, 18, 21, 24. Set an alias for the key with the --alias flag. If no alias is
provided, the tool will automatically generate one
export Output the private key of the given key identity in IOTA CLI Keystore as Bech32 encoded string starting with `iotaprivkey`
list List all keys by its IOTA address, Base64 encoded public key, key scheme name in iota.keystore
multi-sig-address To MultiSig IOTA Address. Pass in a list of all public keys `flag || pk` in Base64. See `keytool list` for example public keys
multi-sig-combine-partial-sig Provides a list of participating signatures (`flag || sig || pk` encoded in Base64), threshold, a list of all public keys and a list of their weights that
define the MultiSig address. Returns a valid MultiSig signature and its sender address. The result can be used as signature field for `iota client
execute-signed-tx`. The sum of weights of all signatures must be >= the threshold
show Read the content at the provided file path. The accepted format can be [enum IotaKeyPair] (Base64 encoded of 33-byte `flag || privkey`) or `type
AuthorityKeyPair` (Base64 encoded `privkey`). It prints its Base64 encoded public key and the key scheme flag
sign Create signature using the private key for the given address (or its alias) in iota keystore. Any signature commits to a [struct IntentMessage] consisting
of the Base64 encoded of the BCS serialized transaction bytes itself and its intent. If intent is absent, default will be used
sign-kms Creates a signature by leveraging AWS KMS. Pass in a key-id to leverage Amazon KMS to sign a message and the base64 pubkey. Generate PubKey from pem using
iotaledger/base64pemkey Any signature commits to a [struct IntentMessage] consisting of the Base64 encoded of the BCS serialized transaction bytes itself and
its intent. If intent is absent, default will be used
help Print this message or the help of the given subcommand(s)
Options:
--keystore-path <KEYSTORE_PATH>
--json Return command outputs in json format
-h, --help Print help
-V, --version Print version
JSON output
Append the --json flag to commands to format responses in JSON instead of the more human friendly default IOTA CLI output. This can be useful for extremely large datasets, for example, as those results can have a troublesome display on smaller screens. In these cases, the --json flag is useful.
Examples
The following examples demonstrate some of the most often used commands.
List the key pairs in the local wallet
Use the iota keytool list command to output all the IOTA addresses that exist in the ~/.iota/iota_config/iota.keystore file in a readable format.
$ iota keytool list
╭────────────────────────────────────────────────────────────────────────────────────────────╮
│ ╭─────────────────┬──────────────────────────────────────────────────────────────────────╮ │
│ │ iotaAddress │ 0x3047f142a84297a42a65fb0a8c7a716d9d1b0bd0413d6bfa5ddfec45df175235 │ │
│ │ publicBase64Key │ exfBzFpY1o20IgizPC7tXYboc7xo0zXn3zD/zLTMjmo= │ │
│ │ keyScheme │ ed25519 │ │
│ │ flag │ 0 │ │
│ │ peerId │ 7b17c1cc5a58d68db42208b33c2eed5d86e873bc68d335e7df30ffccb4cc8e6a │ │
│ ╰─────────────────┴──────────────────────────────────────────────────────────────────────╯ │
│ ╭─────────────────┬──────────────────────────────────────────────────────────────────────╮ │
│ │ iotaAddress │ 0x514692f08249c3e9957799ce29074695840422564bff85e424b56de462913e0d │ │
│ │ publicBase64Key │ okIaLxHxOyWFh07Y4ciMjqtuv62jV5H6+U6OKAtjpJc= │ │
│ │ keyScheme │ ed25519 │ │
│ │ flag │ 0 │ │
│ │ peerId │ a2421a2f11f13b2585874ed8e1c88c8eab6ebfada35791faf94e8e280b63a497 │ │
│ ╰─────────────────┴──────────────────────────────────────────────────────────────────────╯ │
╰────────────────────────────────────────────────────────────────────────────────────────────╯
Generate a new key pair and store it in a file
To generate a new key pair with the ed25519 scheme, use the iota keytool generate ed25519 command. For other schemes, see iota keytool generate –help. The key pair file is saved to the current directory with its filename being the address. The content of the file is a Base64 encoded string of 33-byte flag || privkey.
$ iota keytool generate ed25519
╭─────────────────┬───────────────────────────────────────────────────────────────────────────────────╮
│ iotaAddress │ 0x5d8aa70f17d9343813d3ba6a59ecf5e8a23ffb487938e860999a722989eaef25 │
│ publicBase64Key │ pMAZ/2K/Qmp4tdeWyvg9TMFdv1VjyUrvGJkxLnQZK7o= │
│ keyScheme │ ed25519 │
│ flag │ 0 │
│ mnemonic │ cushion price ability recall payment embody kid media rude mosquito chalk broom │
│ peerId │ a4c019ff62bf426a78b5d796caf83d4cc15dbf5563c94aef1899312e74192bba │
╰─────────────────┴───────────────────────────────────────────────────────────────────────────────────╯
Show the key pair data from a file
Use iota keytool show [filename] to show the key pair data that is stored in a file. For example, the previous command generated a file named 0x5d8aa70f17d9343813d3ba6a59ecf5e8a23ffb487938e860999a722989eaef25.key.
$ iota keytool show 0x5d8aa70f17d9343813d3ba6a59ecf5e8a23ffb487938e860999a722989eaef25.key
╭─────────────────┬──────────────────────────────────────────────────────────────────────╮
│ iotaAddress │ 0x5d8aa70f17d9343813d3ba6a59ecf5e8a23ffb487938e860999a722989eaef25 │
│ publicBase64Key │ L4ApMAZ/2K/Qmp4tdeWyvg9TMFdv1VjyUrvGJkxLnQZK7g== │
│ keyScheme │ ed25519 │
│ flag │ 0 │
│ peerId │ a4c019ff62bf426a78b5d796caf83d4cc15dbf5563c94aef1899312e74192bba │
╰─────────────────┴──────────────────────────────────────────────────────────────────────╯
Sign a transaction
$ iota keytool sign --data AAABACBRRpLwgknD6ZV3mc4pB0aVhAQiVkv/heQktW3kYpE+DQEBAQABAAAwR/FCqEKXpCpl+wqMenFtnRsL0EE9a/pd3+xF3xdSNQEaEUeErlBmGWxz3Bh+9BZh2mzayodzsri7xIZNDHRA3wIAAAAAAAAAILsR2d1FIZ5+ADDYZtJ2e9CWlpAxsGd4Y2rZrjlyTUF1MEfxQqhCl6QqZfsKjHpxbZ0bC9BBPWv6Xd/sRd8XUjXoAwAAAAAAAICWmAAAAAAAAA== --address 0x3047f142a84297a42a65fb0a8c7a716d9d1b0bd0413d6bfa5ddfec45df175235
╭───────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────╮
│ iotaAddress │ 0x3047f142a84297a42a65fb0a8c7a716d9d1b0bd0413d6bfa5ddfec45df175235 │
│ rawTxData │ AAABACBRRpLwgknD6ZV3mc4pB0aVhAQiVkv/heQktW3kYpE+DQEBAQABAAAwR/FCqEKXpCpl+wqMenFtnRsL0EE9a/pd3+xF3xdSNQEaEUeErlBmGWxz3Bh+9BZh2mzayodzsri7xIZNDHRA3wIAAAAAAAAAILsR │
│ │ 2d1FIZ5+ADDYZtJ2e9CWlpAxsGd4Y2rZrjlyTUF1MEfxQqhCl6QqZfsKjHpxbZ0bC9BBPWv6Xd/sRd8XUjXoAwAAAAAAAICWmAAAAAAAAA== │
│ intent │ ╭─────────┬─────╮ │
│ │ │ scope │ 0 │ │
│ │ │ version │ 0 │ │
│ │ │ app_id │ 0 │ │
│ │ ╰─────────┴─────╯ │
│ rawIntentMsg │ AAAAAAABACBRRpLwgknD6ZV3mc4pB0aVhAQiVkv/heQktW3kYpE+DQEBAQABAAAwR/FCqEKXpCpl+wqMenFtnRsL0EE9a/pd3+xF3xdSNQEaEUeErlBmGWxz3Bh+9BZh2mzayodzsri7xIZNDHRA3wIAAAAAAAAA │
│ │ ILsR2d1FIZ5+ADDYZtJ2e9CWlpAxsGd4Y2rZrjlyTUF1MEfxQqhCl6QqZfsKjHpxbZ0bC9BBPWv6Xd/sRd8XUjXoAwAAAAAAAICWmAAAAAAAAA== │
│ digest │ +B8Cbr16HfOVT50DoN/QF8HB0+oznm8KAYy8Rm+TQFo= │
│ iotaSignature │ ANucBEl9TIE0uv+w965DvOjlfDUll7NUtIpJgRhPc3D3y3EtZ4cvaNbm8i5pc7TNIov/qI0FhzIYf2J6PbqoNQ57F8HMWljWjbQiCLM8Lu1dhuhzvGjTNeffMP/MtMyOag== │
╰───────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Help
Each command has its own help section. For example iota keytool sign –help displays the following prompt:
$ iota keytool sign --help
Create signature using the private key for the given address in iota keystore. Any signature commits to a [struct IntentMessage] consisting of the Base64 encoded of the BCS serialized
transaction bytes itself and its intent. If intent is absent, default will be used
Usage: iota keytool sign [OPTIONS] --address <ADDRESS> --data <DATA>
Options:
--address <ADDRESS>
--data <DATA>
--json Return command outputs in json format
--intent <INTENT>
-h, --help Print help
-V, --version Print version