agility-docs

AGILITY Command Line (CLI) Tool

Introduction

The agility command-line interface (CLI) tool is for managing and performing various operations related to the AGILITY platform. The CLI tool has several commands, sub commands, and options that can be used to interact with different components of the AGILITY system.

ℹ️ Inside the VM this tool runs as root user.

sudo su -

[root@localhost ~]# agility --help
Usage: agility [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  backup       Manage backups (VM Only).
  cv           Manage AGILITY ContinuousValidation instance.
  diagnostics  Diagnose and troubleshoot your AGILITY instance.
  ingress      Manage ingress settings.
  k3s          Manage k3s configuration.
  license      Manage AGILITY license.
  monitoring   Manage AGILITY Monitoring Stack.
  proxy        Manage proxy configuration.
  sftp         Manage SFTP configurations.
  telemetry    Manage telemetry settings.
  toolbox      Manage AGILITY Toolbox Component.
  upgrade      Upgrade AGILITY components.
  version      Show AGILITY components version information.

In case of errors or other problems, please check the General Troubleshooting document.

The options available in the CLI tool:

Command: backup

Manage backups (VM Only).

Sub Command: local

Manage local (internal) backups.

Sub Command Description Options Example
create Create a new backup. [--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. </br>[--full] Perform a full backup. Default behavior if neither --full nor --diff is specified. </br>[--diff] Perform a differential (delta) backup. agility backup s3 create
restore Restore DB In-Place from a local backup. [--namespace] TEXT: Namespace in which AGILITY is installed. Default is ‘agility’. </br>[--time] TEXT: Point-in-Time Recovery (PITR) to restore the database to. Format: ‘YYYY-MM-DD HH:mm:ss-TZ’. </br>[--auto-accept] Automatically accept the restore operation without prompting. agility backup local restore
status Show the available backups status. [--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. </br>[--debug] Shows more details. agility backup local status

Sub Command: settings

Configure local bucket backup settings. | Sub Command | Description | Options | Example | | ———– | —————————————- | ——————————————————————————————————————————————————————————————————————————————————————————————- | —————————— | | apply | Apply local backup retention settings. | --retention-count INTEGER: Number of local backups to retain. </br>[--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. | Recommended: </br>agility backup local settings apply </br> </br> Complete: </br>agility backup local settings apply --retention-count=10 | | list | List current local backup retention settings. | [--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. | agility backup local settings list |

Sub Command: s3

Manage S3 bucket backups.

Sub Command Description Options Example
clone Clone the DB from another S3 backup. [--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. </br>[--bucket-name] TEXT: Specify the S3 bucket name. </br>[--endpoint] TEXT: Specify the S3 endpoint. </br>[--path] TEXT: Specify the S3 path. </br>[--region] TEXT: Specify the S3 region. </br>[--access-key-id] TEXT: Specify the S3 Access Key ID. </br>[--secret-access-key] TEXT: Specify the S3 Secret Access Key. </br>[--timeout] Restore job timeout. Default 600 (seg). </br>[--auto-accept] Automatically accept the clone operation without prompting. Recommended: </br>agility backup s3 clone </br> </br> Complete: </br>agility backup s3 clone --bucket-name=my-bucket --endpoint=s3.us-east-1.amazonaws.com --path=/backups-old --access-key-id=XXXX --secret-access-key=YYYYY --region=us-east-1
create Create a new backup. [--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. </br>[--full] Perform a full backup. Default behavior if neither --full nor --diff is specified. </br>[--diff] Perform a differential (delta) backup. agility backup s3 create
restore Restore DB from a S3 bucket backup. [--namespace] TEXT: Namespace in which AGILITY is installed. Default is ‘agility’. </br>[--time] TEXT: Point-in-Time Recovery (PITR) to restore the database to. Format: ‘YYYY-MM-DD HH:mm:ss-TZ’. </br>[--auto-accept] Automatically accept the restore operation without prompting. agility backup s3 restore
status Show the available backups status. [--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. </br>[--debug] Reveals sensitive information. agility backup s3 status
settings Configure S3 bucket backup settings. * see below  

Sub Command: settings

Configure S3 bucket backup settings.

Sub Command Description Options Example
apply Apply S3 bucket backups settings. [--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. </br>[--bucket-name] TEXT: Specify the S3 bucket name. </br>[--endpoint] TEXT: Specify the S3 endpoint. </br>[--path] TEXT: Specify the S3 path. </br>[--region] TEXT: Specify the S3 region. </br>[--retention-count] INTEGER: Specify the full backups retention count. </br>[--full-schedule] TEXT: Specify the full backup schedule. </br>[--differential-schedule] TEXT: Specify the differential backup schedule. </br>[--access-key-id] TEXT: Specify the S3 Access Key ID. </br>[--secret-access-key] TEXT: Specify the S3 Secret Access Key. </br>[--auto-accept] Automatically accept the restore operation without prompting. Recommended: </br>agility backup s3 settings apply </br> </br> Complete: </br>agility backup s3 settings apply --bucket-name=my-bucket --retention-count=10 --full-schedule="0 0 * * *" --differential-schedule="0 2-22/12 * * *" --endpoint=s3.us-east-1.amazonaws.com --path=/backups --access-key-id=XXXX --secret-access-key=YYYYY --region=us-east-1
delete Delete the existing backup settings. [--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. </br>[--auto-accept] Automatically accept the delete operation without prompting. agility backup s3 settings delete
list List S3 bucket backup settings. [--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. </br>[--sensitive] Reveals sensitive information. agility backup s3 settings list

Command: diagnostics

Diagnose and troubleshoot your AGILITY instance.

Sub Command Description Options Example
collect Generate a diagnostics report and optionally upload it to B-Yond storage. [--local]: Generate the report locally without uploading. </br>[--namespace] TEXT: Namespace in which AGILITY is installed. Default is ‘agility’. agility diagnostics collect
run Execute diagnostics checks. [--namespace] TEXT: Namespace in which AGILITY is installed. Default is ‘agility’. agility diagnostics run

Command: cv

Manage AGILITY ContinuousValidation instance.

Sub Command: settings

Manage AGILITY ContinuousValidation settings.

Sub Command Description Options Example
description Show AGILITY setting descriptions. [--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. </br>[--cv] TEXT: ContinuousValidation AGILITY definition. Default is ‘agility’. </br>[--auto-accept] Auto accept all the questions (y). </br>[--help] Show this message and exit. agility cv settings description
set Set value to AGILITY settings. [--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. </br>[--cv] TEXT: ContinuousValidation AGILITY definition. Default is ‘agility’. </br>[--auto-accept] Auto accept all the questions (y). </br>[--help] Show this message and exit. agility cv settings set continuousClassification true
status Show current AGILITY setting values. [--namespace] TEXT: Namespace in which agility is installed. Default is ‘agility’. </br>[--cv] TEXT: ContinuousValidation AGILITY definition. Default is ‘agility’. </br>[--auto-accept] Auto accept all the questions (y). </br>[--help] Show this message and exit. agility cv settings status

Command: license

Manage AGILITY license.

Command Description Options Example
upload Upload AGILITY license. --file TEXT: AGILITY license file path.</br> --text TEXT: AGILITY license content as text.</br> [--namespace] TEXT: Namespace in which AGILITY is installed. Default is ‘agility’. agility license upload --file agility.lic
status Get AGILITY license status. [--namespace] TEXT: Namespace in which AGILITY is installed. Default is ‘agility’. agility license status

Command: ingress

Manage ingress settings.

Sub Command: tls

Manage TLS configuration.

Sub Command Description Options Example
set Set Ingress TLS for the specified host --host TEXT: Specify the host for TLS configuration (required).</br>--cert TEXT: Specify the certificate filename (required).</br>--key TEXT: Specify the key filename (required).</br>[--agility-namespace] TEXT: Namespace in which agility is installed. Default ‘agility’.</br>[--monitoring-namespace] TEXT: Namespace in which monitoring is installed. Default is ‘monitoring’. agility ingress tls set --host example.com --cert tls.crt --key tls.key
reset Reset ingress configuration   agility ingress tls reset

Command: k3s

Manage k3s configuration.

Sub Command Description Options Example
configure Configure k3s kubelet arguments and restart k3s --serialize-image-pulls/--no-serialize-image-pulls: Enable/disable serial image pulls to prevent overwhelming the container registry agility k3s configure --serialize-image-pulls

Command: monitoring

Manage AGILITY Monitoring Stack.

Sub Command Description Options Example
install Install or upgrade AGILITY Monitoring Stack. [--version]: Specify the version to install/upgrade. Default 1.0.8.</br>[--namespace] TEXT: Namespace in which monitoring is installed. Default is ‘monitoring’. agility monitoring install
reset Reset alert manager configuration.   agility monitoring reset
set Configure Alert manager notifications.   agility monitoring install
show Show current alert manager configuration.   agility monitoring show
uninstall Uninstall AGILITY Monitoring Stack. [--namespace] TEXT: Namespace in which monitoring is installed. Default is ‘monitoring’.</br>[--auto-accept]: Auto accept all the questions (y). (default: False) agility monitoring uninstall

Sub Command set

Anonymous usage data collection to B-Yond.

Sub Command Description Options Example
both Configure email and pagerduty notifications for Alert manager. [--email-from] TEXT: Specify the adddress from email will come. </br> [--email-to]: Specify the adddress where email will be sent to. </br> [--smarthost]: Specify the smarthost for email service. </br> [--auth-password]: Specify the auth password for smarthost service. </br> [--auth-username]: Specify the user for smarthost service. </br> [--require-tls]: Enable TLS if required. </br> [--send-resolved]: Send resolved alerts notifications. </br> [--namespace] TEXT: Namespace in which monitoring is installed. Default is ‘monitoring’ agility monitoring both --pager-duty-service-key=pagerduty-key --pager-duty-url=http://pagerduty-url email --email-from=origin@domain.com --email-to=destiny@domain.com
email Configure email notifications for Alert manager. [--email-from] TEXT: Specify the adddress from email will come. </br> [--email-to]: Specify the adddress where email will be sent to. </br> [--smarthost]: Specify the smarthost for email service. </br> [--auth-password]: Specify the auth password for smarthost service. </br> [--auth-username]: Specify the user for smarthost service. </br> [--require-tls]: Enable TLS if required. </br> [--send-resolved]: Send resolved alerts notifications. </br> [--namespace] TEXT: Namespace in which monitoring is installed. Default is ‘monitoring’ agility monitoring set email --email-from=origin@domain.com --email-to=destiny@domain.com
pagerduty Configure pager duty notifications for Alert manager. [--pager-duty-service-key] TEXT: Specify Pager duty service key.</br> [--pager-duty-url] TEXT: Specify the pager duty url. </br> [--namespace] TEXT: Namespace in which monitoring is installed. Default is ‘monitoring’ agility monitoring set pagerduty --pager-duty-service-key=pagerduty-key --pager-duty-url=http://pagerduty-url

For the non cli (manual Helm) installation details please refer to AGILITY Monitoring

Command: proxy

Manage proxy configuration.

Sub Command Description Options Example
set Set the proxy configuration. --http-proxy: Specify the HTTP proxy (required).</br>--https-proxy: Specify the HTTPS proxy (required).</br>[--no-proxy]: Specify the hosts to exclude from the proxy. </br>[--namespace] TEXT: Namespace in which AGILITY is installed. Default is ‘agility’. </br>[--cv] TEXT: ContinuosValidation (default: agility) agility proxy set --http-proxy http://proxy.example.com --https-proxy https://proxy.example.com --no-proxy localhost,127.0.0.1
reset Remove the proxy configuration. [--namespace] TEXT: Namespace in which AGILITY is installed. Default is ‘agility’. </br>[--cv] TEXT: ContinuosValidation (default: agility) agility proxy reset

Command: sftp

Manage SFTP configuration.

Sub Command Description Options Example
create Create a new SFTP configuration.   agility sftp create
update Update existing SFTP configuration.   agility sftp update
list List existing SFTP configurations.   agility sftp list
remove Remove the SFTP configuration. --remove-data: Also delete uploaded files and directories. agility sftp remove --remove-data

Command: telemetry

Manage telemetry settings.

Sub Command local

Local monitoring (agility-monitoring) stack telemetry data.

Sub Command Description Options Example
enable Enable local usage data collection. [--agility-namespace] TEXT: Namespace in which AGILITY is installed (default: agility).</br>[--cv] TEXT: ContinuosValidation (default: agility)</br>[--monitoring-namespace] TEXT: Namespace in which monitoring is installed (default: monitoring).</br>[--auto-accept]: Auto accept all the questions (y). (default: False) agility telemetry local enable --auto-accept
disable Disable local usage data collection. [--agility-namespace] TEXT: Namespace in which AGILITY is installed (default: agility).</br>[--cv] TEXT: ContinuosValidation (default: agility)</br>[--monitoring-namespace] TEXT: Namespace in which monitoring is installed (default: monitoring).</br>[--auto-accept]: Auto accept all the questions (y). (default: False) agility telemetry local disable --auto-accept
status Show local usage data collection details. [--agility-namespace] TEXT: Namespace in which AGILITY is installed (default: agility).</br>[--cv] TEXT: ContinuosValidation (default: agility)</br>[--monitoring-namespace] TEXT: Namespace in which monitoring is installed (default: monitoring).</br>[--auto-accept]: Auto accept all the questions (y). (default: False) agility telemetry local status

Sub Command remote

Anonymous usage data collection to B-Yond.

Sub Command Description Options Example
enable Enable anonymous usage data collection. [--namespace] TEXT: Namespace in which AGILITY is installed (default: agility).</br>[--cv] TEXT: ContinuosValidation (default: agility)</br>[--auto-accept]: Auto accept all the questions (y). (default: False). agility telemetry remote enable --auto-accept
disable Disable anonymous usage data collection. [--namespace] TEXT: Namespace in which AGILITY is installed (default: agility).</br>[--cv] TEXT: ContinuosValidation (default: agility)</br>[--auto-accept]: Auto accept all the questions (y). (default: False) agility telemetry remote disable --auto-accept
status Show anonymous usage data collection details. [--namespace] TEXT: Namespace in which AGILITY is installed (default: agility).</br>[--cv] TEXT: ContinuosValidation (default: agility)</br>[--auto-accept]: Auto accept all the questions (y). (default: False) agility telemetry remote status

Sub Command customer

Enables a customer to route Agility data to a compliant Open Telemetry collector.

Sub Command Description Options Example
enable Enable data collection to customer open telemetry collector. [--namespace] TEXT: Namespace in which AGILITY is installed (default: agility)</br>[--cv] TEXT: ContinuosValidation (default: agility)</br>--endpoint TEXT: Endpoint of the OpenTelemetry Collector.</br>--port TEXT Port of the OpenTelemetry Collector.</br>--no_tls Do not setup TLS. </br>--tls_key TEXT: TLS key path. </br> --tls_cert TEXT: TLS cert path. </br>--tls_ca TEXT: TLS ca path (optional).  
disable Disable data collection to customer open telemetry collector. [--namespace] TEXT: Namespace in which AGILITY is installed (default: agility).</br>[--cv] TEXT: ContinuosValidation (default: agility) </br> --auto-accept Auto accept all the questions (y). agility telemetry customer disable --auto-accept
status Show status of data collection to customer open telemetry collector. [--namespace] TEXT: Namespace in which AGILITY is installed (default: agility).</br>[--cv] TEXT: ContinuosValidation (default: agility)</br> agility telemetry customer status

Sub Command syslog

Enables a syslog exporter to to route Agility logs to a compliant Syslog receiver.

Sub Command Description Options Example
enable Enable log collection to an external syslog receiver. [--namespace] TEXT: Namespace in which AGILITY is installed (default: agility)</br>[--cv] TEXT: ContinuosValidation (default: agility)</br>--endpoint TEXT Endpoint of the Syslog receiver.</br>--port TEXT Port of the Syslog receiver.</br> --protocol TEXT Protocol (rfc5424 or rfc3164) of the syslog endpoint. Default ‘rfc5424’ agility telemetry syslog enable --endpoint localhost --port 514 --protocol rfc5424
disable Disable log collection to an external syslog receiver. [--namespace] TEXT: Namespace in which AGILITY is installed (default: agility).</br>[--cv] TEXT: ContinuosValidation (default: agility)</br> agility telemetry syslog disable
status Show status log collection to an external syslog receiver. [--namespace] TEXT: Namespace in which AGILITY is installed (default: agility).</br>[--cv] TEXT: ContinuosValidation (default: agility)</br> agility telemetry syslog status

Command: toolbox

Manage AGILITY Toolbox component.

Sub Command Description Options Example
install Install or upgrade AGILITY Toolbox. --version TEXT: Specify the version to install/upgrade. If not set, installs the latest available.
--namespace TEXT: Namespace in which toolbox is installed. Default ‘agility’.
--all: Enable all components.
--no-toolkit: Disable the toolkit component.
--no-jupyterhub: Disable the JupyterHub component.
--no-wireshark: Disable the Wireshark component.		 agility toolbox install --all
uninstall Uninstall AGILITY Toolbox. --namespace TEXT: Namespace in which toolbox is installed. Default ‘agility’.
--auto-accept: Automatically accept the uninstall operation without prompting.		 agility toolbox uninstall --namespace agility --auto-accept

Command: upgrade

Upgrade AGILITY components.

Sub Command Description Options Example
agility Upgrade the AGILITY component. --version TEXT: Specify the version for upgrade (required).</br>[--namespace] TEXT: Namespace in which AGILITY is installed. Default is ‘agility’. . agility upgrade agility --version 3.86.3
agility-services Upgrade the AGILITY Services component. --version TEXT: Specify the version for upgrade (required).</br>[--namespace] TEXT: Namespace in which AGILITY is installed. Default is ‘agility’. . agility upgrade agility-services --version 3.86.3
agility-system Upgrade the AGILITY System component. --version TEXT: Specify the version for upgrade (required).</br>[--namespace] TEXT: Namespace for AGILITY System (default: kube-system) (default: kube-system). agility upgrade agility-system --version 3.86.3
cli Upgrade AGILITY CLI --version TEXT: Specify the version for upgrade (required). agility upgrade cli --version 3.86.3
all Upgrade all AGILITY components with the same version (except the database). --all-version TEXT: Specify the version for upgrade. All components with the same version (required).</br>[--namespace] TEXT: Namespace for AGILITY and AGILITY Services (default: agility)</br>--sys-namespace TEXT: Namespace for AGILITY System (default: kube-system).</br>[--skip-version-check]: Skip automatic version verification after upgrade (default: False) agility upgrade all --all-version 3.86.3 --namespace agility --sys-namespace kube-system</br>agility upgrade all --all-version 3.86.3 --skip-version-check
database Upgrade PostgreSQL version. --version TEXT: Specify the PostgreSQL major version to upgrade (required).</br>[--namespace] TEXT: Namespace for AGILITY (default: agility)</br>[--auto-accept]: Auto accept all the questions (y). (default: False)</br>[--force]: Force upgrade, ignoring some restrictions. (default: False) agility upgrade database --version 16

Version Verification

The agility and all upgrade commands now include automatic version verification to ensure deployments are running with the correct versions after Helm chart updates. This feature:

The verification process automatically discovers AGILITY components and monitors their version rollout for up to 15 minutes by default. Note that the timeout is a maximum monitoring period - pods may still become ready after this time, especially during initial installations when container images need to be downloaded.

Command: version

Show AGILITY components version information.

Command Description Options Example
version Display version information for all components [--namespace] TEXT: Namespace in which AGILITY is installed. Default is ‘agility’. agility version

This command displays comprehensive version information including: