Creating Streams with the Command Line Interface

The Stream Machine CLI is a command line interface for interacting with it. You can find its source code and binary at github.com/streammachineio/cli

the Stream Machine portal currently provides only limited functionality. You will need to use the CLI.

The CLI is nothing more than a thin interface to the OpenApi interface. You can actually do all the CLI actions described below via the OpenApi interface. You do need an authentication token though (see below) [1].

Most of the CLI commands provide valid JSON output, so you can use them in command pipes with the excellent jq tool.

Logging in

First create an account at streammachine.io and use the email and password to log in with the CLI.

$ strm auth login
Enter your Stream Machine portal email address [hello@streammachine.io]:  ...
Please enter your Stream Machine portal password:
Succesfully logged in as hello@streammachine.io

This creates a file credentials.json in the application configuration directory [2].

You can use strm auth show to find the billingId that has been assigned to you. You need this with the client drivers.

$ strm auth show
Credentials for hello@streammachine.io
Billing id = hello0123456789
Current token valid until = 2021-01-14T16:28:16 UTC

Or if you prefer JSON:

$ strm auth show --json
{
    "email": "hello@streammachine.io",
    "billingId": "hello0123456789",
    "expiresAt": 1610641696,
    "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjVmOTcxMm....",
    "refreshToken": "AOvuKvQjJ3VzF12-5qo7crLryG9fz5979Zss...."
}

Note that the CLI has command completion. Add source <(strm --generate-completion bash|zsh|fish) to your shell configuration file [3]

Listing streams

Streams can be listed and will be shown as JSON formatted.

When listing streams, the clientSecret is not shown. The secret is only shown once, which is upon creation of the stream. 
$ strm streams list
[
  {
    "name": "stream-machine",
    "tags": [],
    "credentials": {
      "clientId": "3p5hau1zunkyba0..."
    }
  }
]

Creating a stream

A stream can be created as follows [4]:

$ strm streams create stream-machine
{
    "name": "stream-machine",
    "tags": [],
    "credentials": {
        "clientId": "3p5hau1zunkyba0...",
        "clientSecret": "Z^H^s_Xdm!h9W..."
    }
}

The billingId, clientId and clientSecret triplet is what identifies your stream when you send data to Stream Machine. Stream Machine uses the OAuth 2.0 client credentials flow to generate a bearer token that needs to be provided with each http request. Our drivers have tooling to create and refresh these tokens, but nothing precludes you from creating the headers by hand (see the chapter about sending via curl to do this manually).

So with this information, you have enough information to start sending data to in.strm.services/event. With the same credentials you can connect to the egress endpoint with a websocket client to receive the events as you send them.

Creating decrypted streams

If you want to have Stream Machine decrypt data with certain consent levels, you need to create an output stream.

$ strm outputs create --help
Usage: strm outputs create [OPTIONS] name output-name

  Create a new output

Options:
  -cl, --consent-level INT         The consent levels for this
                                   output.
  -clt, --consent-level-type [GRANULAR|CUMULATIVE]
  -d, --description TEXT           Optional description to describe
                                   the purpose of this output.
  -t, --tag TEXT                   Optional tag for this output.
  -dn, --decrypter-name TEXT       Name for the decrypter that will
                                   produce this output.
  -h, --help                       Show this message and exit

Arguments:
  name         The name of the stream for which an output is
               created.
  output-name  The name of the output that is created.
decrypter-name currently has no purpose, but it’s reserved for future use. The default value can be used for now.

So let’s create one, with two consent levels, and a granular consent level type interpretation.

$ strm outputs create stream-machine level0-1 -cl 0 -cl 1  -clt GRANULAR
{
  "linkedStream": "stream-machine",
  "name": "level0-1",
  "tags": [],
  "credentials": {
    "clientId": "wvs5pkr6q48...",
    "clientSecret": "8IhY!HnK(...#"
  },
  "consentLevelType": "GRANULAR",
  "consentLevels": [ 0, 1 ],
  "decrypterName": "default"
}

So this output stream named level0-1 captures data from encrypted stream stream-machine (for the current billingId). It will drop all events that don’t at least have consent levels 0 and 1 in the event. Another way of defining decrypted streams is with consent level type cumulative. This means that the decrypted stream has just one consent level, and it will accept all events that have at least that consent level. It will decrypt PII fields up to and including the decrypted stream consent level.

Using the OpenApi User Interface

If you just try one of the calls on the Swagger page you’ll receive:

{
  "error": {
    "code": 401,
    "status": "Unauthorized",
    "message": "The request could not be authorized"
  }
}

First ask the CLI for a token: strm auth print-access-token. Paste the token into the api page. authorize button

Now you can have a look at all capabilities of the api.

1. strm auth print-access-token
2. ~/.config/stream-machine
3. ~/.bashrc or ~/.zshrc
4. tags are defined but not yet used anywhere in Stream Machine