sui client

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

Synopsis

sui client [OPTIONS] [COMMAND]

Global Options

--client.config

path

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

--client.env

string

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

-y, --yes

boolean

Create a new sui config without prompting if none exists

--json

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]

-s, --sort-by-alias

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]

ADDRESS

string

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

--coin-type

string

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

--with-coins

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]

--package

ObjectID

required

Object ID of the package containing the module

--module

string

required

The name of the module in the package

--function

string

required

Function name in module

--type-args

TypeTag[]

Type arguments to the generic function. All must be specified

--args

SuiJsonValue[]

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

--gas

ObjectID[]

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

--gas-budget

u64

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

--gas-price

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]

OBJECT_ID

ObjectID

required

The ID of the parent object

--cursor

string

Optional paging cursor

--limit

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]

--address

string

Address or its alias. Uses active address if not specified

--url

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]

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]

--primary-coin

ObjectID

required

The address of the coin to merge into

--coin-to-merge

ObjectID

required

The address of the coin to be merged

--gas-budget

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]

KEY_SCHEME

string

required

Keypair scheme: ed25519, secp256k1, or secp256r1

ALIAS

string

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

WORD_LENGTH

string

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

DERIVATION_PATH

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]

--alias

string

required

Environment alias

--rpc

url

required

RPC server URL

--ws

url

WebSocket URL

--basic-auth

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]

OBJECT_ID

ObjectID

required

Object ID of the object to fetch

--bcs

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]

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]

--input-coins

ObjectID[]

required

The input coins to be used for pay recipients

--recipients

string[]

required

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

--amounts

u64[]

required

The amounts to be paid, following the order of recipients

--gas-budget

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]

--input-coins

ObjectID[]

required

The input coins including the gas coin

--recipient

string

required

The recipient address or alias

--gas-budget

u64

Gas budget for this transaction (in MIST)

pay-sui

Pay SUI coins to recipients following specified amounts.

sui client pay-sui [OPTIONS]

--input-coins

ObjectID[]

required

The input coins including the gas coin

--recipients

string[]

required

The recipient addresses. Must be same length as amounts

--amounts

u64[]

required

The amounts to be paid

--gas-budget

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]

PACKAGE_PATH

path

default:"."

Path to directory containing a Move package

--skip-dependency-verification

boolean

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

--verify-deps

boolean

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

--with-unpublished-dependencies

boolean

Also publish transitive dependencies that have not already been published

--gas-budget

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]

--coin-id

ObjectID

required

ID of the coin object to split

--amounts

u64[]

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

--count

u64

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

--gas-budget

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]

--address

string

Address or alias to use as active address

--env

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]

--to

string

required

Recipient address or its alias

--object-id

ObjectID

required

ID of the object to transfer

--gas-budget

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]

--to

string

required

Recipient address or its alias

--sui-coin-object-id

ObjectID

required

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

--amount

u64

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

--gas-budget

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>

DIGEST

TransactionDigest

required

Digest of the transaction block

upgrade

Upgrade Move modules.

sui client upgrade [OPTIONS] [PACKAGE_PATH]

PACKAGE_PATH

path

default:"."

Path to directory containing a Move package

-c, --upgrade-capability

ObjectID

ID of the upgrade capability for the package being upgraded

--skip-dependency-verification

boolean

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

--with-unpublished-dependencies

boolean

Also publish transitive dependencies that have not already been published

--gas-budget

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]

--package

path

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

--protocol-version

u64

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

--module

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]

PACKAGE_PATH

path

default:"."

Path to directory containing a Move package

--verify-deps

boolean

Verify on-chain dependencies

--skip-source

boolean

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

--address-override

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:

--tx-digest

boolean

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

--dry-run

boolean

Perform a dry run of the transaction without executing it

--dev-inspect

boolean

Perform a dev inspect on the transaction

--serialize-unsigned-transaction

boolean

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

--serialize-signed-transaction

boolean

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

--sender

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

Overview

Commands

​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

Build docs developers (and LLMs) love

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