Get started with Qlik CLI

Overview

In this tutorial, you are going to learn the basics of qlik-cli:

Configure the context a connection to Qlik Sense SaaS.
Create a Qlik app using the command line interface.
Add a script to the app.
Reload the app.
Evaluate loaded data using an expression.

Installation

If you haven't set up qlik-cli on your system, follow the directions on the qlik-cli main page here.

On a Mac

Install qlik-cli using Homebrew.

First, install the qlik open source tap:

brew tap qlik-oss/taps

then install the tool:

brew install qlik-cli

On a Windows PC

Install qlik-cli using Chocolatey.

choco install qlik-cli -Source https://www.nuget.org/api/v2

Requirements

Before you begin:

Have access to a Qlik Sense SaaS tenant. Make sure to record the fully qualified domain name of your tenant because it's needed for connecting through qlik-cli.
Confirm the user has a professional license assignment in the tenant.
Confirm the developer role assignment is added to the user who is accessing the tenant through the cli. Click here to learn more.
Obtain an API key from your Qlik Sense SaaS tenant. If you don't know how to obtain an API key, click here and complete this step before continuing.
Install a JSON parser like jq to pipe JSON responses into objects you can use in future commands. On a mac: brew install jq; On Windows: choco install jq

Getting started

Create context

The easiest way to authenticate to Qlik Sense SaaS with qlik-cli is through the context command.

With the API key you obtained previously, enter qlik context init in the command line. A brief set of directions appears requesting the URL to your Qlik Sense SaaS tenant. Enter the tenant URL collected in the requirements sections. You may include https:// in the entry.

Enter tenant URL:

Add the API key acquired earlier into the command line when prompted.

To generate a new API-key, go to
https://<tenant>.<region>.qlikcloud.com/settings/api-keys
API-key:

Upon successful authentication, you should receive a message like this:

Welcome Hardcore Harry, everything is now set up.

Usage

qlik-cli has documentation built into it. For any command issued to the command line, you can add --help to the end and qlik-cli tells you what you can do with it. Begin by entering qlik app create --help into the command line. qlik-cli doesn't create the app here. What it does is return the documentation for the create command.

Creates a new app.
Note that if you're using the --quiet flag, the ID returned will be an item ID.

Usage:
  qlik app create [flags]

Flags:
      --attributes-description string   The description of the application
      --attributes-name string          The name (title) of the application
      --attributes-spaceId string       The space id of the application
  -f, --file string                     Reads request from a file
  -h, --help                            help for create
  -q, --quiet                           Return only ids from the command
      --raw                             Return original response from server without any processing

Create the app

Begin by creating a Qlik app.

# syntax:
qlik app create --attributes-name <appName> -q

# example of creating an app named 'cli-created-app'
qlik app create --attributes-name cli-created-app -q

The command returns only the item id in the prompt because you added the -q flag.

# the item id of your app may vary
5ecd3510a085da00012392da

Note: the item id isn't the same as the app id. The item id is the reference to the app in the items collection. The app id, also known as the resourceId, is a globally unique identifier (guid). You are going to retrieve the app id later in the tutorial.

To confirm app creation, log in to the hub as the user and see the app appears in your home.

a screenshot of an app in Qlik Sense
SaaS hub

If you want to view information about the app you just created use the item get command with the item id obtained earlier:

# syntax:
qlik item get <itemId>

# example of getting an item with the supplied item id:
qlik item get 5ecd3510a085da00012392da

and the response contains all the tenant related metadata tied to the app.

Reveal the item get response

{
  "actions": [
    "read",
    "create",
    "update",
    "delete",
    "reload",
    "import",
    "export",
    "duplicate",
    "change_owner",
    "change_space"
  ],
  "collectionIds": null,
  "createdAt": "2020-05-26T15:26:08Z",
  "creatorId": "BewQZxFax8r47sLrGUmfy4K8YKzYAkjA",
  "id": "5ecd3510a085da00012392da",
  "isFavorited": false,
  "meta": {
    "actions": [
      "read",
      "create",
      "update",
      "delete",
      "reload",
      "import",
      "export",
      "duplicate",
      "change_owner",
      "change_space"
    ],
    "collections": null,
    "isFavorited": false,
    "tags": null
  },
  "name": "cli-created-app",
  "ownerId": "BewQZxFax8r47sLrGUmfy4K8YKzYAkjA",
  "resourceAttributes": {
    "_resourcetype": "app",
    "createdDate": "2020-05-26T15:26:07.796Z",
    "description": "",
    "dynamicColor": "",
    "hasSectionAccess": false,
    "id": "d4b79fd4-d851-42b4-be05-0e64b803811b",
    "lastReloadTime": "2020-05-26T19:38:47.344Z",
    "modifiedDate": "2020-05-26T19:38:47.766Z",
    "name": "cli-created-app",
    "originAppId": "",
    "owner": "0hEhiPyhMBdtOCv2UZKoLo4G24p-7R6eeGdZUQHF0-c",
    "ownerId": "BewQZxFax8r47sLrGUmfy4K8YKzYAkjA",
    "publishTime": "",
    "published": false,
    "spaceId": "",
    "thumbnail": ""
  },
  "resourceCreatedAt": "2020-05-26T15:26:07Z",
  "resourceCustomAttributes": null,
  "resourceId": "d4b79fd4-d851-42b4-be05-0e64b803811b",
  "resourceSubType": "",
  "resourceType": "app",
  "resourceUpdatedAt": "2020-05-26T19:38:47Z",
  "tenantId": "TohbNbUjAGrVXhrvVujU73hzgDQ6DxnG",
  "updatedAt": "2020-05-26T19:38:48Z",
  "updaterId": "BewQZxFax8r47sLrGUmfy4K8YKzYAkjA"
}

Add a load script to the app

An app isn't very useful if it doesn't have a script to load data into it. Here's a sample script to load:

Reveal the script

SET ThousandSep=',';
SET DecimalSep='.';
SET MoneyThousandSep=',';
SET MoneyDecimalSep='.';
SET MoneyFormat='$ ###0.00;-$ ###0.00';
SET TimeFormat='h:mm:ss TT';
SET DateFormat='M/D/YYYY';
SET TimestampFormat='M/D/YYYY h:mm:ss[.fff] TT';
SET FirstWeekDay=6;
SET BrokenWeeks=1;
SET ReferenceDay=0;
SET FirstMonthOfYear=1;
SET CollationLocale='en-US';
SET CreateSearchIndexOnReload=1;
SET MonthNames='Jan;Feb;Mar;Apr;May;Jun;Jul;Aug;Sep;Oct;Nov;Dec';
SET LongMonthNames='January;February;March;April;May;June;July;August;September;October;November;December';
SET DayNames='Mon;Tue;Wed;Thu;Fri;Sat;Sun';
SET LongDayNames='Monday;Tuesday;Wednesday;Thursday;Friday;Saturday;Sunday';
SET NumericalAbbreviation='3:k;6:M;9:G;12:T;15:P;18:E;21:Z;24:Y;-3:m;-6:μ;-9:n;-12:p;-15:f;-18:a;-21:z;-24:y';

Characters:
Load Chr(RecNo()+Ord('A')-1) as Alpha, RecNo() as Num autogenerate 26;

ASCII:
Load
 if(RecNo()>=65 and RecNo()<=90,RecNo()-64) as Num,
 Chr(RecNo()) as AsciiAlpha,
 RecNo() as AsciiNum
autogenerate 255
 Where (RecNo()>=32 and RecNo()<=126) or RecNo()>=160 ;

Transactions:
Load
 TransLineID,
 TransID,
 mod(TransID,26)+1 as Num,
 Pick(Ceil(3*Rand1),'A','B','C') as Dim1,
 Pick(Ceil(6*Rand1),'a','b','c','d','e','f') as Dim2,
 Pick(Ceil(3*Rand()),'X','Y','Z') as Dim3,
 Round(1000*Rand()*Rand()*Rand1) as Expression1,
 Round(  10*Rand()*Rand()*Rand1) as Expression2,
 Round(Rand()*Rand1,0.00001) as Expression3;
Load
 Rand() as Rand1,
 IterNo() as TransLineID,
 RecNo() as TransID
Autogenerate 1000
 While Rand()<=0.5 or IterNo()=1;

 Comment Field Dim1 With "This is a field comment";

When saved to a file with a .qvs extension it can be added to the app using script set command. For the set command you supply the path to the file containing the script and a reference to the app, either the app name or the id.

# syntax:
qlik app script set <scriptFileName> --app <itemId>

# example script set command with path to file and app item id:
qlik app script set ./documents/qlikscripts/basescript.qvs --app 5ecd3510a085da00012392da

The response should look like this:

{cli-created-app d4b79fd4-d851-42b4-be05-0e64b803811b}
Saving app...
App successfully saved

Reload the app

To reload the app use the reload command to create the reload task. The reload task requires the app resourceId, which is different than the item id returned earlier in the tutorial.

To get the app's resourceId use jq with a pipe to access the object:

# syntax:
qlik item get <itemId> | jq .resourceId

# example get command using item id and jq to parse json response:
qlik item get 5ecd3510a085da00012392da | jq .resourceId

This command returns the app's resourceId which looks like this: d4b79fd4-d851-42b4-be05-0e64b803811b. Use this resourceId to create the reload task.

# syntax:
qlik reload create --appId <resourceId>

# example reload create command using the app resource id:
qlik reload create --appId d4b79fd4-d851-42b4-be05-0e64b803811b

The command returns the following information:

{
  "appId": "d4b79fd4-d851-42b4-be05-0e64b803811b",
  "creationTime": "2020-05-26T19:38:43.94Z",
  "id": "5ecd704375a8ec00019d0592",
  "status": "QUEUED",
  "tenantId": "TohbNbUjAGrVXhrvVujU73hzgDQ6DxnG",
  "type": "hub",
  "userId": "BewQZxFax8r47sLrGUmfy4K8YKzYAkjA"
}

where the id is the reload id. To retrieve the up to date status of the reload use the get command.

# syntax:
qlik reload get <reloadId>

# example reload get command using the reload id:
qlik reload get 5ecd704375a8ec00019d0592

Issuing this command returns:

{
  "appId": "d4b79fd4-d851-42b4-be05-0e64b803811b",
  "creationTime": "2020-05-26T19:38:43.94Z",
  "duration": "1.566s",
  "endTime": "2020-05-26T19:38:48.192Z",
  "engineTime": "2020-05-26T19:38:47.344Z",
  "id": "5ecd704375a8ec00019d0592",
  "log": "Characters \u003c\u003c AUTOGENERATE(26) 26 Lines fetched\nASCII \u003c\u003c AUTOGENERATE(255) 191 Lines fetched\nTransactions \u003c\u003c AUTOGENERATE(1000) 2,028 Lines fetched\n",
  "startTime": "2020-05-26T19:38:46.625Z",
  "status": "SUCCEEDED",
  "tenantId": "TohbNbUjAGrVXhrvVujU73hzgDQ6DxnG",
  "type": "hub",
  "userId": "BewQZxFax8r47sLrGUmfy4K8YKzYAkjA"
}

The app reload succeeded. Now you can validate the app data using the eval command.

Evaluating app data using an expression

So far you have created an app, added a script, and loaded data; all normal command line interface and automation type activities. While this is great, and is sure to help you become more efficient, wouldn't it be nice to access the app and interact with the data?

What does the eval command do? It enables you to write an expression in the command line to evaluate data in the app using the Qlik Associative Engine.

# syntax:
qlik app eval <measure> string by <dimension> string --app <itemId> OR <resourceId>

# Using the eval command to count the Dim1s by Dim1 values for the given app resource id:
qlik app eval "count(Dim1)" by "Dim1" --app d4b79fd4-d851-42b4-be05-0e64b803811b

and observe the response:

+------+-------------+
| Dim1 | count(Dim1) |
+------+-------------+
| A    | 686         |
| B    | 678         |
| C    | 664         |
+------+-------------+

Recap

Excellent job. You have taken a big step into using qlik-cli. Now, you have the capability to work with Qlik apps from a command line, and so much more. From spaces to items and reloads to collections, there is a lot you can do to automate Qlik Sense.

Full set of commands used in tutorial

# establish context for connecting to Qlik Sense SaaS
qlik context init

# create an app in the context tenant with a specified name, returns the item id for the app
qlik app create --attributes-name <appName> -q

# returns additional system metadata for the app including resourceId
qlik item get <itemId>

# sets the load script from a supplied filename for a given Qlik app item id
qlik app script set <scriptFileName> --app <itemId>

# returns the resourceId from an app's system metadata using jq to parse the JSON response
qlik item get <itemId> | jq .resourceId

# creates a reload for an app with a supplied resource id
qlik reload create --appId <resourceId>

# returns status information for the reload associated to the reload id
qlik reload get <reloadId>

# returns data from the supplied app item id or resource id given an expression using strings to represent the measure(s) and dimension(s) to calculate
qlik app eval <measure> string by <dimension> string --app <itemId> OR <resourceId>

Sample script

SET ThousandSep=',';
SET DecimalSep='.';
SET MoneyThousandSep=',';
SET MoneyDecimalSep='.';
SET MoneyFormat='$ ###0.00;-$ ###0.00';
SET TimeFormat='h:mm:ss TT';
SET DateFormat='M/D/YYYY';
SET TimestampFormat='M/D/YYYY h:mm:ss[.fff] TT';
SET FirstWeekDay=6;
SET BrokenWeeks=1;
SET ReferenceDay=0;
SET FirstMonthOfYear=1;
SET CollationLocale='en-US';
SET CreateSearchIndexOnReload=1;
SET MonthNames='Jan;Feb;Mar;Apr;May;Jun;Jul;Aug;Sep;Oct;Nov;Dec';
SET LongMonthNames='January;February;March;April;May;June;July;August;September;October;November;December';
SET DayNames='Mon;Tue;Wed;Thu;Fri;Sat;Sun';
SET LongDayNames='Monday;Tuesday;Wednesday;Thursday;Friday;Saturday;Sunday';
SET NumericalAbbreviation='3:k;6:M;9:G;12:T;15:P;18:E;21:Z;24:Y;-3:m;-6:μ;-9:n;-12:p;-15:f;-18:a;-21:z;-24:y';

Characters:
Load Chr(RecNo()+Ord('A')-1) as Alpha, RecNo() as Num autogenerate 26;

ASCII:
Load
 if(RecNo()>=65 and RecNo()<=90,RecNo()-64) as Num,
 Chr(RecNo()) as AsciiAlpha,
 RecNo() as AsciiNum
autogenerate 255
 Where (RecNo()>=32 and RecNo()<=126) or RecNo()>=160 ;

Transactions:
Load
 TransLineID,
 TransID,
 mod(TransID,26)+1 as Num,
 Pick(Ceil(3*Rand1),'A','B','C') as Dim1,
 Pick(Ceil(6*Rand1),'a','b','c','d','e','f') as Dim2,
 Pick(Ceil(3*Rand()),'X','Y','Z') as Dim3,
 Round(1000*Rand()*Rand()*Rand1) as Expression1,
 Round(  10*Rand()*Rand()*Rand1) as Expression2,
 Round(Rand()*Rand1,0.00001) as Expression3;
Load
 Rand() as Rand1,
 IterNo() as TransLineID,
 RecNo() as TransID
Autogenerate 1000
 While Rand()<=0.5 or IterNo()=1;

 Comment Field Dim1 With "This is a field comment";

ON THIS PAGE