Skip to main content

Sui Client PTB CLI

The client ptb command allows users to specify the transactions to be executed in a Programmable Transaction Block directly from your CLI or through bash scripts.

Commands​

The following list itemizes all the available args for the sui client ptb command. Use the --help for a long help version that includes some examples on how to use this command.

Build, preview, and execute programmable transaction blocks. Depending on your shell, you might have to use quotes around arrays or other passed values. Use --help to see examples for how to use the core functionality of this command.

Usage: sui client ptb [OPTIONS]

Options:
      --assign <NAME> <VALUE>                                         Assign a value to a variable name to use later in the PTB.
      --gas-coin <ID>                                                 The object ID of the gas coin to use. If not specified, it will try to use the first gas coin that it finds that has at least the requested gas-budget balance.
      --gas-budget <MIST>                                             The gas budget for the transaction, in MIST.
      --make-move-vec <TYPE> <[VALUES]>                               Given n-values of the same type, it constructs a vector. For non objects or an empty vector, the type tag must be specified.
      --merge-coins <INTO_COIN> <[COIN OBJECTS]>                      Merge N coins into the provided coin.
      --move-call <PACKAGE::MODULE::FUNCTION> <TYPE> <FUNCTION_ARGS>  Make a move call to a function.
      --split-coins <COIN> <[AMOUNT]>                                 Split the coin into N coins as per the given array of amounts.
      --transfer-objects <TO> <[OBJECTS]>                             Transfer objects to the specified address.
      --publish <MOVE_PACKAGE_PATH>                                   Publish the move package. It takes as input the folder where the package exists.
      --upgrade <MOVE_PACKAGE_PATH>                                   Upgrade the move package. It takes as input the folder where the package exists.
      --preview                                                       Preview the list of PTB transactions instead of executing them.
      --summary                                                       Show only a short summary (digest, execution status, gas cost). Do not use this flag when you need all the transaction data and the execution effects.
      --warn-shadows                                                  Enable shadow warning when the same variable name is declared multiple times. Off by default.
      --json                                                          Return command outputs in json format
  -h, --help                                                          Print help (see more with '--help')

Design philosophy and concepts​

The main philosophy behind the CLI PTB support is to enable a user to build and execute a PTB from the command line. Bash scripts can be used to construct and execute the PTB just as you would do from the command line, providing great flexibility when it comes to automating different tasks.

Besides using existing traditional PTB related concepts, we introduce a few new and important concepts for this command.

danger

Note that all the following examples were tested using a bash shell environment and your experience may vary depending on how your shell interprets the input values (e.g., zsh requires to pass values in brackets by adding quotes around it: "[]"; bash accepts them without quotes).

Addresses and Object IDs​

You can pass literal addresses and objects IDs by prefixing them with '@'. This is needed to distinguish a hexadecimal value from an address in some situations. Here are some examples for transfer-objects and gas-coin:

sui client ptb --transfer-objects @0x02a212de6a9dfa3a69e22387acfbafbb1a9e591bd9d636e7895dcfc8de05f331 --gas-coin @0x00002819ee07a66e53800495ccf5eeade8a02054a2e0827546c70e4b226f0495
tip

For addresses that are in your local wallet, you can use their alias instead (passing them without '@', e.g., --transfer-objects my_alias).

Assign​

The --assign argument is used to bind values to variables. There are two ways you can use it:

  • assign a value to a variable
  • assign a variable to the result of the previous command

Let's look at the first case where we assign a value to a variable. We want to check if some variable's value is none. We call the 0x1::option::is_none function from the Move standard library, and pass in the variable name like this: 

sui client ptb \
--assign my_variable none \
--move-call 0x1::option::is_none "<u64>" my_variable \
--gas-budget 50000000
tip

CLI PTB uses name resolution for common packages like sui, std, deepbook, so you can use them directly instead of their addresses: 0x2, 0x1, or 0xdee9.

In the second case, if a previous command outputs some result, it can be bound to a variable in order to be accessed later. Let's see an example where we want a new coin with 1000 MIST, which we can achieve by using the split-coins command. Once we do that, we want to transfer the new coin to another address. Without the --assign argument, we would not be able to instruct the CLI to transfer that new coin object as we would not have a way to refer to it.

sui client ptb \
--split-coins gas [1000] \
--assign coin \
--transfer-objects @recipient_address [coin] \
--gas-budget 50000000
tip

Variable names cannot be address, bool, vector, some, none, gas, u8, u16, u32, u64, u128, or u256.

tip

If you build a complex PTB, use the --preview flag to display the PTB transaction list instead of executing it.

Examples​

The following examples demonstrate how to use the client ptb command.

tip

When a PTB is executed, the output contains all the relevant information (tx data, gas cost, effects, object changes, etc.). Use --summary to get a short summary when you do not need all the data. For complex PTBs, you can use --preview to display the PTB transaction list instead of executing it.

Move call​

When needing to execute a move call, use the --move-call transaction to call a specific function from a package. The CLI PTB supports name resolution for common packages like sui, std, deepbook, so you can use both 0x1::option::is_none as well as std::option::is_none for passing the function name.

--assign A none
--move-call std::option::is_none<u64> A

Publish​

Publishing a package is one of the most important commands that users need when working with Sui. While the CLI has a standalone publish command, PTBs also supports publishing and upgrading packages. One main difference is that with sui client ptb, you would need to explicitly transfer the upgrade cap object that is returned when creating a package, or destroy it with a call to make_immutable. Here is an example on how to publish a Move project on chain using the sui client ptb command. It makes a call to the sui::tx_context::sender to acquire the sender and assigns the result of that call to the sender variable, and then calls the publish command. The result of publish is bounded to upgrade_cap variable, and then this object is transferred to the sender. 

--move-call sui::tx_context::sender
--assign sender
--publish "."
--assign upgrade_cap
--transfer-objects sender "[upgrade_cap]"
--gas-budget 100000000

Split, destroy, and merge coins​

The following example showcases how to split a gas coin into multiple coins, make a move call to destroy one or more of the new coins, and finally merge the coins that were not destroyed back into the gas coin. It also showcases how to use framework name resolution (e.g., sui::coin instead of 0x2::coin) and how to refer to different values in an array using the . syntax.

# Split off from gas
--split-coins gas [0,1,2,3]
--assign coins
--move-call sui::coin::destroy_zero<sui::sui::SUI> coins.0
# Can further split a split coin (and through variable bindings/result accesses)
--split-coins coins.1 [0,0]
--assign zcoins
# Destroy both new coins
--move-call sui::coin::destroy_zero<sui::sui::SUI> zcoins.0
--move-call sui::coin::destroy_zero<sui::sui::SUI> zcoins.1
# Can merge the split coins back
--merge-coins gas [coins.1, coins.2, coins.3]
--gas-budget 10000000

Transfer objects​

This example creates three new coins from gas and transfers them to a different address.

# Split off from gas
--assign to_address @0x02a212de6a9dfa3a69e22387acfbafbb1a9e591bd9d636e7895dcfc8de05f331
--split-coins gas [1,2,3]
--assign s
# Transfer the three new coins to a different address
--transfer-objects to_address [s.0, s.1, s.2]
--gas-budget 10000000
info

You can also pass an alias (without the '@') instead of an address.

Reserved words​

Variable names cannot be address, bool, vector, some, none, gas, u8, u16, u32, u64, u128, or u256.

JSON output​

Append the --json flag to commands to format responses in JSON instead of the more human-friendly default Sui 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.