sui client

The sui client command provides tools for interacting with the Sui blockchain network.

Synopsis

sui client [OPTIONS] [COMMAND]

Global Options

path

Path to client configuration file (default: ~/.sui/sui_config/client.yaml)

string

The Sui environment to use (must be present in config file)

boolean

Create a new sui config without prompting if none exists

boolean

Return command outputs in JSON format

Commands

active-address

Display the default address used for commands when none specified.

sui client active-address

Example output:

0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890

active-env

Display the default environment used for commands when none specified.

sui client active-env

Example output:

testnet

addresses

Obtain the addresses managed by the client.

sui client addresses [OPTIONS]

boolean

Sort by alias instead of address

Example:

sui client addresses
sui client addresses --sort-by-alias

balance

List the coin balance of an address.

sui client balance [OPTIONS] [ADDRESS]

string

Address or its alias. If not specified, uses active address

string

Show balance for the specified coin (e.g., 0x2::sui::SUI). Shows all coins if not specified

boolean

Show a list with each coin’s object ID and balance

Example:

# Show all balances for active address
sui client balance

# Show SUI balance with individual coins
sui client balance --coin-type 0x2::sui::SUI --with-coins

# Check balance for specific address
sui client balance 0xADDRESS

call

Call a Move function.

sui client call [OPTIONS]

ObjectID

required

Object ID of the package containing the module

string

required

The name of the module in the package

string

required

Function name in module

TypeTag[]

Type arguments to the generic function. All must be specified

SuiJsonValue[]

Simplified ordered args like in the function syntax. ObjectIDs and addresses must be hex strings

ObjectID[]

IDs of gas objects for payment. Auto-selected if not provided

u64

Gas budget for this transaction (in MIST). If not provided, performs dry run to estimate

u64

Gas price for this transaction (in MIST). Uses reference gas price if not provided

Example:

# Call a simple function
sui client call \
  --package 0x2 \
  --module coin \
  --function value \
  --args 0xOBJECT_ID \
  --gas-budget 10000000

# Call with type arguments
sui client call \
  --package 0xPACKAGE \
  --module nft \
  --function mint \
  --type-args 0x2::sui::SUI \
  --args "NFT Name" "Description" \
  --gas-budget 10000000

chain-identifier

Query the chain identifier from the RPC endpoint.

sui client chain-identifier

dynamic-field

Query dynamic fields by parent object address.

sui client dynamic-field <OBJECT_ID> [OPTIONS]

ObjectID

required

The ID of the parent object

string

Optional paging cursor

u32

default:"50"

Maximum items returned per page

envs

List all Sui environments.

sui client envs

Example output:

╭──────────┬────────────────────────────────────────┬────────╮
│ alias    │ rpc                                    │ active │
├──────────┼────────────────────────────────────────┼────────┤
│ devnet   │ https://fullnode.devnet.sui.io:443     │        │
│ testnet  │ https://fullnode.testnet.sui.io:443    │ *      │
│ mainnet  │ https://fullnode.mainnet.sui.io:443    │        │
│ local    │ http://127.0.0.1:9000                  │        │
╰──────────┴────────────────────────────────────────┴────────╯

faucet

Request gas coin from faucet.

sui client faucet [OPTIONS]

string

Address or its alias. Uses active address if not specified

string

The url to the faucet. Auto-detected based on active network if not specified

Example:

# Request tokens for active address
sui client faucet

# Request tokens for specific address
sui client faucet --address my_address_alias

For testnet tokens, use the Web UI at https://faucet.sui.io/

gas

Obtain all gas objects owned by an address.

sui client gas [ADDRESS]

string

Address or its alias owning the objects. Uses active address if not specified

merge-coin

Merge two coin objects into one coin.

sui client merge-coin [OPTIONS]

ObjectID

required

The address of the coin to merge into

ObjectID

required

The address of the coin to be merged

u64

Gas budget for this transaction (in MIST)

Example:

sui client merge-coin \
  --primary-coin 0xCOIN1 \
  --coin-to-merge 0xCOIN2 \
  --gas-budget 5000000

new-address

Generate new address and keypair.

sui client new-address <KEY_SCHEME> [ALIAS] [WORD_LENGTH] [DERIVATION_PATH]

string

required

Keypair scheme: ed25519, secp256k1, or secp256r1

string

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

string

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

string

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

Example:

# Generate ed25519 address with default settings
sui client new-address ed25519

# Generate with custom alias
sui client new-address ed25519 my_wallet

# Generate with custom word length
sui client new-address secp256k1 my_wallet word24

new-env

Add new Sui environment.

sui client new-env [OPTIONS]

string

required

Environment alias

url

required

RPC server URL

url

WebSocket URL

string

Basic authentication in format username:password

Example:

# Add testnet environment
sui client new-env \
  --alias testnet \
  --rpc https://fullnode.testnet.sui.io:443

# Add local network
sui client new-env \
  --alias local \
  --rpc http://127.0.0.1:9000

object

Get object information.

sui client object <OBJECT_ID> [OPTIONS]

ObjectID

required

Object ID of the object to fetch

boolean

Return the BCS serialized version of the object

Example:

sui client object 0xOBJECT_ID
sui client object 0xOBJECT_ID --bcs

objects

Obtain all objects owned by an address.

sui client objects [ADDRESS]

string

Address owning the objects. Uses active address if not specified. Accepts address or alias

pay

Pay coins to recipients following specified amounts.

sui client pay [OPTIONS]

ObjectID[]

required

The input coins to be used for pay recipients

string[]

required

The recipient addresses. Must be same length as amounts. Accepts addresses or aliases

u64[]

required

The amounts to be paid, following the order of recipients

u64

Gas budget for this transaction (in MIST)

Example:

sui client pay \
  --input-coins 0xCOIN1 0xCOIN2 \
  --recipients 0xRECIPIENT1 0xRECIPIENT2 \
  --amounts 1000000000 2000000000 \
  --gas-budget 10000000

pay-all-sui

Pay all residual SUI coins to recipient, after deducting gas cost.

sui client pay-all-sui [OPTIONS]

ObjectID[]

required

The input coins including the gas coin

string

required

The recipient address or alias

u64

Gas budget for this transaction (in MIST)

pay-sui

Pay SUI coins to recipients following specified amounts.

sui client pay-sui [OPTIONS]

ObjectID[]

required

The input coins including the gas coin

string[]

required

The recipient addresses. Must be same length as amounts

u64[]

required

The amounts to be paid

u64

Gas budget for this transaction (in MIST)

ptb

Run a Programmable Transaction Block from provided arguments.

sui client ptb [PTB_ARGS]

See the PTB documentation for detailed syntax and examples.

publish

Publish Move modules.

sui client publish [OPTIONS] [PACKAGE_PATH]

path

default:"."

Path to directory containing a Move package

boolean

Publish without checking whether dependency source code compiles to on-chain bytecode

boolean

Check that dependency source code compiles to on-chain bytecode before publishing

boolean

Also publish transitive dependencies that have not already been published

u64

Gas budget for this transaction (in MIST)

Example:

# Publish package in current directory
sui client publish --gas-budget 100000000

# Publish with dependency verification
sui client publish --verify-deps --gas-budget 100000000

# Publish package at specific path
sui client publish ./my_package --gas-budget 100000000

remove-address

Remove an existing address by its alias or hexadecimal string.

sui client remove-address <ALIAS_OR_ADDRESS>

split-coin

Split a coin object into multiple coins.

sui client split-coin [OPTIONS]

ObjectID

required

ID of the coin object to split

u64[]

Specific amounts to split out from the coin (mutually exclusive with —count)

u64

Count of equal-size coins to split into (mutually exclusive with —amounts)

u64

Gas budget for this transaction (in MIST)

Example:

# Split into specific amounts
sui client split-coin \
  --coin-id 0xCOIN \
  --amounts 1000000000 2000000000 3000000000 \
  --gas-budget 10000000

# Split into 5 equal parts
sui client split-coin \
  --coin-id 0xCOIN \
  --count 5 \
  --gas-budget 10000000

switch

Switch active address and/or network environment.

sui client switch [OPTIONS]

string

Address or alias to use as active address

string

The RPC server environment to use

Example:

# Switch environment
sui client switch --env testnet

# Switch address
sui client switch --address my_wallet

# Switch both
sui client switch --env mainnet --address my_main_wallet

transfer

Transfer object to an address.

sui client transfer [OPTIONS]

string

required

Recipient address or its alias

ObjectID

required

ID of the object to transfer

u64

Gas budget for this transaction (in MIST)

Example:

sui client transfer \
  --to 0xRECIPIENT \
  --object-id 0xOBJECT \
  --gas-budget 10000000

transfer-sui

Transfer SUI, and pay gas with the same SUI coin object.

sui client transfer-sui [OPTIONS]

string

required

Recipient address or its alias

ObjectID

required

ID of the coin to transfer (also used as gas)

u64

The amount to transfer. If not specified, the entire coin object will be transferred

u64

Gas budget for this transaction (in MIST)

Example:

# Transfer specific amount
sui client transfer-sui \
  --to 0xRECIPIENT \
  --sui-coin-object-id 0xCOIN \
  --amount 1000000000 \
  --gas-budget 10000000

# Transfer entire coin
sui client transfer-sui \
  --to 0xRECIPIENT \
  --sui-coin-object-id 0xCOIN \
  --gas-budget 10000000

tx-block

Get the effects of executing a transaction block.

sui client tx-block <DIGEST>

TransactionDigest

required

Digest of the transaction block

upgrade

Upgrade Move modules.

sui client upgrade [OPTIONS] [PACKAGE_PATH]

path

default:"."

Path to directory containing a Move package

ObjectID

ID of the upgrade capability for the package being upgraded

boolean

Upgrade without checking whether dependency source code compiles to on-chain bytecode

boolean

Also publish transitive dependencies that have not already been published

u64

Gas budget for this transaction (in MIST)

Example:

sui client upgrade \
  --upgrade-capability 0xCAP_ID \
  --gas-budget 100000000

verify-bytecode-meter

Run the bytecode verifier on a package.

sui client verify-bytecode-meter [OPTIONS]

path

Path to directory containing a Move package (defaults to current directory)

u64

Protocol version to use for the bytecode verifier (defaults to latest)

path[]

Paths to specific pre-compiled module bytecode to verify. Can be specified multiple times

verify-source

Verify local Move packages against on-chain packages.

sui client verify-source [OPTIONS] [PACKAGE_PATH]

path

default:"."

Path to directory containing a Move package

boolean

Verify on-chain dependencies

boolean

Don’t verify source (only valid if —verify-deps is enabled)

ObjectID

Override addresses for the package’s own modules. Only works for unpublished modules (whose addresses are 0x0)

Transaction Processing Options

Many commands support these transaction processing options:

boolean

Compute the transaction digest and print it, but do not execute

boolean

Perform a dry run of the transaction without executing it

boolean

Perform a dev inspect on the transaction

boolean

Serialize the BCS bytes of unsigned transaction data and print as Base64. Can be used with execute-signed-tx

boolean

Serialize the BCS bytes of signed transaction data and print as Base64. Can be used with execute-combined-signed-tx

SuiAddress

Set the transaction sender to this address

Examples

Complete Workflow: Creating and Funding an Address

# Create new address
sui client new-address ed25519 my_wallet

# Set as active
sui client switch --address my_wallet

# Request faucet tokens (on devnet/testnet)
sui client faucet

# Check balance
sui client balance

# View gas objects
sui client gas

Publishing and Interacting with a Package

# Build and publish
cd my_package
sui move build
sui client publish --gas-budget 100000000

# Note the package ID from output, then call a function
sui client call \
  --package 0xPACKAGE_ID \
  --module my_module \
  --function my_function \
  --gas-budget 10000000

Working with Coins

# Split a coin
sui client split-coin \
  --coin-id 0xCOIN \
  --amounts 1000000000 2000000000 \
  --gas-budget 5000000

# Merge coins
sui client merge-coin \
  --primary-coin 0xCOIN1 \
  --coin-to-merge 0xCOIN2 \
  --gas-budget 5000000

# Transfer SUI
sui client transfer-sui \
  --to 0xRECIPIENT \
  --sui-coin-object-id 0xCOIN \
  --amount 1000000000 \
  --gas-budget 5000000

​Synopsis

​Global Options

​Commands

​active-address

​active-env

​addresses

​balance

​call

​chain-identifier

​dynamic-field

​envs

​faucet

​gas

​merge-coin

​new-address

​new-env

​object

​objects

​pay

​pay-all-sui

​pay-sui

​ptb

​publish

​remove-address

​split-coin

​switch

​transfer

​transfer-sui

​tx-block

​upgrade

​verify-bytecode-meter

​verify-source

​Transaction Processing Options

​Examples

​Complete Workflow: Creating and Funding an Address

​Publishing and Interacting with a Package

​Working with Coins

Synopsis

Global Options

Commands

active-address

active-env

addresses

balance

call

chain-identifier

dynamic-field

envs

faucet

gas

merge-coin

new-address

new-env

object

objects

pay

pay-all-sui

pay-sui

ptb

publish

remove-address

split-coin

switch

transfer

transfer-sui

tx-block

upgrade

verify-bytecode-meter

verify-source

Transaction Processing Options

Examples

Complete Workflow: Creating and Funding an Address

Publishing and Interacting with a Package

Working with Coins