Snowplow Tracking CLI 0.1.0 released

We are pleased to announce the first release of the Snowplow Tracking CLI! This is a command-line application (written in Golang) to make it fast and easy to send an event to Snowplow directly from the command line. You can use the app to embed Snowplow tracking directly into your shell scripts.

In the rest of this post we will cover:

1. How to install the app
2. How to use the app
3. Examples
4. Under the hood
5. Roadmap
6. Documentation and getting help

1. How to install the app

You can download the binary for Linux and Windows directly from Bintray:

• Linux 64bit binary
• Windows 32bit binary

Unzip the file and the app is called snowplowtrk.

The binary for macOS is scheduled for version 0.2.0 – (see issue #2).

2. How to use the app

The command line interface is as follows:

snowplowtrk --collector=[[COLLECTOR_DOMAIN]] --appid=[[APP_ID]] --method=[[POST|GET]] --sdjson=[[SELF_DESC_JSON]] 

or:

snowplowtrk --collector=[[COLLECTOR_DOMAIN]] --appid=[[APP_ID]] --method=[[POST|GET]] --schema=[[SCHEMA_URI]] --json=[[JSON]] 

Where:

• --collector is the domain for your Snowplow collector, e.g. snowplow-collector.acme.com
• --appid is optional (not sent if not set)
• --method is optional. It defaults to GET
• --sdjson is a self-describing JSON of the standard form { "schema": "iglu:...", "data": { ... } }
• --schema is a schema URI, most likely of the form iglu:...
• --json is a (non-self-describing) JSON, of the form { ... }
• --dbpath is optional, it allows you to set the full path to where the event database is created. It defaults to events.db in the same directory as the application

You can either send in a self-describing JSON, or pass in the constituent parts (i.e. a regular JSON plus a schema URI) and the Snowplow Tracking CLI will construct the final self-describing JSON for you.

3. Examples

Here are some examples:

$ snowplowtrk --collector snowplow-collector.acme.com --appid myappid --method POST --schema iglu:com.snowplowanalytics.snowplow/event/jsonschema/1-0-0 --json "{"hello":"world"}" 

$ snowplowtrk --collector snowplow-collector.acme.com --appid myappid --method POST --sdjson "{"schema":"iglu:com.snowplowanalytics.snowplow/event/jsonschema/1-0-0", "data":{"hello":"world"}}" 

4. Under the hood

There is no buffering in the Snowplow Tracking CLI – each event is sent as an individual payload whether GET or POST.

Under the hood, the app uses the Snowplow Golang Tracker.

The Snowplow Tracking CLI will exit once the Snowplow collector has responded. The return codes from snowplowtrk are as follows:

• 0 if the Snowplow collector responded with an OK status (2xx or 3xx)
• 4 if the Snowplow collector responded with a 4xx status
• 5 if the Snowplow collector responded with a 5xx status
• 1 for any other error

5. Roadmap

In the future, we plan to support generating events from local files of newline-delimited (ND) JSON. There is potential for the Snowplow Tracking CLI to evolve into a sophisticated logfile-to-Snowplow emitter, along similar lines to Logstash or Fluentd.

6. Documentation and getting help

This is the first release of the Snowplow Tracking CLI.

For more information, check out the project README</a>; you can read more about self-describing JSONs here.

If you have any questions or run into any problems, please raise an issue or get in touch with us through the usual channels.