sui keytool

The sui keytool command provides tools for managing cryptographic keys in the Sui keystore.

Synopsis

sui keytool [OPTIONS] <COMMAND>

Global Options

--keystore-path

path

Path to the keystore file

--json

boolean

Return command outputs in JSON format

Commands

update-alias

Update an old alias to a new one.

sui keytool update-alias <OLD_ALIAS> [NEW_ALIAS]

OLD_ALIAS

string

required

Current alias to update

NEW_ALIAS

string

New alias. If not provided, a random one will be generated

Example:

sui keytool update-alias old_wallet new_wallet
sui keytool update-alias old_wallet  # Auto-generates new alias

convert

Convert private key from Hex or Base64 to Bech32 format.

sui keytool convert <VALUE>

VALUE

string

required

Private key in Hex or Base64 format

Example:

sui keytool convert <HEX_OR_BASE64_KEY>

Output:

{
  "bech32WithFlag": "suiprivkey1...",
  "base64WithFlag": "A...",
  "hexWithoutFlag": "abc123...",
  "scheme": "ed25519"
}

Hex private key import/export is deprecated. Use Bech32 format (starting with suiprivkey) for all key operations.

decode-or-verify-tx

Decode transaction bytes or verify a signature.

sui keytool decode-or-verify-tx [OPTIONS]

--tx-bytes

string

required

Base64 encoded transaction bytes

--sig

GenericSignature

Signature to verify against the transaction

--cur-epoch

u64

default:"0"

Current epoch for verification

Example:

# Decode only
sui keytool decode-or-verify-tx --tx-bytes <BASE64_TX>

# Decode and verify
sui keytool decode-or-verify-tx \
  --tx-bytes <BASE64_TX> \
  --sig <BASE64_SIG> \
  --cur-epoch 100

decode-multi-sig

Decode a MultiSig signature and optionally verify it.

sui keytool decode-multi-sig [OPTIONS]

--multisig

MultiSig

required

MultiSig signature to decode

--tx-bytes

string

Transaction bytes to verify against (optional)

--cur-epoch

u64

default:"0"

Current epoch for verification

Example:

sui keytool decode-multi-sig \
  --multisig <BASE64_MULTISIG> \
  --tx-bytes <BASE64_TX> \
  --cur-epoch 100

generate

Generate a new keypair.

sui keytool generate <KEY_SCHEME> [DERIVATION_PATH] [WORD_LENGTH]

KEY_SCHEME

SignatureScheme

required

Key scheme: ed25519, secp256k1, or secp256r1

DERIVATION_PATH

DerivationPath

Optional derivation path. Defaults:

ed25519: m/44'/784'/0'/0'/0'
secp256k1: m/54'/784'/0'/0/0
secp256r1: m/74'/784'/0'/0/0

WORD_LENGTH

string

Mnemonic word length: word12, word15, word18, word21, or word24. Default: word12

Example:

# Generate with defaults
sui keytool generate ed25519

# Generate with custom word length
sui keytool generate secp256k1 "m/54'/784'/0'/0/0" word24

Output: Creates a .key file in current directory with filename <address>.key.

Use sui client new-address if you want to generate and save the key into sui.keystore instead.

import

Add a new key to Sui CLI Keystore.

sui keytool import [OPTIONS] <INPUT_STRING> <KEY_SCHEME> [DERIVATION_PATH]

--alias

string

Alias for this address. Must start with a letter and contain only letters, digits, hyphens (-), or underscores (_)

INPUT_STRING

string

required

Either a mnemonic phrase or Bech32 encoded private key (starting with suiprivkey)

KEY_SCHEME

SignatureScheme

required

Key scheme: ed25519, secp256k1, or secp256r1

DERIVATION_PATH

DerivationPath

Optional derivation path (only for mnemonic import)

Example:

# Import from mnemonic
sui keytool import \
  --alias my_wallet \
  "word1 word2 word3 ..." \
  ed25519

# Import from Bech32 key
sui keytool import \
  --alias my_wallet \
  "suiprivkey1..." \
  ed25519

export

Export the private key of a given key identity.

sui keytool export --key-identity <KEY_IDENTITY>

--key-identity

KeyIdentity

required

Address or alias of the key to export

Example:

sui keytool export --key-identity my_wallet

Output:

{
  "exportedPrivateKey": "suiprivkey1...",
  "key": {
    "alias": "my_wallet",
    "suiAddress": "0x...",
    "publicBase64Key": "A...",
    "keyScheme": "ed25519",
    "flag": 0
  }
}

Keep exported private keys secure. Anyone with access to the private key has full control of the associated address.

list

List all keys in sui.keystore.

sui keytool list [OPTIONS]

-s, --sort-by-alias

boolean

Sort by alias instead of address

Example:

sui keytool list
sui keytool list --sort-by-alias

Output:

╭────────────┬────────────────────┬────────────────────╮
│ alias       │ Sui Address            │ Scheme          │
├────────────┼────────────────────┼────────────────────┤
│ my_wallet   │ 0x1a2b3c...             │ ed25519         │
│ work_wallet │ 0x4d5e6f...             │ secp256k1       │
╰────────────┴────────────────────┴────────────────────╯

load-keypair

Read a keypair from a file.

sui keytool load-keypair <FILE>

FILE

path

required

Path to keypair file

Accepted formats:

SuiKeyPair: Base64 encoded 33-byte flag || privkey
AuthorityKeyPair: Base64 encoded privkey

Example:

sui keytool load-keypair ./account.key

show

Show the public key and scheme from a keypair file.

sui keytool show <FILE>

FILE

path

required

Path to keypair file

Example:

sui keytool show ./account.key

sign

Create a signature using a private key.

sui keytool sign [OPTIONS]

--address

KeyIdentity

required

Address or alias of the signer

--data

string

required

Base64 encoded BCS serialized transaction data

--intent

Intent

Intent for the signature. Default: transaction intent

Example:

sui keytool sign \
  --address my_wallet \
  --data <BASE64_TX_DATA>

Output:

{
  "suiAddress": "0x...",
  "rawTxData": "...",
  "intent": {...},
  "rawIntentMsg": "...",
  "digest": "...",
  "suiSignature": "..."
}

sign-kms

Create a signature using AWS KMS.

sui keytool sign-kms [OPTIONS]

--data

string

required

Base64 encoded BCS serialized transaction data

--keyid

string

required

AWS KMS key ID

--intent

Intent

Intent for the signature

--base64pk

string

required

Base64 encoded public key

Example:

sui keytool sign-kms \
  --data <BASE64_TX_DATA> \
  --keyid arn:aws:kms:region:account:key/id \
  --base64pk <BASE64_PUBKEY>

Requires AWS credentials configured in the environment.

multisig-address

Generate a MultiSig address.

sui keytool multisig-address [OPTIONS]

--threshold

ThresholdUnit

required

Threshold for the MultiSig (minimum weight required)

--pks

PublicKey[]

required

List of public keys (Base64 encoded flag || pk)

--weights

WeightUnit[]

required

List of weights corresponding to each public key

Example:

sui keytool multisig-address \
  --threshold 2 \
  --pks <PK1> <PK2> <PK3> \
  --weights 1 1 1

Output:

{
  "multisigAddress": "0x...",
  "multisig": [
    {
      "address": "0x...",
      "publicBase64Key": "A...",
      "weight": 1
    },
    ...
  ]
}

multisig-combine-partial-sig

Combine partial signatures into a MultiSig signature.

sui keytool multisig-combine-partial-sig [OPTIONS]

--sigs

GenericSignature[]

required

List of participating signatures (Base64 encoded)

--pks

PublicKey[]

required

List of all public keys in the MultiSig

--weights

WeightUnit[]

required

List of weights for each public key

--threshold

ThresholdUnit

required

Threshold for the MultiSig

Example:

sui keytool multisig-combine-partial-sig \
  --sigs <SIG1> <SIG2> \
  --pks <PK1> <PK2> <PK3> \
  --weights 1 1 1 \
  --threshold 2

The order of signatures must match the order of public keys. Sum of weights of all signatures must be >= threshold.

unpack

Unpack a keypair and output to file.

sui keytool unpack <KEYPAIR>

KEYPAIR

string

required

Base64 encoded 33-byte flag || privkey

Creates a file named <address>.key in the current directory. Example:

sui keytool unpack <BASE64_KEYPAIR>

Generate OAuth URL and execute a zkLogin transaction.

sui keytool zk-login-sign-and-execute-tx [OPTIONS]

--max-epoch

u64

required

Maximum epoch for zkLogin signature validity

--network

string

default:"devnet"

Network to use (devnet, testnet, mainnet)

--fixed

boolean

default:"false"

Use a fixed keypair generated from [0; 32] seed

--test-multisig

boolean

default:"false"

Use a multisig address with zklogin and a traditional keypair

--sign-with-sk

boolean

default:"false"

Execute tx with the traditional sig (in the multisig), otherwise with the zklogin sig

Example:

sui keytool zk-login-sign-and-execute-tx \
  --max-epoch 500 \
  --network devnet

The command will:

Generate OAuth URLs for various providers (Google, Twitch, Facebook, etc.)
Prompt you to visit a URL and paste the redirect
Generate zkLogin proof
Execute a test transaction

Workaround for zkLogin when token pasting doesn’t work.

sui keytool zk-login-enter-token [OPTIONS]

--parsed-token

string

required

Parsed JWT token

--max-epoch

u64

required

Maximum epoch

--jwt-randomness

string

required

JWT randomness

--kp-bigint

string

required

Ephemeral keypair as BigInt

--ephemeral-key-identifier

SuiAddress

required

Ephemeral key identifier

--network

string

default:"devnet"

Network to use

Parse and verify a zkLogin signature.

sui keytool zk-login-sig-verify [OPTIONS]

--sig

string

required

Base64 encoded zkLogin signature

--bytes

string

Base64 encoded TransactionData or PersonalMessage

--intent-scope

required

0 for TransactionData, 3 for PersonalMessage

--cur-epoch

u64

Current epoch for verification

--network

string

default:"devnet"

Network to verify the signature for

Example:

sui keytool zk-login-sig-verify \
  --sig <BASE64_SIG> \
  --bytes <BASE64_BYTES> \
  --intent-scope 0 \
  --cur-epoch 100 \
  --network devnet

TESTING ONLY: Generate a zkLogin signature for a personal message.

sui keytool zk-login-insecure-sign-personal-message [OPTIONS]

--data

string

required

Base64 encoded message to sign

--max-epoch

u64

required

Maximum epoch for zkLogin signature validity

Example:

sui keytool zk-login-insecure-sign-personal-message \
  --data $(echo -n "hello" | base64) \
  --max-epoch 5

This command uses a test issuer and is for testing only. Do not use in production.

Key Schemes

Sui supports three signature schemes:

ed25519

Default derivation path: m/44'/784'/0'/0'/0'
Recommended for: General use
Advantages: Fast, small signatures

secp256k1

Default derivation path: m/54'/784'/0'/0/0
Recommended for: Compatibility with Bitcoin/Ethereum tools
Advantages: Wide ecosystem support

secp256r1

Default derivation path: m/74'/784'/0'/0/0
Recommended for: Hardware security modules
Advantages: NIST standard, hardware support

MultiSig Workflows

Creating a 2-of-3 MultiSig

# 1. Get public keys from all participants
sui keytool list

# 2. Create MultiSig address
sui keytool multisig-address \
  --threshold 2 \
  --pks <PK1> <PK2> <PK3> \
  --weights 1 1 1

# Note the multisig address from output

Signing with MultiSig

# 1. Each participant signs independently
sui keytool sign \
  --address participant1 \
  --data <TX_DATA>

# Repeat for participant2

# 2. Combine signatures
sui keytool multisig-combine-partial-sig \
  --sigs <SIG1> <SIG2> \
  --pks <PK1> <PK2> <PK3> \
  --weights 1 1 1 \
  --threshold 2

# 3. Execute transaction with combined signature
sui client execute-signed-tx \
  --tx-bytes <TX_BYTES> \
  --signatures <COMBINED_SIG>

Security Best Practices

Never share private keys or mnemonics: Anyone with access has full control
Backup mnemonics securely: Store in a safe, offline location
Use hardware wallets for large amounts: Consider Ledger or similar
Verify addresses carefully: Double-check before sending transactions
Use strong aliases: Make them memorable but not personally identifying

Examples

Complete Key Management Workflow

# Generate new key
sui keytool generate ed25519 "m/44'/784'/0'/0'/0'" word24

# Import to keystore
sui keytool import \
  --alias my_secure_wallet \
  "<MNEMONIC_PHRASE>" \
  ed25519

# List all keys
sui keytool list

# Export for backup (store securely!)
sui keytool export --key-identity my_secure_wallet > backup.key

# Sign a transaction
sui keytool sign \
  --address my_secure_wallet \
  --data <TX_DATA>

Offline Signing

# On online machine: prepare transaction
sui client call \
  --package 0x2 \
  --module coin \
  --function split \
  --args 0xCOIN 1000 \
  --serialize-unsigned-transaction \
  --gas-budget 5000000

# Copy TX_BYTES to offline machine

# On offline machine: sign
sui keytool sign \
  --address cold_wallet \
  --data <TX_BYTES>

# Copy signature back to online machine

# On online machine: execute
sui client execute-signed-tx \
  --tx-bytes <TX_BYTES> \
  --signatures <SIGNATURE>

Overview

Commands

sui keytool

Synopsis

Global Options

Commands

update-alias

convert

decode-or-verify-tx

decode-multi-sig

generate

import

export

list

load-keypair

show

sign

sign-kms

multisig-address

multisig-combine-partial-sig

unpack

Key Schemes

ed25519

secp256k1

secp256r1

MultiSig Workflows

Creating a 2-of-3 MultiSig

Signing with MultiSig

Security Best Practices

Examples

Complete Key Management Workflow

Offline Signing

Build docs developers (and LLMs) love

Overview

Commands

​Synopsis

​Global Options

​Commands

​update-alias

​convert

​decode-or-verify-tx

​decode-multi-sig

​generate

​import

​export

​list

​load-keypair

​show

​sign

​sign-kms

​multisig-address

​multisig-combine-partial-sig

​unpack

​zk-login-sign-and-execute-tx

​zk-login-enter-token

​zk-login-sig-verify

​zk-login-insecure-sign-personal-message

​Key Schemes

​ed25519

​secp256k1

​secp256r1

​MultiSig Workflows

​Creating a 2-of-3 MultiSig

​Signing with MultiSig

​Security Best Practices

​Examples

​Complete Key Management Workflow

​Offline Signing

Build docs developers (and LLMs) love

Synopsis

Global Options

Commands

update-alias

convert

decode-or-verify-tx

decode-multi-sig

generate

import

export

list

load-keypair

show

sign

sign-kms

multisig-address

multisig-combine-partial-sig

unpack

zk-login-sign-and-execute-tx

zk-login-enter-token

zk-login-sig-verify

zk-login-insecure-sign-personal-message

Key Schemes

ed25519

secp256k1

secp256r1

MultiSig Workflows

Creating a 2-of-3 MultiSig

Signing with MultiSig

Security Best Practices

Examples

Complete Key Management Workflow

Offline Signing