IOTA Move CLI
The IOTA CLI move command provides several commands for working with Move source code. A typical usage of iota move is to compile and test the Move code, or to generate a new Move project by using iota move new project_name, which creates the needed directories and the Move.toml file.
Check IOTA CLI installation
Before you can use the IOTA CLI, you must install it. To check if the CLI exists on your system, open a terminal or console and type the following command:
iota --version
If the terminal or console responds with a version number, you already have the IOTA CLI installed.
If the command is not found, follow the instructions in Install IOTA to get the IOTA CLI on your system.
Commands
Typing iota move --help into your terminal or console displays the following information on available commands.
Tool to build and test Move applications
Usage: iota move [OPTIONS] <COMMAND>
Commands:
build
coverage Inspect test coverage for this package. A previous test run with the `--coverage` flag must have previously been run
disassemble
manage-package Record addresses (Object IDs) for where this package is published on chain (this command sets variables in Move.lock)
migrate Migrate to Move 2024 for the package at `path`. If no path is provided defaults to current directory
new Create a new Move package with name `name` at `path`. If `path` is not provided the package will be created in the directory `name`
test Run Move unit tests in this package
help Print this message or the help of the given subcommand(s)
Options:
-p, --path <PACKAGE_PATH> Path to a package which the command should be run with respect to
-d, --dev Compile in 'dev' mode. The 'dev-addresses' and 'dev-dependencies' fields will be used if this flag is set. This flag is useful for development of packages that expose named addresses that are not set to a specific value
--test Compile in 'test' mode. The 'dev-addresses' and 'dev-dependencies' fields will be used along with any code in the 'tests' directory
--doc Generate documentation for packages
--install-dir <INSTALL_DIR> Installation directory for compiled artifacts. Defaults to current directory
--force Force recompilation of all packages
--fetch-deps-only Only fetch dependency repos to MOVE_HOME
--skip-fetch-latest-git-deps Skip fetching latest git dependencies
--default-move-flavor <DEFAULT_FLAVOR> Default flavor for move compilation, if not specified in the package's config
--default-move-edition <DEFAULT_EDITION> Default edition for move compilation, if not specified in the package's config
--dependencies-are-root If set, dependency packages are treated as root packages. Notably, this will remove warning suppression in dependency packages
--silence-warnings If set, ignore any compiler warnings
--warnings-are-errors If set, warnings become errors
--no-lint If `true`, disable linters
--lint If `true`, enables extra linters
-h, --help Print help
-V, --version Print version
Examples
The following examples demonstrate some of the most often used commands.
Create a new Move project
To create a new Move project that automatically adds the necessary dependencies in a Move.toml file, run iota move new [<PROJECT-NAME>].
$ iota move new smart_contract_test
$ ls -l smart_contract_test
Move.toml
sources
tests
# display the contents of Move.toml file
$ cat smart_contract_test/Move.toml
[package]
name = "smart_contract_test"
edition = "2024.beta" # edition = "legacy" to use legacy (pre-2024) Move
[dependencies]
Iota = { git = "https://github.com/iotaledger/iota.git", subdir = "crates/iota-framework/packages/iota-framework", rev = "testnet" }
[addresses]
smart_contract_test = "0x0"
Build a Move project
Use iota move build at the root of your Move project to build the package.
$ iota move build
UPDATING GIT DEPENDENCY https://github.com/iotaledger/iota.git
INCLUDING DEPENDENCY IOTA
INCLUDING DEPENDENCY MoveStdlib
BUILDING smart_contract_test
Run tests in a Move project
Use iota move test to run the tests in a Move package.
$ iota move test
UPDATING GIT DEPENDENCY https://github.com/iotaledger/iota.git
INCLUDING DEPENDENCY IOTA
INCLUDING DEPENDENCY MoveStdlib
BUILDING smart_contract_test
Running Move unit tests
Test result: OK. Total tests: 0; passed: 0; failed: 0
Get test coverage for a module
This command currently only works on debug builds of the CLI. Please build the CLI from source to use it.
This example uses first_package Move package.
To get the a summary of the test coverage, you must first run the iota move test --coverage command, and then the iota move coverage summary --test to get a summary of the test coverage in the example project.
$ iota move test --coverage
INCLUDING DEPENDENCY IOTA
INCLUDING DEPENDENCY MoveStdlib
BUILDING first_package
Running Move unit tests
[ PASS ] 0x0::example::test_module_init
[ PASS ] 0x0::example::test_sword_transactions
Test result: OK. Total tests: 2; passed: 2; failed: 0
$ iota move coverage summary --test
+-------------------------+
| Move Coverage Summary |
+-------------------------+
Module 0000000000000000000000000000000000000000000000000000000000000000::example
>>> % Module coverage: 92.81
+-------------------------+
| % Move Coverage: 92.81 |
+-------------------------+
Help
Each command has its own help section. For example iota move build --help displays the following prompt:
$ iota move build --help
Usage: iota move build [OPTIONS]
Options:
-p, --path <PACKAGE_PATH> Path to a package which the command should be run with respect to
--with-unpublished-dependencies Include the contents of packages in dependencies that haven't been published (only relevant when dumping bytecode as base64)
-d, --dev Compile in 'dev' mode. The 'dev-addresses' and 'dev-dependencies' fields will be used if this flag is set. This flag is useful for development of packages that expose named addresses that are not set to a specific value
--dump-bytecode-as-base64 Whether we are printing in base64
--generate-struct-layouts If true, generate struct layout schemas for all struct types passed into `entry` functions declared by modules in this package These layout schemas can be consumed by clients (e.g., the TypeScript SDK) to enable serialization/deserialization of transaction
arguments and events
--test Compile in 'test' mode. The 'dev-addresses' and 'dev-dependencies' fields will be used along with any code in the 'tests' directory
--doc Generate documentation for packages
--install-dir <INSTALL_DIR> Installation directory for compiled artifacts. Defaults to current directory
--force Force recompilation of all packages
--fetch-deps-only Only fetch dependency repos to MOVE_HOME
--skip-fetch-latest-git-deps Skip fetching latest git dependencies
--default-move-flavor <DEFAULT_FLAVOR> Default flavor for move compilation, if not specified in the package's config
--default-move-edition <DEFAULT_EDITION> Default edition for move compilation, if not specified in the package's config
--dependencies-are-root If set, dependency packages are treated as root packages. Notably, this will remove warning suppression in dependency packages
--silence-warnings If set, ignore any compiler warnings
--warnings-are-errors If set, warnings become errors
--no-lint If `true`, disable linters
--lint If `true`, enables extra linters
-h, --help Print help
-V, --version Print version