The StackState CLI can be used to configure StackState, work with data and help with debugging problems. The CLI provides easy access to the functionality provided by the stackstate api. The URLs and authentication credentials are configurable. Multiple configurations can be stored for access to different instances.



  • Docker

Getting the cli

The CLI can be downloaded from using your license key.

The downloaded zip contains the following:

+-- bin
|   +-- sts
+-- conf.d
|   +-- conf.yaml.example
|   +-- VERSION
+-- templates
   +-- topology
  • sts is the cli. Put sts on your path to use it anywhere on the command line.
  • conf.yaml.example documents how to configure the url and credentials.
  • VERSION the version of the cli.
  • templates these are topology templates in a format specific to the cli.


The cli searches for configuration in conf.d/conf.yaml. You need to create this file. In this file the URLs to the sts APIs, their authentication (if any), and a client must be defined. You can copy the conf.d/conf.example.yaml file and rename it to conf.yaml to get you started. Or copy the example below.

     url: "https://???"
     ## StackState authentication. This type of authentication is exclusive to the `base_api`.
     # auth:
     #   username: "???"
     #   password: "???"
     ## HTTP basic authentication.
     # basic_auth:
     #   username: "???"
     #   password: "???"
     url: "https://???:7077"
     ## HTTP basic authentication.
       #username: "???"
       #password: "???"
     url: "https://???:7071"
     ## HTTP basic authentication.
       #username: "???"
       #password: "???"

   ## The CLI uses a client configuration to identify who is sending to the StackState instance. The client
   ## is used to send topology and/or telemetry to the receiver API.
   ## Unless the `--client` argument is passed the CLI will pick the `default` instance as configured below.
   ## Other clients follow the exact same configuration pattern as the default client. You may simply copy-paste its config and modify whatever is needed.
       api_key: "???"
       ## The name of the host that is passed to StackState when sending. Leave these values unchanged
       ## if you have no idea what to fill here.
       hostname: "hostname"
       internal_hostname: "internal_hostname"

The conf.yaml can hold multiple configurations. The example only holds a default instance. Other instances can be added on the same level as the default. To use a non default instance use sts --instance <instance_name> ...


Configuring StackState through the CLI

You can use the sts graph export and sts graph import commands to export and import different types of configuration nodes from and to StackState. To list all configuration nodes of a type call sts graph list <type>.

Some well known configuration nodes are:

  • Sync
  • TemplateFunction
  • ComponentType
  • RelationType
  • Domain
  • Layer
  • Environment
  • DataSource
  • View
  • EventHandler
  • CheckFunction
  • BaselineFunction
  • PropagationFunction
  • EventHandlerFunction
  • MappingFunction
  • IdExtractorFunction
  • ViewHealthStateConfigurationFunction

It may be handy to write configurations to disk. For example, to write all check function to disk call:

sts graph list --ids CheckFunction | xargs sts graph export --ids > mycheckfunctions.stj

To import these check functions call:

sts graph import < mycheckfunctions.stj

Inspecting data with the CLI

Data flowing through Kafka topics

Use sts topic list to list all Kafka topics active for a StackState instance. Then use sts topic show <topic> to inspect a topic.

Topology and Telemetry

To inspect both topology and telemetry a script can be executed with the sts script command.

Sending data with the CLI

You may not always want to try a new configuration on real data. First you might want to see if it works correctly with predictable data. The CLI makes it easy to send some test topology or telemetry to StackState.

  • For help on sending metrics: sts metrics send -h
  • For help on sending events: sts events send -h
  • For help on sending topology: sts topology send -h ().


To send metrics the cli provides sts metrics send <MetricName> <OptionalNumberValue> with some predefined settings. Running without any optional arguments sends one datapoint of the given value.

Using optional arguments provides a way to create historical data for a test metric.

-p gives the option to specify a time period. this can be done in weeks <num>w, days <num>d, hours <num>h, minutes <num>m and seconds <num>s. or any combination thereof. for example: -p 4w2d6h30m15s

-b provides a bandwidth between which the values will be generated. for example: -b 100-250

By default a metrics pattern is random or when a value is provided a flatline. This can be changed by using a pattern argument. The options are --linear and --baseline.

  • --linear creates a line between the values given for -b. plotted over the time given for -p.
  • --baseline creates a daily usage curve. On Saturday and Sunday the metric is much lower than on weekdays. The min and max of the curve is set by -b and the time period by -p.

To see all options that are available use sts metrics send -h.


The cli can send events using sts events send <eventName> It will send one event with the given name.


please refer to provided with the cli for detailed instructions