StackState version 4.3 (EOL)
🚀
Setup
👤
Use
StackState CLI
Install the StackState CLI
This page describes StackState version 4.3.
The StackState 4.3 version range is End of Life (EOL) and no longer supported. We encourage customers still running the 4.3 version range to upgrade to a more recent release.
Overview
The StackState 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.
Install the StackState CLI
A standalone executable is available to run the StackState CLI on Linux and Windows. You can also run the CLI inside a Docker container on Linux, Windows or MacOS.
Linux install
The steps below describe how to install the StackState CLI on Linux using the standalone executable file. If you prefer, you can run the CLI inside a Docker container .
Requirements:
- Access to the StackState APIs.
Installation:
- 1.
- 2.Rename the downloaded file to be
stsand make it executable:1mv sts-cli-VERSION-linux64 sts2chmod +x stsCopied! - 3.(optional) Add the file to your PATH to use StackState CLI commands from anywhere on the command line.
- 4.To configure the StackState CLI, do one of the following:
Windows install
The steps below describe how to install the StackState CLI on Windows using the standalone executable file. If you prefer, you can run the CLI inside a Docker container .
Requirements:
- Access to the StackState APIs.
Installation:
- 1.
- 2.Rename the downloaded file to be
sts.exe. - 3.(optional) Add the file to your PATH to use StackState CLI commands from anywhere on the command line.
- 4.To configure the StackState CLI, do one of the following:
Docker install (Mac, Linux, Windows)
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:
- 1.The ZIP archive contains the following files:1.2+-- bin3| +-- sts # Script to run the CLI in Docker for bash4| +-- sts.ps1 # Script to run the CLI in Docker for Powershell5+-- conf.d6| +-- conf.yaml.example # Example CLI configuration7| +-- VERSION # The CLI version to retrieve from Docker hub8+-- templates9| +-- topology # Topology templates in a format specific to the CLI10+-- release_notes.md # Changelog of the CLI11+-- usage.md # How to configure and use this packageCopied!
- 2.(optional) Add the
bindirectory to your PATH to use StackState CLI commands from anywhere on the command line. - 3.
Configure the StackState CLI
After installation, the StackState CLI must be configured with the API connection details for your StackState instance. If you installed the standalone executable StackState CLI on Linux or Windows, a wizard is available to guide you through configuration. If you installed the Docker version of the StackState CLI on Mac, Linux or Windows, the configuration file must be manually created.
Configuration wizard (Linux and Windows install)
If the StackState CLI was installed on Linux or Windows using a standalone executable file, the first time you run any
sts 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 StackState CLI will use this and the configuration wizard will not run.The configuration wizard is not available when the CLI is run inside a Docker container on Mac OS, Linux or Windows.
Example configuration wizard:
1
$ sts graph list-types
2
No config was found. Would you like to configure the CLI using this wizard? (Y/n): Y
3
4
StackState URL: https://company.stackstate.com/
5
Your API token (see https://company.stackstate.com/#/cli ):
6
Admin API URL (default: https://company.stackstate.com/admin):
7
Receiver API URL (default: https://company.stackstate.com/receiver):
8
Receiver API key (default: API_KEY):
9
Hostname used for receiver ingestion via the CLI (default: mycli):
10
11
Thank you! Config file saved to: /Users/myuser/.stackstate/cli/conf.yaml
Copied!
Manual configuration (Docker)
The CLI configuration file can be manually created or edited using the steps below. This is required for a Docker install and optional for a Linux or Windows install using a standalone executable file.
- 1.Download the ZIP file
sts-cli-VERSION.zipfrom https://download.stackstate.com. If you ran the Docker install, you can skip this step and use the ZIP archive you already downloaded. - 2.Copy the file
conf.d/conf.example.yamlfrom the ZIP archive and put it in one of the following directories:- Docker:
conf.d/- relative to the directory where the CLI is run.
- Linux or Windows:
conf.d/- relative to the directory where the CLI is run.~/.stackstate/cli/- relative to the user's home directory.%APPDATA%/StackState/cli/- relative to the user's home directory.
- 3.Rename the file to be
conf.yaml. - 4.Edit the file and add:
- URLs to the StackState APIs.
- Any required authentication details for the APIs. The
base_apiAPI has support for API tokens. You can copy your private API Token from the CLI page in the StackState UI. - Client details.
Example conf.yaml
1
## The CLI uses an instance of StackState for all its commands.
2
## Unless the `--instance` argument is passed the CLI will pick the `default` instance as configured below.
3
## Other instances follow the exact same configuration pattern as the instance below.
4
instances:
5
default:
6
base_api:
7
url: "https://stackstate.mycompany.com"
8
# Get the api token from the user interface, see https://stackstate.mycompany.com/#/cli
9
apitoken_auth:
10
token: '???'
11
## HTTP basic authentication.
12
#basic_auth:
13
#username: '???'
14
#password: '???'
15
receiver_api:
16
url: "https://stackstate.mycompany.com/receiver"
17
## HTTP basic authentication.
18
#basic_auth:
19
#username: '???'
20
#password: '???'
21
admin_api:
22
url: "https://stackstate.mycompany.com/admin"
23
# Get the api token from the user interface, see https://stackstate.mycompany.com/#/cli
24
apitoken_auth:
25
token: '???'
26
## HTTP basic authentication.
27
#basic_auth:
28
#username: '???'
29
#password: '???'
30
31
## The CLI uses a client configuration to identify who is sending to the StackState instance. The client
32
## is used to send topology and/or telemetry to the receiver API.
33
##
34
## Unless the `--client` argument is passed the CLI will pick the `default` instance as configured below.
35
## Other clients follow the exact same configuration pattern as the default client. You may simply copy-paste its config and modify whatever is needed.
36
clients:
37
default:
38
api_key: "API_KEY"
39
## The name of the host that is passed to StackState when sending. Leave these values unchanged
40
## if you have no idea what to fill here.
41
hostname: "hostname"
42
internal_hostname: "internal_hostname"
Copied!
Add multiple configurations
The
conf.yaml CLI configuration file can hold multiple configurations. Other StackState instances can be added on the same level as the default configuration. For example:1
instances:
2
default:
3
base_api:
4
...
5
admin_api:
6
...
7
receiver_api:
8
...
9
clients:
10
...
11
Preproduction:
12
base_api:
13
...
14
clients:
15
...
Copied!
To use the StackState CLI with a non-default instance, specify the instance name in the sts command:
1
sts --instance <instance_name> ...
Copied!
Authentication
The StackState CLI exposes a number of APIs: the Base API, the Admin API and the Receiver API. StackState receives topology, telemetry and trace data via the Receiver API. All other operations happen via the Base API and the Admin API. These APIs are secured differently.
API key - Receiver API
StackState receives topology, telemetry and trace data via the Receiver API. If you want to push information to StackState using the CLI, you will need to provide a Receiver API key. This is the same API key that is used by the StackState Agent, which is configured by your administrator.
API token - Base API and Admin API
Base API and Admin API authentication using username/password will be deprecated.
The CLI will issue a warning when username/password authentication is used for the Base API and the Admin API. It is recommended to switch to token based authentication.
Base API and Admin API access are required for all operations other than sending topology, telemetry or traces to StackState. The StackState CLI authenticates against the Base API and the Admin API using a unique API token that is auto-generated for your user account.
You can find your API token in the StackState UI on the page Main menu > CLI.
The Base API is used for most operations. The Admin API is used for some operations that affect the global configuration of StackState, such as the configuration of StackGraph's retention. To use the Admin API, you need the
access-admin-api StackState permission.Use the StackState CLI
For details on how to work with the StackState CLI, see the CLI reference guide or refer to the help provided in the CLI.
1
sts --help
Copied!
Last modified 3mo ago
Copy link
Contents
Overview
Install the StackState CLI
Linux install
Windows install
Docker install (Mac, Linux, Windows)
Configure the StackState CLI
Configuration wizard (Linux and Windows install)
Manual configuration (Docker)
Add multiple configurations
Authentication
API key - Receiver API
API token - Base API and Admin API
Use the StackState CLI