suideveloper
Get started
All questions
Transactions

How do I use sui client ptb?

November 11, 2026

sui client ptb builds a programmable transaction block from command-line flags and executes it with your active address. Each command flag (--move-call, --split-coins, --merge-coins, --transfer-objects, --make-move-vec, --publish, --upgrade) adds a command, and --assign binds a value or the previous command's result to a name you can use later. Add --preview to see the commands without running them, or --dry-run to simulate.

A first PTB

Send 0.5 SUI split off your gas coin to another address:

Terminal
sui client ptb \
  --split-coins gas "[500000000]" \
  --assign coin \
  --transfer-objects "[coin]" @0xRECIPIENT
  • gas is the reserved name for the gas coin.
  • --assign coin with no value binds the result of the previous command.
  • An @ prefix marks an address or object ID literal. Aliases from your keystore work without the @.
  • Amounts are in MIST (1 SUI = 10^9 MIST).

Syntax cheat sheet

Terminal
# Move call with type arguments and a shared object
--move-call 0x2::coin::value "<0x2::sui::SUI>" @0xCOIN_ID

# Bind a literal
--assign amount 1000

# Access one result from a multi-result command
--split-coins gas "[1,2,3]" --assign s
--transfer-objects "[s.0, s.1, s.2]" @0xRECIPIENT

# Vectors, options, strings
--move-call $PKG::m::f vector[1,2,3] some(5) none '"hello"'

# Merge coins into one
--merge-coins @0xPRIMARY "[@0xCOIN_A, @0xCOIN_B]"

# Build a vector of objects
--make-move-vec "<sui::coin::Coin<sui::sui::SUI>>" "[@0xA, @0xB]"

The well-known packages std, sui and deepbook resolve by name, so sui::coin::value works in place of 0x2::coin::value. Separate multiple type arguments with commas: "<u64,u8>". You can't use these words as variable names: address, bool, vector, some, none, gas, u8, u16, u32, u64, u128, u256.

Publishing with a PTB

Unlike sui client publish, a PTB publish gives you the UpgradeCap back as a result, and you have to transfer it yourself:

Terminal
sui client ptb \
  --move-call sui::tx_context::sender --assign sender \
  --publish "." --assign upgrade_cap \
  --transfer-objects "[upgrade_cap]" sender

Address balance withdrawals

Newer CLI versions accept withdrawal(AMOUNT) (SUI) or withdrawal<COIN_TYPE>(AMOUNT) as an input that draws from your address balance. Redeem it in the same PTB:

Terminal
sui client ptb \
  --move-call sui::coin::redeem_funds "<sui::sui::SUI>" 'withdrawal(1000000000)' \
  --assign coin \
  --transfer-objects "[coin]" @0xRECIPIENT

Useful options

Flag Purpose
--preview Print the command list, don't execute
--dry-run / --dev-inspect Simulate instead of executing
--gas-budget <MIST> Set a budget. If you leave it out, the CLI dry-runs to estimate one
--gas-coin <ID> Choose the gas coin
--gas-price <MIST> Set the gas price. Defaults to the reference gas price
--gas-sponsor <ADDRESS> Make another address the gas owner
--sender <ADDRESS> Sign as an address other than the active one
--tx-digest Print the digest without executing
--serialize-unsigned-transaction Output base64 TransactionData for offline or multisig signing
--summary / --json Shorter or machine-readable output
--warn-shadows Warn when a variable name is reused

Shell quoting gotchas

  • zsh treats [ ] as a glob, so quote arrays: "[coin]", not [coin].
  • Wrap string literals in single quotes so the double quotes reach the CLI: '"Hello, world"'.
  • Quote type arguments ("<u64>") because < and > are shell redirects.
  • On Windows you may need extra quoting, for example --assign "forge @0x...".

For long PTBs, put the command in a bash script with a \ at the end of each line. Get testnet SUI first with the faucet. For a single Move call, sui client call is shorter.

Sources

More on transactions

What is a programmable transaction block (PTB)?