CLI for the Autonomi Network

Usage

ant [OPTIONS] <COMMAND>

Options

• --log-output-dest <LOG_OUTPUT_DEST>: Specify the logging output destination. [default: data-dir]
• --log-format <LOG_FORMAT>: Specify the logging format.
• --peer <multiaddr>: Peer(s) to use for bootstrap, in a 'multiaddr' format containing the peer ID [env: ANT_PEERS=]
• --timeout <CONNECTION_TIMEOUT>: The maximum duration to wait for a connection to the network before timing out
• -x, --no-verify: Prevent verification of data storage on the network
• -h, --help: Print help (see more with '--help')
• -V, --version: Print version

Commands

File

• file cost <file>
• file upload <file> [--public] [--no-archive] [--retry-failed 3]
• file download <addr> <dest_file>
• file list

Reference : File

Register

• register generate-key [--overwrite]
• register cost <name>
• register create <name> <value>
• register edit [--name] <address> <value>
• register get [--name] <address>
• register list

Reference : Register

Vault

• vault cost
• vault create
• vault load
• vault sync [--force]

Reference : Vault

Scratchpad

• scratchpad generate-key [--overwrite]
• scratchpad cost <name>
• scratchpad create <name> <data> [--max-fee-per-gas <value>]
• scratchpad share <name>
• scratchpad get <name> [--secret-key] [--hex]
• scratchpad edit <name> <data> [--secret-key]
• scratchpad list

Reference : Scratchpad

Wallet

• wallet create [--no-password] [--password <password>]
• wallet import <private_key> [--no-password] [--password <password>]
• wallet balance
• wallet export

Reference : Wallet

Analyze

• analyze <address>

Reference : Analyze

Help

• help
• help <COMMAND>

Installation

You can install the Autonomi CLI in two ways: by directly downloading the binary from GitHub or by building it from source using a terminal.

Option 1: Downloading the Binary from GitHub

1. Go to the Releases page on GitHub.
2. Download the latest release for your operating system.
3. Extract the downloaded archive.
4. Move the binary to a directory included in your system's PATH.

Option 2: Build locally

1. Ensure you have Rust and Cargo installed on your machine. You can download them from rust-lang.org
2. Clone the repository

git clone https://github.com/maidsafe/autonomi.git
cd autonomi

3. Build the CLI:

cargo build --release --bin=ant

4. Add the CLI to your PATH / Environment Variables

Windows (PowerShell)

$env:PATH += ";C:\path\to\your\binary"
[System.Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\path\to\your\binary", [System.EnvironmentVariableTarget]::User)

macOS and Linux (Bash)

export PATH=$PATH:/path/to/your/binary
echo 'export PATH=$PATH:/path/to/your/binary' >> ~/.bashrc
source ~/.bashrc

Options

Specify the logging output destination.

--log-output-dest <LOG_OUTPUT_DEST>

Default value: data-dir
Valid values: [stdout , data-dir , <custom path>]

The data directory location is platform specific:

OS	Path
Linux	$HOME/.local/share/autonomi/client/logs
macOS	$HOME/Library/Application Support/autonomi/client/logs
Windows	%AppData%\autonomi\client\logs

Specify the logging format.

--log-format <LOG_FORMAT>

Valid values [default , json]

If the argument is not used, the default format will be applied.

Specify the Connection Timeout

--timeout <CONNECTION_TIMEOUT>

Default value: 120
Valid values: [0 - 999]

The maximum duration to wait for a connection to the network before timing out.
This value is expressed in seconds.

Prevent verification of data storage on the network.

-x, --no-verify

This may increase operation speed, but offers no guarantees that operations were successful.

Reference

File Operations

Get a cost estimate for storing a file

file cost <file>

Gets a cost estimate for uploading a file to the network. This returns both the storage costs and gas fees for the file.

Expected value:

• <file>: File path (accessible by current user)

Upload a file

file upload <file> [--public] [--no-archive] [--retry-failed 3]

Uploads a file to the network.

Expected value:

• <file>: File path (accessible by current user)

The following flags can be added:

• --public (Optional) Specifying this will make this file publicly available to anyone on the network
• --no-archive (Optional) Skip creating local archive after upload. Only upload files without saving archive information. Note that --no-archive is the default behaviour for single file uploads (folk can still upload a single file as an archive by putting it in a directory)
• --retry-failed (Optional) Automatically retry failed uploads. This is particularly useful for handling gas fee errors when the network base fee exceeds your --max-fee-per-gas setting. The retry mechanism works at the batch level, so only failed chunks are retried, not the entire file upload process. Being the times of the original chunks, default is 0 for not carrying out retry.

Example usage with retry functionality:

ant file upload myfile.txt --public --retry-failed 3 --max-fee-per-gas 10000000

This will upload the file publicly and automatically retry if the base fee is higher than arbitrums minimum gas fee, showing detailed error messages with current gas prices. Using these settings ensures your data goes up at minimum cost (but depending on current blockchain fees and the amount of data this might take a while)

Download a file

file download <addr> <dest_path>

Download a file from network address to output path

Expected values:

• <addr>: The network address of a file
• <dest_path>: The output path to download the file to

List the files in a vault

file list

Lists all files (both public and private) in a vault.

Register Operations

Generate a key for a register

register generate-key [--overwrite]

Generate a new register key

The following flag can be applied: --overwrite (Optional) Adding this flag will overwrite any existing key, and result in loss of access to any existing registers created using that key

Get a cost estimate for storing a register on the network

register cost <name>

Gets a cost estimate for storing a register on the network. This returns both the storage costs and gas fees.

Create a new register and upload to the network

register create <name> <value>

Create a new register with the given name and value. Note: that anyone with the register address can read its value.

Expected values:

• <name>: The name of the register
• <value>: The value to store in the register

Edit an existing register

register edit [--name] <address> <value>

Edit an existing register

Expected values:

• <address>: The address of the register to edit
• <value>: The new value to store in the register

The following flag can be applied: --name:bool (Optional) Adding this flag will use the name of the register instead of the address Note: that only the owner of the register can use this shorthand as the address can be generated from the name and register key.

Get a register

register get [--name] <address>

Get a register from the network

Expected values:

• <address>: The address of the register

The following flag can be applied: --name:bool (Optional) Adding this flag will use the name of the register instead of the address Note: that only the owner of the register can use this shorthand as the address can be generated from the name and register key.

List registers

register list

List local registers

Vault Operations

Get a cost estimate for storing a vault on the network

vault cost

Gets a cost estimate for uploading a vault to the network. This returns both the storage costs and gas fees for the vault.

Create a new vault and upload to the network

vault create

Creates a new vault and uploads it to the network. This will initialise a new vault in the local storage and then upload it to the network.

Load vault from the network

vault load

Retrieves data from the network and writes it to local storage. This will download the vault data from the network and synchronise it with the local storage.

Sync local data with the network

vault sync [--force]

Sync the users local data with the network vault data.

The following flag can be applied: --force (Optional) Add this flag to overwrite data in the vault with local user data

Wallet Operations

Create a new wallet

wallet create [--no-password] 

You will be prompted for an optional password, ignoring this will not encrypt the wallet. This will output the private key for the wallet, the public key for the wallet, and the stored location on device.

The following flags can be used to explictly include or exclude encryption of the created wallet

--no-password (Optional) Add this flag to skip the password prompt and encryption step.
--password <password> (Optional) Add this flag to encrypt the create wallet

Note on wallet security Encrypted wallets provide an additional layer of security, requiring a password to read the private key and perform transactions. However, ensure you remember your password; losing it may result in the inability to access your encrypted wallet.

Imports an existing wallet from a private key

wallet import <private_key>

The following flags can be used to explictly include or exclude encryption of the imported wallet

--no-password (Optional) Add this flag to skip the password prompt and encryption step.
--password <password> (Optional) Add this flag to encrypt the create wallet

Displays the wallet balance

wallet balance

This will display both the token and gas balances.

Display the wallet details

wallet export

This will display both the address and private key of the wallet.

Analyze Operations

Analyze an address to get the address type, and visualize the content.

analyze <address>

Scratchpad Operations

Generate a new scratchpad key

scratchpad generate-key [--overwrite]

Generate a new general scratchpad key from which all your scratchpad keys can be derived.

The following flag can be applied: --overwrite (Optional) Warning: overwriting the existing key will result in loss of access to any existing scratchpads

Get a cost estimate for creating a scratchpad

scratchpad cost <name>

Gets a cost estimate for creating a scratchpad on the network.

Expected values:

• <name>: The name of the scratchpad

Create a new scratchpad

scratchpad create <name> <data> [--max-fee-per-gas <value>]

Create a new scratchpad with the given name and data.

Expected values:

• <name>: The name of the scratchpad
• <data>: The data to store in the scratchpad (Up to 4MB)

The following flag can be applied: --max-fee-per-gas <value> (Optional) Specify the maximum fee per gas

Share a scratchpad

scratchpad share <name>

Share a scratchpad secret key with someone else. Sharing this key means that the other party will have permanent read and write access to the scratchpad.

Expected values:

• <name>: The name of the scratchpad

Get a scratchpad

scratchpad get <name> [--secret-key] [--hex]

Get the contents of an existing scratchpad from the network.

Expected values:

• <name>: The name of the scratchpad

The following flags can be applied: --secret-key (Optional) Indicate that this is an external scratchpad secret key (Use when interacting with a shared scratchpad) --hex (Optional) Display the data as a hex string instead of raw bytes

Edit a scratchpad

scratchpad edit <name> <data> [--secret-key]

Edit the contents of an existing scratchpad.

Expected values:

• <name>: The name of the scratchpad
• <data>: The new data to store in the scratchpad (Up to 4MB)

The following flag can be applied: --secret-key (Optional) Indicate that this is an external scratchpad secret key (Use when interacting with a shared scratchpad)

List scratchpads

scratchpad list

List owned scratchpads.

Error Handling

If you encounter any errors while using the CLI, you can use the --log-output-dest and --log-format options to specify logging details. This can help with debugging and understanding the behavior of the CLI.

License

This Autonomi Network repository is licensed under the General Public License (GPL), version 3 (LICENSE).

Contributing

Contributions are welcome! Please read the CONTRIBUTING.md file for guidelines on how to contribute to this project.