Aptos Command Line Interface (CLI) Tool

The aptos tool is a command line interface (CLI) for debugging, development, and node operation. This document describes how to install the aptos CLI tool and how to use it.

Installation

Install precompiled binary (easy mode)

Navigate to the release page for Aptos CLI.
Download the latest release for your computer.
Place this at a location for you to run it e.g. ~/bin/aptos in Linux.
On Linux and Mac, make this executable chmod +x ~/bin/aptos.
Now type ~/bin/aptos help to read help instructions.
If you want you can add ~/bin to your path in your appropriate .bashrc or .zshrc for future use

Install Cargo (harder mode)

You will need the cargo package manager to install the aptos CLI tool. Follow the below steps. 1. Follow the cargo installation instructions on this page and install cargo. Proceed only after you successfully install cargo. 2. Execute the below step to ensure that your current shell environment knows where cargo is. bash source $HOME/.cargo/env

Install the `aptos` CLI

Install dependencies before compiling:
1. For Debian or Ubuntu: sudo apt install build-essential pkg-config openssl libssl-dev libclang-dev.
2. For RHEL or Centos: sudo yum install pkgconfig openssl openssl-devel clang.
3. For others: please manually install pkg-config openssl, libssl and libclang:
  - pkg-config:
    - Download and unzip the source code at https://pkgconfig.freedesktop.org/releases/
    - ./configure --prefix=/usr/local/pkg_config/0_29_2 --with-internal-glib
    - sudo make && sudo make install
  - openssl and libssl:
    - Check https://wiki.openssl.org/index.php/CompilationandInstallation for full instructions.
  - libclang:
    - Check https://clang.llvm.org/get_started.html for full instructions.
Install the aptos CLI tool by running the below command. You can run this command from any directory. The aptos CLI tool will be installed into your CARGO_HOME, usually ~/.cargo: bash cargo install --git https://github.com/aptos-labs/aptos-core.git aptos --tag aptos-cli-0.2.0
Confirm that the aptos CLI tool is installed successfully by running the below command. The terminal will display the path to the aptos CLI's location. bash which aptos

Using the `aptos` CLI

Command Line Help

Command line help is available. Type aptos help or aptos --help to see the available command options. ```bash $ aptos help aptos 0.2.0 Aptos Labs opensource@aptoslabs.com CLI tool for interacting with the Aptos blockchain and nodes

USAGE: aptos

OPTIONS: -h, --help Print help information -V, --version Print version information

SUBCOMMANDS: account CLI tool for interacting with accounts config Tool for configuration of the CLI tool genesis Tool for setting up and building the Genesis transaction help Print this message or the help of the given subcommand(s) init Tool to initialize current directory for the aptos tool key CLI tool for generating, inspecting, and interacting with keys move CLI tool for performing Move tasks ```

Command specific help is also available. For example, type aptos move --help to get command-specific help. ```bash $ aptos move --help aptos-move 0.2.0 CLI tool for performing Move tasks

USAGE: aptos move

OPTIONS: -h, --help Print help information -V, --version Print version information

SUBCOMMANDS: compile Compiles a package and returns the [ModuleId]s help Print this message or the help of the given subcommand(s) init Creates a new Move package at the given location publish Publishes the modules in a Move package run Run a Move function test Run Move unit tests against a package path ```

Help for sub-commands is also available. For example, type aptos move compile --help to get command-specific help. ``bash $ aptos move compile --help aptos-move-compile 0.2.0 Compiles a package and returns the [ModuleId`]s

USAGE: aptos move compile [OPTIONS]

OPTIONS: -h, --help Print help information

    --named-addresses <NAMED_ADDRESSES>
        Named addresses for the move binary

        Example: alice=0x1234, bob=0x5678

        Note: This will fail if there are duplicates in the Move.toml file remove those first.

        [default: ]

    --output-dir <OUTPUT_DIR>
        Path to save the compiled move package

        Defaults to `<package_dir>/build`

    --package-dir <PACKAGE_DIR>
        Path to a move package (the folder with a Move.toml file)

        [default: .]

-V, --version
        Print version information

```

Examples

Initialize local configuration and create an account

A local folder named .aptos/ will be created with a configuration config.yaml which can be used to store configuration between CLI runs. This is local to your run, so you will need to continue running CLI from this folder, or reinitialize in another folder.

Step 1) Run Aptos init

This will initialize the configuration with the private key given. ```bash $ aptos init Configuring for profile default Enter your rest endpoint [Current: None | No input: https://fullnode.devnet.aptoslabs.com]

No rest url given, using https://fullnode.devnet.aptoslabs.com... Enter your faucet endpoint [Current: None | No input: https://faucet.devnet.aptoslabs.com]

No faucet url given, using https://faucet.devnet.aptoslabs.com... Enter your private key as a hex literal (0x...) [Current: None | No input: Generate new key (or keep one if present)]

No key given, generating key... Account 50A49D913AA6381C01579E3FC00784B49AFA3A771F06389EBC65F8FF3A4E9A7D doesn't exist, creating it and funding it with 10000 coins Aptos is now set up for account 50A49D913AA6381C01579E3FC00784B49AFA3A771F06389EBC65F8FF3A4E9A7D! Run aptos help for more information about commands

{ "Result": "Success" } ```

Step 2) Changing the configuration

To change the configuration, you can either run the command aptos init or you can manually edit the .aptos/config.yaml that is in your current working directory.

Step 3) Creating other profiles

You can also create other profiles for different endpoints and different keys. These can be made by adding the --profile argument, and can be used in most other commands to replace command line arguments.

```bash $ aptos init --profile superuser Configuring for profile superuser Enter your rest endpoint [Current: None | No input: https://fullnode.devnet.aptoslabs.com]

No rest url given, using https://fullnode.devnet.aptoslabs.com... Enter your faucet endpoint [Current: None | No input: https://faucet.devnet.aptoslabs.com]

No faucet url given, using https://faucet.devnet.aptoslabs.com... Enter your private key as a hex literal (0x...) [Current: None | No input: Generate new key (or keep one if present)]

No key given, generating key... Account 18B61497FD290B02BB0751F44381CADA1657C2B3AA6194A00D9BC9A85FAD3B04 doesn't exist, creating it and funding it with 10000 coins Aptos is now set up for account 18B61497FD290B02BB0751F44381CADA1657C2B3AA6194A00D9BC9A85FAD3B04! Run aptos help for more information about commands { "Result": "Success" }

```

View an account's balance and transfer events

You can view the balance and transfer events (deposits and withdrawals) with: ```bash $ aptos account list --query balance --account 18B61497FD290B02BB0751F44381CADA1657C2B3AA6194A00D9BC9A85FAD3B04

```

The above command will generate the following information on your terminal:

bash { "Result": [ { "coin": { "value": "9999729" }, "deposit_events": { "counter": "1", "guid": { "guid": { "id": { "addr": "0x661a4ca2b5f7475e61d2209cd3818488b3725ddb5e483633317291f86d3a26d6", "creation_num": "1" } }, "len_bytes": 40 } }, "withdraw_events": { "counter": "3", "guid": { "guid": { "id": { "addr": "0x661a4ca2b5f7475e61d2209cd3818488b3725ddb5e483633317291f86d3a26d6", "creation_num": "2" } }, "len_bytes": 40 } } } ] }

Listing resources in an account

You can list the resources in an account from the command line. For example, see below for how to list the resources in the account you just created above: ```bash $ aptos account list --query resources --account 18B61497FD290B02BB0751F44381CADA1657C2B3AA6194A00D9BC9A85FAD3B04

```

The above command will generate the following resource list information on your terminal:

```bash { "Result": [ { "counter": "2" }, { "authenticationkey": "0x18b61497fd290b02bb0751f44381cada1657c2b3aa6194a00d9bc9a85fad3b04", "selfaddress": "0x18b61497fd290b02bb0751f44381cada1657c2b3aa6194a00d9bc9a85fad3b04", "sequencenumber": "0" }, { "coin": { "value": "10000" } }, { "receivedevents": { "counter": "0", "guid": { "guid": { "id": { "addr": "0x18b61497fd290b02bb0751f44381cada1657c2b3aa6194a00d9bc9a85fad3b04", "creationnum": "1" } }, "lenbytes": 40 } }, "sentevents": { "counter": "0", "guid": { "guid": { "id": { "addr": "0x18b61497fd290b02bb0751f44381cada1657c2b3aa6194a00d9bc9a85fad3b04", "creationnum": "0" } }, "len_bytes": 40 } } } ] }

```

You can additionally list the default profile from configuration with no account specified. bash $ aptos account list { "Result": [ { "counter": "2" }, { "authentication_key": "0x50a49d913aa6381c01579e3fc00784b49afa3a771f06389ebc65f8ff3a4e9a7d", "self_address": "0x50a49d913aa6381c01579e3fc00784b49afa3a771f06389ebc65f8ff3a4e9a7d", "sequence_number": "0" }, { "coin": { "value": "10000" } }, { "received_events": { "counter": "0", "guid": { "guid": { "id": { "addr": "0x50a49d913aa6381c01579e3fc00784b49afa3a771f06389ebc65f8ff3a4e9a7d", "creation_num": "1" } }, "len_bytes": 40 } }, "sent_events": { "counter": "0", "guid": { "guid": { "id": { "addr": "0x50a49d913aa6381c01579e3fc00784b49afa3a771f06389ebc65f8ff3a4e9a7d", "creation_num": "0" } }, "len_bytes": 40 } } } ] }

Additionally, any place that takes an account can use the name of a profile: bash $ ./aptos account list --query resources --account superuser { "Result": [ { "counter": "2" }, { "authentication_key": "0x18b61497fd290b02bb0751f44381cada1657c2b3aa6194a00d9bc9a85fad3b04", "self_address": "0x18b61497fd290b02bb0751f44381cada1657c2b3aa6194a00d9bc9a85fad3b04", "sequence_number": "0" }, { "coin": { "value": "10000" } }, { "received_events": { "counter": "0", "guid": { "guid": { "id": { "addr": "0x18b61497fd290b02bb0751f44381cada1657c2b3aa6194a00d9bc9a85fad3b04", "creation_num": "1" } }, "len_bytes": 40 } }, "sent_events": { "counter": "0", "guid": { "guid": { "id": { "addr": "0x18b61497fd290b02bb0751f44381cada1657c2b3aa6194a00d9bc9a85fad3b04", "creation_num": "0" } }, "len_bytes": 40 } } } ] }

Listing modules in an account

You can pass different types of queries to view different items under an account. Currently, 'resources' and 'modules' are supported but more query types are coming. For example, to fetch modules: ```bash $ ./aptos account list --query modules --account superuser

{ "Result": [ { "bytecode": "0xa11ceb0b050000000b01000a020a12031c2504410405452d0772e00108d202400692030a0a9c03150cb103650d96040400000101010201030104000506000006080001070700030e0401060100080001000009020300020f0404000110060100041107000003120709010603130a030106050806080105010802020c0a02000103040508020802070801010a0201060c010800010b0301090002070b030109000900074d657373616765054153434949064572726f7273054576656e74065369676e6572124d6573736167654368616e67654576656e740d4d657373616765486f6c64657206537472696e670b6765745f6d6573736167650b7365745f6d6573736167650c66726f6d5f6d6573736167650a746f5f6d657373616765076d657373616765156d6573736167655f6368616e67655f6576656e74730b4576656e7448616e646c650d6e6f745f7075626c697368656406737472696e670a616464726573735f6f66106e65775f6576656e745f68616e646c650a656d69745f6576656e747bd2d264eec4088a11c41a7acbcd8ab2d2c887fa4ea1a3ab0d0b4a405ddfb1560000000000000000000000000000000000000000000000000000000000000001030800000000000000000002020a08020b08020102020c08020d0b030108000001000101030b0a002901030607001102270b002b0110001402010200010105240b0111030c040e0011040c020a02290120030b05120e000b040e00380012012d0105230b022a010c050a051000140c030a050f010b030a04120038010b040b050f0015020100010100", "abi": { "address": "0x7bd2d264eec4088a11c41a7acbcd8ab2d2c887fa4ea1a3ab0d0b4a405ddfb156", "name": "Message", "friends": [], "exposedfunctions": [ { "name": "getmessage", "visibility": "public", "generictypeparams": [], "params": [ "address" ], "return": [ "0x1::ASCII::String" ] }, { "name": "setmessage", "visibility": "script", "generictypeparams": [], "params": [ "signer", "vector" ], "return": [] } ], "structs": [ { "name": "MessageChangeEvent", "isnative": false, "abilities": [ "drop", "store" ], "generictypeparams": [], "fields": [ { "name": "frommessage", "type": "0x1::ASCII::String" }, { "name": "tomessage", "type": "0x1::ASCII::String" } ] }, { "name": "MessageHolder", "isnative": false, "abilities": [ "key" ], "generictypeparams": [], "fields": [ { "name": "message", "type": "0x1::ASCII::String" }, { "name": "messagechange_events", "type": "0x1::Event::EventHandle<0x7bd2d264eec4088a11c41a7acbcd8ab2d2c887fa4ea1a3ab0d0b4a405ddfb156::Message::MessageChangeEvent>" } ] } ] } } ] } ```

Transferring coins

The Aptos CLI is a simple wallet as well, and can transfer coins between accounts. bash $ ./aptos account transfer --account superuser --amount 100 { "Result": { "gas_used": 86, "balance_changes": { "18b61497fd290b02bb0751f44381cada1657c2b3aa6194a00d9bc9a85fad3b04": { "coin": { "value": "10100" } }, "50a49d913aa6381c01579e3fc00784b49afa3a771f06389ebc65f8ff3a4e9a7d": { "coin": { "value": "9814" } } }, "sender": "50a49d913aa6381c01579e3fc00784b49afa3a771f06389ebc65f8ff3a4e9a7d", "success": true, "version": 270408, "vm_status": "Executed successfully" } }

Generating a Peer config

To allow others to connect to your node, you need to generate a peer configuration. Below command shows how you can use the aptos CLI to generate a peer configuration and write it into a file named peer_config.yaml. bash $ aptos key extract-peer --output-file peer_config.yaml

The above command will generate the following output on the terminal: ```bash { "Result": { "027eeddfbda3780b51e44731f0b214e53715cd17cdaecac99dc61590c1f2b76a": { "addresses": [], "keys": [ "0x027eeddfbda3780b51e44731f0b214e53715cd17cdaecac99dc61590c1f2b76a" ], "role": "Upstream" } } }

```

The peer_config.yaml file will be created in your current working directory, with the contents as shown in the below example:

```bash

027eeddfbda3780b51e44731f0b214e53715cd17cdaecac99dc61590c1f2b76a: addresses: [] keys: - "0x027eeddfbda3780b51e44731f0b214e53715cd17cdaecac99dc61590c1f2b76a" role: Upstream ```

Note: In the addresses key, you should fill in your address.

Compiling Move

The aptos CLI can be used to compile a Move package locally. The below example uses the HelloBlockchain in move-examples.

bash aptos move compile --package-dir aptos-move/move-examples/hello_blockchain/ --named-addresses HelloBlockchain=8946741e5c907c43c9e042b3739993f32904723f8e2d1491564d38959b59ac71

The above command will generate the below terminal output: bash { "Result": [ "8946741E5C907C43C9E042B3739993F32904723F8E2D1491564D38959B59AC71::Message" ] }

Compiling & Unit Testing Move

The aptos CLI can also be used to compile and run unit tests locally. In this example, we'll use the HelloBlockchain in move-examples.

bash aptos move test --package-dir aptos-move/move-examples/hello_blockchain/ --named-addresses HelloBlockchain=8946741e5c907c43c9e042b3739993f32904723f8e2d1491564d38959b59ac71 The above command will generate the following terminal output: bash BUILDING MoveStdlib BUILDING AptosFramework BUILDING Examples Running Move unit tests [ PASS ] 0x8946741e5c907c43c9e042b3739993f32904723f8e2d1491564d38959b59ac71::Message::sender_can_set_message [ PASS ] 0x8946741e5c907c43c9e042b3739993f32904723f8e2d1491564d38959b59ac71::MessageTests::sender_can_set_message Test result: OK. Total tests: 2; passed: 2; failed: 0 { "Result": "Success" }

Debug and Print Stacktrace

In this example, we will use DebugDemo in debug-move

First, you need to include Move nursery in your Move.toml file toml file

Now, you can use Debug::print and Debug::print_stack_trace in your move file

You can run the following command: bash aptos move test --package-dir crates/aptos/debug-move-example

The command will generate the following output: ```bash Running Move unit tests [debug] 0000000000000000000000000000000000000000000000000000000000000001 Call Stack: [0] 0000000000000000000000000000000000000000000000000000000000000001::Message::sendercanset_message

    Code:
        [4] CallGeneric(0)
        [5] MoveLoc(0)
        [6] LdConst(0)
      > [7] Call(1)
        [8] Ret

    Locals:
        [0] -
        [1] 0000000000000000000000000000000000000000000000000000000000000001

Operand Stack: ```

Publishing a Move Package with a named address

In this example, we'll use the HelloBlockchain in move-examples.

Publish the package with your account address set for HelloBlockchain.

Here, you need to change 8946741e5c907c43c9e042b3739993f32904723f8e2d1491564d38959b59ac71 to your account address. bash aptos move publish --package-dir aptos-move/move-examples/hello_blockchain/ --named-addresses HelloBlockchain=8946741e5c907c43c9e042b3739993f32904723f8e2d1491564d38959b59ac71

You can additionally use named profiles for the addresses. The first placeholder is default bash aptos move publish --package-dir aptos-move/move-examples/hello_blockchain/ --named-addresses HelloBlockchain=default

Running a Move Function

Now that you've published the function above, you can run it.

Arguments must be given a type with a colon to separate it. In this example, we want the input to be parsed as a string, so we put string:Hello!.

bash aptos move run --function-id 0x8946741e5c907c43c9e042b3739993f32904723f8e2d1491564d38959b59ac71::Message::set_message --args string:hello!

Additionally, profiles can replace addresses in the function id. bash aptos move run --function-id default::Message::set_message --args string:hello!

Genesis Ceremonies

The aptos tool supports bootstrapping new blockchains through what is known as a genesis ceremony. The output of the genesis ceremony is the output of move instructions that prepares a blockchain for online operation. The input consists of:

A set of validators and their configuration
The initial set of Move modules, known as a framework
A unique ChainId (u8) that distinguishes this from other deployments
For test chains, there also exists an account that manages the minting of TestCoin

Generating Genesis

The genesis organizer constructs a Layout and distributes it.
The genesis organizer prepares the Aptos framework's bytecode and distributes it.
Each participant generates their ValidatorConfiguration and distributes it.
Each participant generates a genesis.blob from the resulting contributions
The genesis organizer executes the genesis.blob to derive the initial waypoint and distributes it.
Each participant begins their aptos-node. The aptos-node verifies upon startup that the genesis.blob with the waypoint provided by the genesis organizer .
The blockchain will begin consensus after a quorum of stake is available.

Prepare Aptos-core

The following guide assumes that you have access to the Aptos-core repository or the associated tools. You can download and prepare Aptos-core from GitHub:

git clone https://github.com/aptos-labs/aptos-core.git cd aptos-core git checkout --track origin/testnet ./scripts/dev_setup.sh source ~/.cargo/env

The `Layout` File

The layout file contains: * root_key: an Ed25519 public key for TestCoin management. * users: the set of participants * chain_id: the ChainId or a unique integer that distinguishes this deployment from other Aptos networks

An example: root_key: "0xca3579457555c80fc7bb39964eb298c414fd60f81a2f8eedb0244ec07a26e575" users: - alice - bob chain_id: 8

Building the Aptos Framework

From your Aptos-core repository, build the framework and package it: cargo run --package framework mkdir aptos-framework-release cp aptos-framework/releases/artifacts/current/build/**/bytecode_modules/* aptos-framework-release

The framework will be stored within the aptos-framework-release directory.

The `ValidatorConfiguration` File

The ValidatorConfiguration file contains:

account_address: The account that manages this validator. This must be derived from the account_key provided within te ValidatorConfiguration file.
consensus_key: The public key for authenticating consensus messages from the validator
account_key: The public key for the account that manages this validator. This is used to derive the account_address.
network_key: The public key for both validator and fullnode network authentication and encryption.
validator_host: The network address where the validator resides. This contains a host and port field. The host should either be a DNS name or an IP address. Currently only IPv4 is supported.
full_node_host: An optional network address where the fullnode resides. This contains a host and port field. The host should either be a DNS name or an IP address. Currently only IPv4 is supported.
stake_amount: The number of coins being staked by this node. This is expected to be 1, if it is different the configuration will be considered invalid.

An example: account_address: ccd49f3ea764365ac21e99f029ca63a9b0fbfab1c8d8d5482900e4fa32c5448a consensus_key: "0xa05b8f41057ac72f9ca99f5e3b1b787930f03ba5e448661f2a1fac98371775ee" account_key: "0x3d15ab64c8b14c9aab95287fd0eb894aad0b4bd929a5581bcc8225b5688f053b" network_key: "0x43ce1a4ac031b98bb1ee4a5cd72a4cca0fd72933d64b22cef4f1a61895c2e544" validator_host: host: bobs_host port: 6180 full_node_host: host: bobs_host port: 6182 stake_amount: 1

To generate this using the aptos CLI:

Generate your validator's keys:

cargo run --package aptos -- genesis generate-keys --output-dir bobs

Generate your ValidatorConfiguration:

cargo run --package aptos -- \\ genesis set-validator-configuration \\ --keys-dir bobs \\ --username bob \\ --validator-host bobs_host:6180 \\ --full-node-host bobs_host:6180 \\ --local-repository-dir .

The last command will produce a bob.yaml file that should be distributed to other participants for genesis.blob generation.

Generating a Genesis and Waypoint

genesis.blob and the waypoint can be generated after obtaining the Layout file, each of the individual ValidatorConfiguration files, and the framework release. It is important to validate that the ValidatorConfiguration provided in the earlier stage is the same as in the distribution for generating the genesis.blob. If there is a mismatch, inform all participants.

To generate the genesis.blob and waypoint: * Place the Layout file in a directory, e.g., genesis. * Place all the ValidatorConfiguration files into the genesis directory. * Ensure that the ValidatorConfiguration files are listed under the set of users within the Layout file. * Make a framework directory within the genesiss directory and place the framework release .mv files into the framework directory. * Use the aptos CLI to generate genesis and waypoint:

cargo run --package aptos -- genesis generate-genesis --local-repository-dir genesis

Starting an `aptos-node`

Upon generating the genesis.blob and waypoint, place them into your validator and fullnode's configuration directory and begin your validator and fullnode.