sui move - Sui

The sui move command provides tools for developing Move smart contracts on Sui.

Synopsis

sui move [OPTIONS] <COMMAND>

Global Options

path

Path to a package which the command should be run with respect to

path

Path to client configuration file

string

The Sui environment to use

Build Configuration Options

These options are available for most commands:

string

Build environment for the package

string

Build mode(s) to use

boolean

Enable dev mode

boolean

Enable test mode

Commands

build

Build a Move package.

sui move build [OPTIONS]

boolean

Dump package bytecode as Base64

boolean

Build with unpublished dependencies (addresses set to 0x0)

boolean

Skip tree shaking optimization

Example:

# Build package in current directory
sui move build

# Build package at specific path
sui move build --path ./my_package

# Build with bytecode output
sui move build --dump-bytecode-as-base64

Output: Successful builds display:

Build summary
Module compilation status
Package digest
Build artifacts location

test

Run Move unit tests.

sui move test [OPTIONS] [FILTER]

string

Optional filter string to run specific tests matching the pattern

boolean

Enable coverage collection during tests

u64

Gas limit for running tests (default: 1000000000)

boolean

List all tests without running them

Example:

# Run all tests
sui move test

# Run tests matching a pattern
sui move test test_transfer

# Run tests with coverage
sui move test --coverage

# List all available tests
sui move test --list

Test Output:

RUNNING MoveUnit tests
[ PASS    ] 0x0::my_module::test_create
[ PASS    ] 0x0::my_module::test_transfer
[ PASS    ] 0x0::my_module::test_burn
Test result: OK. Total tests: 3; passed: 3; failed: 0

coverage

Generate coverage report for Move tests.

sui move coverage [OPTIONS]

string

Output format: text, html, lcov, or summary (default: summary)

path

Output file or directory for coverage data

Prerequisites: Must run sui move test --coverage first to generate coverage data. Example:

# Generate coverage data
sui move test --coverage

# View coverage summary
sui move coverage

# Generate HTML coverage report
sui move coverage --format html --output coverage_report

# Generate LCOV format for CI tools
sui move coverage --format lcov --output coverage.lcov

disassemble

Disassemble Move bytecode.

sui move disassemble [OPTIONS]

Disassembles compiled Move modules to readable bytecode. Example:

sui move disassemble --path ./my_package

migrate

Migrate a Move package to the latest syntax and format.

sui move migrate [OPTIONS]

Updates Move source code to match current language version. Example:

sui move migrate
sui move migrate --path ./legacy_package

new

Create a new Move package.

sui move new <NAME>

string

required

Name of the new package

Example:

sui move new my_package

Creates a new directory with:

my_package/
├── Move.toml
├── sources/
│   └── my_package.move
└── tests/
    └── my_package_tests.move

Generated Move.toml:

[package]
name = "my_package"
version = "0.0.1"

[dependencies]
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/mainnet" }

[addresses]
my_package = "0x0"

summary

Generate a package summary.

sui move summary [OPTIONS]

ObjectID

Generate summary for an on-chain package

boolean

Generate bytecode-based summary

Example:

# Summary of local package
sui move summary

# Summary of on-chain package
sui move summary --package-id 0xPACKAGE_ID --bytecode

update-deps

Update Move package dependencies.

sui move update-deps [OPTIONS]

Updates dependencies defined in Move.toml to their latest compatible versions. Example:

sui move update-deps

Package Structure

A typical Sui Move package structure:

my_package/
├── Move.toml           # Package manifest
├── Move.lock           # Dependency lock file (auto-generated)
├── sources/            # Source code directory
│   ├── module1.move
│   └── module2.move
├── tests/              # Unit tests
│   └── tests.move
├── scripts/            # Transaction scripts (optional)
│   └── script.move
└── build/              # Build output (auto-generated)
    └── ...

Move.toml Configuration

The Move.toml file configures your package:

[package]
name = "my_package"        # Package name
version = "1.0.0"          # Package version

[dependencies]
# Sui framework dependency
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/mainnet" }

# Local dependency
MyLibrary = { local = "../my_library" }

# Git dependency
DeepBook = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/deepbook", rev = "main" }

[addresses]
my_package = "0x0"         # Address for unpublished package
std = "0x1"               # Standard library
sui = "0x2"               # Sui framework

[dev-dependencies]
# Dependencies only for tests

Writing Tests

Move unit tests use the #[test] attribute:

module my_package::my_module {
    use sui::test_scenario;

    #[test]
    fun test_create() {
        let sender = @0xA;
        let mut scenario = test_scenario::begin(sender);
        
        // Test logic here
        
        test_scenario::end(scenario);
    }

    #[test]
    #[expected_failure(abort_code = 0)]
    fun test_failure() {
        // Test that should fail
        abort 0
    }
}

Test Attributes

attribute

Marks a function as a test

attribute

Marks code that is only compiled in test mode

attribute

Marks a test that is expected to fail

parameter

Expected abort code for #[expected_failure]

Build Modes

Sui Move supports different build modes:

Default: Standard build for deployment
Test: Includes test code and test-only dependencies
Dev: Development mode with additional checks

Common Workflows

Creating a New Package

# Create package
sui move new my_nft
cd my_nft

# Build
sui move build

# Test
sui move test

# Publish
sui client publish --gas-budget 100000000

Development Cycle

# Make changes to code
vim sources/my_module.move

# Build and test
sui move build && sui move test

# If tests pass, publish
sui client publish --gas-budget 100000000

Working with Dependencies

# Update dependencies
sui move update-deps

# Build with updated dependencies
sui move build

# Test with new dependencies
sui move test

Examples

Simple Counter Module

module my_package::counter {
    use sui::object::{Self, UID};
    use sui::tx_context::{Self, TxContext};
    use sui::transfer;

    public struct Counter has key {
        id: UID,
        value: u64,
    }

    public fun create(ctx: &mut TxContext) {
        let counter = Counter {
            id: object::new(ctx),
            value: 0,
        };
        transfer::share_object(counter);
    }

    public fun increment(counter: &mut Counter) {
        counter.value = counter.value + 1;
    }

    public fun value(counter: &Counter): u64 {
        counter.value
    }

    #[test]
    fun test_counter() {
        use sui::test_scenario;

        let user = @0xA;
        let mut scenario = test_scenario::begin(user);
        
        // Create counter
        {
            let ctx = test_scenario::ctx(&mut scenario);
            create(ctx);
        };
        
        // Increment counter
        test_scenario::next_tx(&mut scenario, user);
        {
            let mut counter = test_scenario::take_shared<Counter>(&scenario);
            increment(&mut counter);
            assert!(value(&counter) == 1, 0);
            test_scenario::return_shared(counter);
        };
        
        test_scenario::end(scenario);
    }
}

Running the Example

# Create and build
sui move new counter_package
cd counter_package
# Add the counter module code above to sources/counter.move

# Build
sui move build

# Test
sui move test

# Publish
sui client publish --gas-budget 100000000

Troubleshooting

Build Errors

Module not found:

# Ensure dependencies are specified in Move.toml
# Run update-deps
sui move update-deps

Address resolution failed:

# Check [addresses] section in Move.toml
# Ensure all referenced addresses are defined

Test Failures

# Run with verbose output
RUST_LOG=debug sui move test

# Run specific test
sui move test my_test_name

Dependency Issues

# Clean build artifacts
rm -rf build

# Update dependencies
sui move update-deps

# Rebuild
sui move build

​Synopsis

​Global Options

​Build Configuration Options

​Commands

​build

​test

​coverage

​disassemble

​migrate

​new

​summary

​update-deps

​Package Structure

​Move.toml Configuration

​Writing Tests

​Test Attributes

​Build Modes

​Common Workflows

​Creating a New Package

​Development Cycle

​Working with Dependencies

​Examples

​Simple Counter Module

​Running the Example

​Troubleshooting

​Build Errors

​Test Failures

​Dependency Issues

Synopsis

Global Options

Build Configuration Options

Commands

build

test

coverage

disassemble

migrate

new

summary

update-deps

Package Structure

Move.toml Configuration

Writing Tests

Test Attributes

Build Modes

Common Workflows

Creating a New Package

Development Cycle

Working with Dependencies

Examples

Simple Counter Module

Running the Example

Troubleshooting

Build Errors

Test Failures

Dependency Issues