summaryrefslogtreecommitdiffstats
path: root/docs/cli/overview.md
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-03-28 06:11:39 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-03-28 06:11:39 +0000
commit1fd6a618b60d7168fd8f37585d5d39d22d775afd (patch)
treefbc6d0c213b8acdd0a31deafe5c5fc0d05a3a312 /docs/cli/overview.md
parentInitial commit. (diff)
downloadanta-1fd6a618b60d7168fd8f37585d5d39d22d775afd.tar.xz
anta-1fd6a618b60d7168fd8f37585d5d39d22d775afd.zip
Adding upstream version 0.13.0.upstream/0.13.0
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/cli/overview.md')
-rw-r--r--docs/cli/overview.md103
1 files changed, 103 insertions, 0 deletions
diff --git a/docs/cli/overview.md b/docs/cli/overview.md
new file mode 100644
index 0000000..90e70a5
--- /dev/null
+++ b/docs/cli/overview.md
@@ -0,0 +1,103 @@
+<!--
+ ~ Copyright (c) 2023-2024 Arista Networks, Inc.
+ ~ Use of this source code is governed by the Apache License 2.0
+ ~ that can be found in the LICENSE file.
+ -->
+
+# Overview of ANTA's Command-Line Interface (CLI)
+
+ANTA provides a powerful Command-Line Interface (CLI) to perform a wide range of operations. This document provides a comprehensive overview of ANTA CLI usage and its commands.
+
+ANTA can also be used as a Python library, allowing you to build your own tools based on it. Visit this [page](../advanced_usages/as-python-lib.md) for more details.
+
+To start using the ANTA CLI, open your terminal and type `anta`.
+
+!!! warning
+ The ANTA CLI options have changed after version 0.11 and have moved away from the top level `anta` and are now required at their respective commands (e.g. `anta nrfu`). This breaking change occurs after users feedback on making the CLI more intuitive. This change should not affect user experience when using environment variables.
+
+## Invoking ANTA CLI
+
+```bash
+$ anta --help
+--8<-- "anta_help.txt"
+```
+
+## ANTA environement variables
+
+Certain parameters are required and can be either passed to the ANTA CLI or set as an environment variable (ENV VAR).
+
+To pass the parameters via the CLI:
+
+```bash
+anta nrfu -u admin -p arista123 -i inventory.yaml -c tests.yaml
+```
+
+To set them as environment variables:
+
+```bash
+export ANTA_USERNAME=admin
+export ANTA_PASSWORD=arista123
+export ANTA_INVENTORY=inventory.yml
+export ANTA_INVENTORY=tests.yml
+```
+
+Then, run the CLI without options:
+
+```bash
+anta nrfu
+```
+
+!!! note
+ All environement variables may not be needed for every commands.
+ Refer to `<command> --help` for the comprehensive environment varibles names.
+
+Below are the environement variables usable with the `anta nrfu` command:
+
+| Variable Name | Purpose | Required |
+| ------------- | ------- |----------|
+| ANTA_USERNAME | The username to use in the inventory to connect to devices. | Yes |
+| ANTA_PASSWORD | The password to use in the inventory to connect to devices. | Yes |
+| ANTA_INVENTORY | The path to the inventory file. | Yes |
+| ANTA_CATALOG | The path to the catalog file. | Yes |
+| ANTA_PROMPT | The value to pass to the prompt for password is password is not provided | No |
+| ANTA_INSECURE | Whether or not using insecure mode when connecting to the EOS devices HTTP API. | No |
+| ANTA_DISABLE_CACHE | A variable to disable caching for all ANTA tests (enabled by default). | No |
+| ANTA_ENABLE | Whether it is necessary to go to enable mode on devices. | No |
+| ANTA_ENABLE_PASSWORD | The optional enable password, when this variable is set, ANTA_ENABLE or `--enable` is required. | No |
+
+!!! info
+ Caching can be disabled with the global parameter `--disable-cache`. For more details about how caching is implemented in ANTA, please refer to [Caching in ANTA](../advanced_usages/caching.md).
+
+## ANTA Exit Codes
+
+ANTA CLI utilizes the following exit codes:
+
+- `Exit code 0` - All tests passed successfully.
+- `Exit code 1` - An internal error occurred while executing ANTA.
+- `Exit code 2` - A usage error was raised.
+- `Exit code 3` - Tests were run, but at least one test returned an error.
+- `Exit code 4` - Tests were run, but at least one test returned a failure.
+
+To ignore the test status, use `anta nrfu --ignore-status`, and the exit code will always be 0.
+
+To ignore errors, use `anta nrfu --ignore-error`, and the exit code will be 0 if all tests succeeded or 1 if any test failed.
+
+## Shell Completion
+
+You can enable shell completion for the ANTA CLI:
+
+=== "ZSH"
+
+ If you use ZSH shell, add the following line in your `~/.zshrc`:
+
+ ```bash
+ eval "$(_ANTA_COMPLETE=zsh_source anta)" > /dev/null
+ ```
+
+=== "BASH"
+
+ With bash, add the following line in your `~/.bashrc`:
+
+ ```bash
+ eval "$(_ANTA_COMPLETE=bash_source anta)" > /dev/null
+ ```