Skip to content

Commit

Permalink
[aptos-cli] Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
gregnazario authored and aptos-bot committed May 6, 2022
1 parent e57be6b commit fc0d770
Showing 1 changed file with 182 additions and 27 deletions.
209 changes: 182 additions & 27 deletions crates/aptos/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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 <PACKAGE_DIR>
aptos move compile [OPTIONS]

OPTIONS:
-h, --help
Expand All @@ -97,6 +109,8 @@ OPTIONS:
--package-dir <PACKAGE_DIR>
Path to a move package (the folder with a Move.toml file)

[default: .]

-V, --version
Print version information
```
Expand All @@ -106,26 +120,27 @@ 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
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"
}
Expand All @@ -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
```
Expand All @@ -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.
Expand All @@ -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
}
}
}
]
}
Expand All @@ -198,39 +331,61 @@ $ 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
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
```
Expand Down

0 comments on commit fc0d770

Please sign in to comment.