Merge pull request #2545 from maidsafe/Nic-dorman-patch-2

chore: update CLI readme
maidsafe · Dec 17, 2024 · 537a040 · 537a040
2 parents 8904816 + 5f2f985
commit 537a040
Showing 1 changed file with 233 additions and 62 deletions.
diff --git 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] <COMMAND>
+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      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 <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
-```
+### File
+- `file cost <file>`
+- `file upload <file> [--public]`
+- `file download <addr> <dest_file>`
+- `file list`
+
+[Reference : File](#file-operations)
+
+### Register [Deprecated]
+- `register generate-key [--overwrite]`
+- `register cost <name>`
+- `register create <name> <value> [--public]`
+- `register edit [--name] <address> <value>`
+- `register get [--name] <address>`
+- `register list`
+
+### Vault
+- `vault cost`
+- `vault create`
+- `vault load`
+- `vault sync [--force]`
+
+[Reference : Vault](#vault-operations)
+
+### Wallet
+- `wallet create [--no-password] [--password <password>]`
+- `wallet import <private_key> [--no-password] [--password <password>]`
+- `wallet balance`
+- `wallet export`
+
+[Reference : Wallet](#wallet-operations)
+
+### 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.
 
-## 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 <LOG_OUTPUT_DEST>
+```
 
-Example:
+Default value: `data-dir`\
+Valid values: [`stdout` , `data-dir` , <custom path\>]
 
-   ```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 <LOG_FORMAT>
+```   
+Valid values [`default` , `json`]
 
-```bash
-wallet create --private-key <PRIVATE_KEY>
+If the argument is not used, the default format will be applied.
+
+### Specify the Connection Timeout
 ```
+--timeout <CONNECTION_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 <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]
+```
+Uploads a file to the network.
+
+Expected value: 
+- `<file>`: 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 <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
 
-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 <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.
+
+
+## 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.