NAME

supctl - Avassa environment command line interface

SYNOPSIS

supctl [OPTIONS] [COMMAND [COMMAND-OPTIONS]] [ARG...]

DESCRIPTION

supctl is used to interact with Avassa environments.

In order to interact with an Avassa environment, the command do login or do oidc-login must be given. If this command is successful, supctl saves the returned token together with the user name and host information in a profile directory. See the CONFIGURATION and PROFILES sections for more information.

CONFIGURATION

Configuration files are stored in $HOME/.config/supctl unless specified otherwise by $XDG_CONFIG_HOME. There is normally no need to manually edit the configuration. supctl can maintain connection profiles for multiple Avassa environments. Each profile contains the host information and the user credentials needed to interact with one environment. If no profiles exist, one will automatically be created the first time you log in to an environment. See the section PROFILES for further information on how to manage profiles.

OPTIONS

-v, --verbose: verbose output
-n HOSTNAME, --host HOSTNAME: connect to HOSTNAME
-p PORT, --port PORT: connect to supd on PORT
-c DIR, --config-dir DIR: store configuration in DIR
-d DIR, --profile-dir DIR: read and store profile in DIR
-P PROFILE, --profile PROFILE: Use profile PROFILE
-e ETAG, --etag ETAG: send ETAG in If-Match header
-j, --json: get or send JSON
-T, --table: get or send JSON, format output as CSV
-U, --csv: get or send JSON, format output as table
-y, --yaml: get or send YAML
-f, --fail-silently: fail silently on error
-q PARAMS, --query-params PARAMS: supply query params
-r, --use-root-token: authenticate using root token
-S, --use-system-token: authenticate using system token
-t TOKEN, --token TOKEN: authenticate using TOKEN
-F FILE, --token-file FILE: authenticate using token contained in FILE
-k, --insecure: do not verify server certificate
-C CACERTFILE, --ca-cert CACERTFILE: load CA certificate from CACERTFILE
-H HOSTNAME, --server-hostname HOSTNAME: use HOSTNAME as TLS Server Name Indication
-w, --no-warnings: silence all warnings
-V, --version: print version info and exit
-h, --help: show this help message and exit

COMMANDS

completion [bash|zsh]: Print sourceable bash/zsh completion script. If no parameter is given, a guess will be made based on $SHELL.
show [-s|--site SITE] [-c|--config] [PATH]: Show operational state, or current configuration if --config is given, at the given PATH, or all operational state or current configuration if PATH is not given. If SITE is given, show the operational state or current configuration on the given site.
list [-s|--site SITE] [-c|--config] [PATH]: Show the keys (and nothing else) of the list at the given PATH. If SITE is given, show the keys on the given site.
count [-s|--site SITE] [-c|--config] [PATH]: Return the number of elements in the list at the given PATH. If SITE is given, return count from the given site.
create PATH: Create new configuration at the given PATH.
replace PATH: Replace existing configuration at the given PATH.
delete PATH: Delete existing configuration at the given PATH.
merge PATH: Merge the configuration at the given PATH with new data.
patch PATH: Patch the configuration at the given PATH using JSON Patch.
edit PATH: Open $EDITOR with the configuration at the given PATH, and put it back when the editor is closed.
do [-s|--site SITE] PATH: Invoke an operation at the given PATH. If SITE is given, the operation is invoked at the given site.
profile create NAME: Create a new profile called NAME and set it as the active one. A new profile is just an empty directory, the initial configuration is created when you log in to an environment.
profile delete NAME: Delete the profile called NAME.
profile set NAME: Activate the profile called NAME for the current shell session.
profile unset: Deactivate the profile that is currently active (typically to prevent accidental use).
profile set-default NAME: Choose a profile to use as the default when no other profile is active.
profile unset-default: Remove the current default profile setting.
profile list: List all available profiles. The active one will always appear first in the list.
update: Download the latest supctl client from the Control Tower. There is usually no need to run this as supctl will automatically check for and download updates. The downloaded client is stored in the active profile and is used when interacting with this particular Control Tower.

PROFILES

Profiles allow supctl to easily connect to many different environments. Initially there are no profiles configured at all. You can create a profile explicitly by running supctl profile create NAME, or you can just log in to your environment and supctl will create a profile for you. In the latter case, the hostname of your environment will be used as the profile name.

Once your profile is created and populated, subsequent calls to supctl will use the credentials in your profile directory to connect to your Avassa environment. To choose a different profile, use the command supctl profile set NAME. Profile selection is local to your shell session. This means that you need to select a profile each time you open a new terminal, but subshells and scripts will inherit the profile you have selected.

If you typically only use one profile, you can set it as the default profile, and it will be used if no other profile is selected. See the set-default command above.

The current profile directory can be overridden using the environment variable SUPCTL_PROFILE_DIR or using the -d/--profile-dir option. If both are specified, the option given on the command line takes priority.

ENVIRONMENT VARIABLES

SUPCTL_CONFIG_DIR: Directory where config is stored. Default is $XDG_CONFIG_HOME/supctl or, failing that, $HOME/.config/supctl.
SUPCTL_PROFILE_DIR: Profile directory to use. Overrides the otherwise active profile.
SUPCTL_CDIR: Deprecated. Same functionality as SUPCTL_PROFILE_DIR.
SUPCTL_PORT: Port to connect to. Overrides the port in the active profile.
SUPCTL_LOGFILE: Enable logging and store logs in this file.
SUPCTL_LOGLEVEL: One of DEBUG, INFO, WARNING, ERROR, CRITICAL. Default is DEBUG. Used only if SUPCTL_LOGFILE is set.
SUPCTL_NOBROWSER: If set, supctl will not attempt to open a browser window for oidc-login.
SSLKEYLOGFILE: If set, supctl will store its TLS secrets in this file, allowing tools like Wireshark to use it for analyzing traffic. Do not set unless you know what you are doing.

EXAMPLES

Connecting to a new environment:

supctl --host www.example.com do login joe@example.com

You will be prompted for a password. If the login is successful, the active profile will be updated with the credentials needed to interact with this environment. If there was no active profile, one will be created with the name www.example.com.