keen-cli

A command line interface for the Keen IO analytics API.

Installation

keen-cli is built with Ruby, so you'll need a working Ruby 1.9+ environment to use it. You can find Ruby installation instructions here.

Install the gem:

$ gem install keen-cli

Verify the keen command is in your path by running it:

Commands:
  keen events:add         # Add an event
  keen help [COMMAND]     # Describe available commands or one specific command
  keen project:open       # Open the current project
  keen project:show       # Show the current project
  keen project:workbench  # Open the current project's workbench
  keen queries:run        # Run a query
  keen version            # Print the keen-cli version

You should see information about available commands.

If keen can't be found there might be an issue with your Ruby installation. If you're using rbenv try running rbenv rehash after installation.

Environment configuration

Most keen-cli functions require the presence of a project and one or more API keys to do meaningful actions. By default, keen-cli attempts to find these in the process environment or a .env file in the current directory. This is the same heuristic that keen-gem uses.

An example .env file looks like this:

KEEN_PROJECT_ID=aaaaaaaaaaaaaaa
KEEN_MASTER_KEY=xxxxxxxxxxxxxxx
KEEN_WRITE_KEY=yyyyyyyyyyyyyyy
KEEN_READ_KEY=zzzzzzzzzzzzzzz

If you run keen from a directory with this .env file, it will assume the project in context is the one specified by KEEN_PROJECT_ID.

To override the project context use the --project option:

$ keen project:show --project XXXXXXXXXXXXXXX

Similar overrides are available for specifiying API keys: --master-key, --read-key and --write-key.

For example:

$ keen project:show --project XXXXXXXXXXXXXXX --master-key AAAAAAAAAAAAAA

Shorter aliases exist as well: -p for project, -k for master key, -r for read key, and -w for write key.

$ keen project:show -p XXXXXXXXXXXXXXX -k AAAAAAAAAAAAAA

Usage

keen-cli has a variety of commands, and most are namespaced for clarity.

• version - Print version information

Projects

• project:open - Open the Project Overview page in a browser
• project:workbench - Open the Project Workbench in a browser
• project:show - Get data about the project, uses the project row resource.

Events

events:add - Add an event.

Parameters:

• --collection (alias -c): The collection to add the event to. Alternately you can set KEEN_COLLECTION_NAME on the environment if you're working with the same collection frequently.
• --data (alias -d). The properties of the event. The value can be JSON or key=value pairs delimited by & (just like a query string). Data can also be piped in via STDIN.

Various examples:

# create an empty event
$ keen events:add --collection cli-tests

# use the shorter form of collection
$ keen events:add -c cli-tests

# add a blank event to a collection specified in the .env file:
# KEEN_COLLECTION_NAME=cli-tests
$ keen events:add

# create an event from JSON
$ keen events:add -c cli-tests -d "{ \"username\" : \"dzello\", \"zsh\": 1 }"

# create an event from key value pairs
$ keen events:add -c cli-tests -d "username=dzello&zsh=1"

# pipe in events as JSON
$ echo "{ \"username\" : \"dzello\", \"zsh\": 1 }" | keen events:add -c cli-tests

# pipe in events in querystring format
$ echo "username=dzello&zsh=1" | keen events:add -c cli-test

# pipe in events from a file of newline delimited json
# { "username" : "dzello", "zsh" : 1 }
# { "username" : "dkador", "zsh" : 1 }
# { "username" : "gphat", "zsh" : 1 }
$ cat events.json | keen events:add -c cli-test

Queries

queries:run - Runs a query and prints the result in pretty JSON.

Parameters:

• --collection (alias -c) – The collection name to query against. Can also be set on the environment via KEEN_COLLECTION_NAME
• --analysis-type (alias -a)
• --group-by (alias -g)
• --target-property (alias -y)
• --timeframe (alias -t)
• --interval (alias -i)
• --filters (alias -f)
• --percentile

Some examples:

# run a count
$ keen queries:run --collection cli-tests --analysis-type count
1000

# run a count with collection name from .env
# KEEN_COLLECTION_NAME=cli-tests
$ keen queries:run --analysis-type count
1000

# run a count with a group by
$ keen queries:run --collection cli-tests --analysis-type count --group-by username
[
  {
    "username": "dzello",
    "result": 1000
  }
]

# run a query with a timeframe, target property, group by, and interval
$ keen queries:run --collection cli-tests --analysis-type median --target-property value --group-by cohort --timeframe last_24_hours --interval hourly

{
  "timeframe": {
    "start": "2014-06-27T01:00:00.000Z",
    "end": "2014-06-27T02:00:00.000Z"
  },
  "value": [
  ...
  ...
  ...

Contributing

keen-cli is open source, and contributions are very welcome!

Running the tests with:

$ bundle exec rake spec