diff --git a/ant-cli/README.md b/ant-cli/README.md index c8c57392ad..6093ff220d 100644 --- a/ant-cli/README.md +++ b/ant-cli/README.md @@ -1,87 +1,258 @@ -# A CLI for the Autonomi Network +# CLI for the Autonomi Network +## Usage ``` -Usage: ant [OPTIONS] +ant [OPTIONS] +``` +### Options +- `--log-output-dest `: Specify the logging output destination. [default: data-dir] +- `--log-format `: Specify the logging format. +- `--peer `: Peer(s) to use for bootstrap, in a 'multiaddr' format containing the peer ID [env: ANT_PEERS=] +- `--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 Operations related to file handling - register Operations related to register management - vault Operations related to vault management - wallet Operations related to wallet management - help Print this message or the help of the given subcommand(s) +## Commands -Options: - --log-output-dest - Specify the logging output destination. [default: data-dir] - --log-format - Specify the logging format. - --peer - Peer(s) to use for bootstrap, in a 'multiaddr' format containing the peer ID [env: ANT_PEERS=] - --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 -``` +### File +- `file cost ` +- `file upload [--public]` +- `file download ` +- `file list` + +[Reference : File](#file-operations) + +### Register [Deprecated] +- `register generate-key [--overwrite]` +- `register cost ` +- `register create [--public]` +- `register edit [--name]
` +- `register get [--name]
` +- `register list` + +### Vault +- `vault cost` +- `vault create` +- `vault load` +- `vault sync [--force]` + +[Reference : Vault](#vault-operations) + +### Wallet +- `wallet create [--no-password] [--password ]` +- `wallet import [--no-password] [--password ]` +- `wallet balance` +- `wallet export` + +[Reference : Wallet](#wallet-operations) + +### Help +- `help` +- `help ` + + +## 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. -## Wallet +### Option 1: Downloading the Binary from GitHub -### Create a new wallet +1. Go to the [Releases](https://github.com/maidsafe/autonomi/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) +```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) ```bash -wallet create +export PATH=$PATH:/path/to/your/binary +echo 'export PATH=$PATH:/path/to/your/binary' >> ~/.bashrc +source ~/.bashrc ``` -> Add the `--no-password` flag to skip the optional encryption step. +## Reference -> **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. +### Specify the logging output destination. +``` +--log-output-dest +``` -Example: +Default value: `data-dir`\ +Valid values: [`stdout` , `data-dir` , ] - ```bash - $ wallet create - Enter password (leave empty for none): - Repeat password: - Wallet address: 0xaf676aC7C821977506AC9DcE28bFe83fb06938d8 - Stored wallet in: "/Users/macuser/Library/Application Support/autonomi/client/wallets/0xaf676aC7C821977506AC9DcE28bFe83fb06938d8.encrypted" - ``` +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 | -### Import a wallet +### Specify the logging format. +``` +--log-format +``` +Valid values [`default` , `json`] -```bash -wallet create --private-key +If the argument is not used, the default format will be applied. + +### Specify the Connection Timeout ``` +--timeout +``` -### Check wallet balance +Default value: `120`\ +Valid values: [`0 - 999`] -```bash -wallet balance +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. -Example: - ```bash - $ wallet balance - Wallet balances: 0x5A631e17FfB0F07b00D88E0e42246495Bf21d698 - +---------------+---+ - | Token Balance | 0 | - +---------------+---+ - | Gas Balance | 0 | - +---------------+---+ - ``` +### File Operations -## License +#### Get a cost estimate for storing a file +``` +file cost +``` + +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 path (accessible by current user) + + +#### Upload a file +``` +file upload [--public] +``` +Uploads a file to the network. + +Expected value: +- ``: File path (accessible by current user) + +The following flag can be added: +`--public` (Optional) Specifying this will make this file publicly available to anyone on the network + +#### Download a file +``` +file download +``` +Download a file from network address to output path + +Expected values: +- ``: The network address of a file +- ``: The output path to download the file to -This Safe Network repository is licensed under the General Public License (GPL), version -3 ([LICENSE](LICENSE) http://www.gnu.org/licenses/gpl-3.0.en.html). ---- +#### List the files in a vault +``` +file list +``` +Lists all files (both public and private) in a vault. + + +### 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 ` (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 +``` + +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 ` (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. + + +## 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 Safe Network repository is licensed under the General Public License (GPL), version 3 (LICENSE http://www.gnu.org/licenses/gpl-3.0.en.html). -Feel free to modify or expand upon this README as needed. Would you like to add or change anything else? +## Contributing +Contributions are welcome! Please read the [CONTRIBUTING.md](https://github.com/maidsafe/autonomi/blob/main/CONTRIBUTING.md) file for guidelines on how to contribute to this project.