CLI: stac (deprecated)
StackState Self-hosted v5.1.x
Last updated
StackState Self-hosted v5.1.x
Last updated
The StackState stac
CLI provides easy access to the functionality provided by the StackState APIs. It can be used to configure StackState, work with data, automate using StackState data and help with developing StackPacks. You can configure the CLI to work with multiple instances of StackState.
stac
CLIA standalone executable is available to run the stac
CLI on and . You can also run the stac
CLI on Linux, Windows or macOS.
The steps below describe how to install the stac
CLI on Linux using the standalone executable file. If you prefer, you can run the stac
CLI .
Requirements:
Access to the StackState APIs.
Installation:
Download the Linux executable sts-cli-VERSION-linux64
from where the VERSION
is the same as the StackState version you are running. For example, download sts-cli-5.0.0-linux64
if you are running StackState v5.0.0.
Rename the downloaded file to be stac
and make it executable:
(optional) Add the file to your PATH to use stac
CLI commands from .
To configure the StackState CLI, do one of the following:
(recommended).
.
Requirements:
Access to the StackState APIs.
Installation:
Rename the downloaded file to be stac.exe
.
To configure the StackState CLI, do one of the following:
The StackState CLI can be run inside a Docker container on Linux, Windows or macOS. The ZIP archive provided contains scripts that run the CLI without needing to worry about Docker invocations.
Requirements:
Access to the StackState APIs.
Internet connection for first time run.
Installation:
The ZIP archive contains the following files:
Rename the bash and Powershell scripts in the bin
directory to use the new stac
name:
Script to run the CLI in Docker for bash: Rename from sts
to stac
.
Script to run the CLI in Docker for Powershell: Rename from sts.ps1
to stac.ps1
.
stac
CLIAfter a new installation, the stac
CLI must be configured with the API connection details for your StackState instance. If you upgraded from a previous version of the CLI, it isn't necessary to configure the CLI again, the existing CLI configuration will be used.
The standalone executable StackState CLI on Linux or Windows includes a wizard to guide you through configuration. If you installed the Docker version of the stac
CLI on macOS, Linux or Windows, the configuration file must be manually created.
If the stac
CLI was installed on Linux or Windows using a standalone executable file, the first time you run any stac
command, a configuration wizard will request the required configuration items. The wizard will then create a configuration file with the entered details and store it under the user's home directory. If a valid configuration file already exists, the stac
CLI will use this and the configuration wizard won't run.
The configuration wizard isn't available when the stac
CLI is run inside a Docker container on macOS, Linux or Windows.
Example configuration wizard:
Copy the file conf.d/conf.example.yaml
from the ZIP archive and put it in one of the following directories:
Docker:
conf.d/
- relative to the directory where the stac
CLI is run.
Linux or Windows:
conf.d/
- relative to the directory where the stac
CLI is run.
~/.stackstate/cli/
- relative to the user's home directory.
%APPDATA%/StackState/cli/
- relative to the user's home directory.
Rename the file to be conf.yaml
.
Edit the file and add:
URLs to the StackState APIs.
Client details.
The conf.yaml
configuration file for the stac
CLI can hold multiple configurations. Other StackState instances can be added on the same level as the default configuration. For example:
To use the stac
CLI with a non-default instance, specify the instance name in the stac
command:
The stac
CLI uses three StackState APIs: the Base API, the Admin API and the Receiver API. These APIs are secured differently and need to have separate authentication details provided in the stac
CLI configuration file.
StackState receives topology, telemetry and trace data via the Receiver API. If you want to push information to StackState using the stac
CLI, you will need a Receiver API key. This is the same API key used by the StackState Agent and is available from your administrator.
Base API and Admin API authentication using username/password will be deprecated.
The stac
CLI will issue a warning when username/password authentication is used for the Base API and the Admin API. It's recommended to switch to token based authentication as described below.
The stac
CLI authenticates against the Base API and the Admin API using a unique API token auto-generated for your StackState user account. The same API token should be entered in the stac
CLI configuration file for both the Base API and the Admin API.
The Base API is used for most operations. All users have access to this API, although the available operations will be restricted in accordance with the permissions assigned to each role.
The Admin API is used for some operations that affect the global configuration of StackState, such as the configuration of StackGraph's retention. Only users with the permission access-admin-api
will have access to the Admin API and the associated operations.
You can find your API token in the StackState UI, go to Main menu > CLI.
Follow the steps below to upgrade an installed version of the CLI. Note that it isn't necessary to configure the CLI again after the upgraded version is installed, the existing CLI configuration will be used.
Delete the existing CLI files:
Windows and Linux:
Version 4.6 and older: The file was downloaded as sts-cli-VERSION-linux64
and renamed to sts
.
Version 5.0 and above: The file was downloaded as sts-cli-VERSION-linux64
and renamed to stac
.
Docker:
The zip archive was downloaded as sts-cli-VERSION.zip
and extracted. All files extracted from the zip archive should be removed.
Follow the instructions to download and install the upgraded CLI:
It isn't necessary to configure the CLI again, the existing CLI configuration will be used.
To uninstall an installed version of the stac
CLI:
Delete the old CLI files:
Linux or Windows:
Version 4.6 and older: The file was downloaded as sts-cli-VERSION-linux64
and renamed to sts
.
Version 5.0 and above: The file was downloaded as sts-cli-VERSION-linux64
and renamed to stac
.
Docker:
The zip archive was downloaded as sts-cli-VERSION.zip
and extracted. All files extracted from the zip archive should be removed.
Delete any stac
CLI configuration files:
Linux or Windows:
conf.d/conf.yaml
- relative to the directory where the CLI is run.
~/.stackstate/cli/conf.yaml
- relative to the user's home directory.
%APPDATA%/StackState/cli/conf.yaml
- relative to the user's home directory.
Docker:
conf.d/conf.yaml
- relative to the directory where the CLI would run. Should have been removed together with the old CLI files in step 1.
If you added the CLI file or directory to your path (an optional installation step), remove it.
stac
CLIFor details on how to work with the StackState CLI, refer to the help provided in the CLI.
The stac
CLI can be used to check your license validity and update a license key when needed, for example, in case of expiration.
The steps below describe how to install the StackState CLI on Windows using the standalone executable file. If you prefer, you can run the stac
CLI .
Download the executable sts-cli-VERSION-windows.exe
from where the VERSION
is the same as the StackState version you are running. For example, download sts-cli-5.0.0-windows.exe
if you are running StackState v5.0.0.
(optional) Add the file to your PATH to use stac
CLI commands from .
(recommended).
.
.
Download the ZIP file sts-cli-VERSION.zip
from where the VERSION
is the same as the StackState version you are running. For example, download sts-cli-5.0.0.zip
if you are running StackState v5.0.0.
(optional) Add the bin
directory to your PATH to use stac
CLI commands from .
To configure the StackState CLI, .
Linux or Windows install (standalone executable): .
macOS (Docker): .
To configure the stac
CLI, you will need your .
Follow the steps below to manually create or edit the stac
CLI configuration file. A Docker install of the stac
CLI must be manually configured. For a Linux or Windows install using a standalone executable file, you can also use the (preferred).
Download the ZIP file sts-cli-VERSION.zip
from . If you ran the Docker install, you can skip this step and use the ZIP archive you already downloaded.
Any required authentication details for the APIs. The base_api
API has support for . You can copy your private API Token from the CLI page in the StackState UI.
➡️
If you are using a custom tool instead of the CLI, you can authenticate with the same used by the CLI. For example, this can be done by including the following header in a curl request: