From fc0d770ab1b753b39cb1474a2da0900df9de8904 Mon Sep 17 00:00:00 2001 From: Greg Nazario Date: Thu, 5 May 2022 17:04:39 -0700 Subject: [PATCH] [aptos-cli] Update README Closes: #823 --- crates/aptos/README.md | 209 +++++++++++++++++++++++++++++++++++------ 1 file changed, 182 insertions(+), 27 deletions(-) diff --git a/crates/aptos/README.md b/crates/aptos/README.md index 4d6c3b45fbedc..c9aedcf5e2f1c 100644 --- a/crates/aptos/README.md +++ b/crates/aptos/README.md @@ -3,7 +3,15 @@ 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 Cargo +### Install precompiled binary (easy mode) +* Navigate to the [release page](https://github.com/aptos-labs/aptos-core/releases) 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](https://doc.rust-lang.org/cargo/getting-started/installation.html) and install `cargo`. Proceed only after you successfully install `cargo`. @@ -25,7 +33,7 @@ which aptos ## Using the `aptos` CLI ### Command Line Help -Command line help is available. Type `aptos --help` to see the available command options. +Command line help is available. Type `aptos help` or `aptos --help` to see the available command options. ```bash $ aptos help aptos 0.1.0 @@ -41,9 +49,12 @@ OPTIONS: 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 int + 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. @@ -62,6 +73,7 @@ OPTIONS: 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 @@ -74,7 +86,7 @@ aptos-move-compile 0.1.0 Compiles a package and returns the [`ModuleId`]s USAGE: - aptos move compile [OPTIONS] --package-dir + aptos move compile [OPTIONS] OPTIONS: -h, --help @@ -97,6 +109,8 @@ OPTIONS: --package-dir Path to a move package (the folder with a Move.toml file) + [default: .] + -V, --version Print version information ``` @@ -106,8 +120,8 @@ OPTIONS: ### 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. Right now it supports only private keys, but will support -more in the future. +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 @@ -115,17 +129,18 @@ 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] +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] +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)] +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 6C0DAB5A4F0FD733168BB8675FB5D20B802CCAD5FB58794DC0C26A48B11B9FC0 doesn't exist, creating it and funding it with 10000 coins -Aptos is now set up for account 6C0DAB5A4F0FD733168BB8675FB5D20B802CCAD5FB58794DC0C26A48B11B9FC0! Run `aptos help` for more information about commands +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" } @@ -143,26 +158,27 @@ by adding the `--profile` argument, and can be used in most other commands to re ```bash $ aptos init --profile superuser Configuring for profile superuser -Enter your rest endpoint [Current: None No input: https://fullnode.devnet.aptoslabs.com] +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] +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)] +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 6C0DAB5A4F0FD733168BB8675FB5D20B802CCAD5FB58794DC0C26A48B11B9FC0 doesn't exist, creating it and funding it with 10000 coins -Aptos is now set up for account 6C0DAB5A4F0FD733168BB8675FB5D20B802CCAD5FB58794DC0C26A48B11B9FC0! Run `aptos help` for more information about commands +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" } + ``` ### 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 --account 6C0DAB5A4F0FD733168BB8675FB5D20B802CCAD5FB58794DC0C26A48B11B9FC0 +$ aptos account list --account 18B61497FD290B02BB0751F44381CADA1657C2B3AA6194A00D9BC9A85FAD3B04 ``` @@ -172,12 +188,47 @@ The above command will generate the following resource list information on your { "Result": [ { - "authentication_key": "0x5f0f53b1394364832e78add00c7412be0845cd583caa36ffb1a2bffbf1cbaf83", - "self_address": "0x1", + "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 + } + } } ] } + ``` You can additionally list the default profile from configuration with no account specified. @@ -186,9 +237,91 @@ $ aptos account list { "Result": [ { - "authentication_key": "0x5f0f53b1394364832e78add00c7412be0845cd583caa36ffb1a2bffbf1cbaf83", - "self_address": "0x1", + "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 --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 + } + } } ] } @@ -198,7 +331,28 @@ $ aptos account list The Aptos CLI is a simple wallet as well, and can transfer coins between accounts. ```bash -aptos account transfer --account 0x5f0f53b1394364832e78add00c7412be0845cd583caa36ffb1a2bffbf1cbaf83 --amount 50 +$ ./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 @@ -206,31 +360,32 @@ aptos account transfer --account 0x5f0f53b1394364832e78add00c7412be0845cd583caa3 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 --private-key-file my-key.key --output-file peer_config.yaml +$ aptos key extract-peer --output-file peer_config.yaml ``` The above command will generate the following output on the terminal: ```bash { "Result": { - "8946741e5c907c43c9e042b3739993f32904723f8e2d1491564d38959b59ac71": { + "027eeddfbda3780b51e44731f0b214e53715cd17cdaecac99dc61590c1f2b76a": { "addresses": [], "keys": [ - "0x8946741e5c907c43c9e042b3739993f32904723f8e2d1491564d38959b59ac71" + "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 --- -8946741e5c907c43c9e042b3739993f32904723f8e2d1491564d38959b59ac71: +027eeddfbda3780b51e44731f0b214e53715cd17cdaecac99dc61590c1f2b76a: addresses: [] keys: - - "0x8946741e5c907c43c9e042b3739993f32904723f8e2d1491564d38959b59ac71" + - "0x027eeddfbda3780b51e44731f0b214e53715cd17cdaecac99dc61590c1f2b76a" role: Upstream ```