Get started with qlik-cli

Overview

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

Configure a context to enable 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

Installation on Windows via package manager is not currently available. You can download the Windows executable.

Requirements

Before you begin, you need to:

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 is assigned 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.

Get 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 to receive information about the specific command. 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.

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 an 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 app ID in the prompt because you added the -q flag.

# the app ID of your app may vary
a4cddff4-2227-41e3-9e43-abcfc88a0b2c

To confirm app creation, log in to the hub as the user and see if the app appears on Qlik Sense Hub 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 qlik app get command with the app ID obtained earlier:

# syntax:
qlik app get <appId>

# example of getting an item with the supplied app id:
qlik app get a4cddff4-2227-41e3-9e43-abcfc88a0b2c

The response contains app-related metadata for the app.

Reveal the app get response

{
  "attributes": {
    "_resourcetype": "app",
    "createdDate": "2020-06-05T10:56:25.028Z",
    "custom": {},
    "description": "",
    "dynamicColor": "",
    "encrypted": true,
    "hasSectionAccess": false,
    "id": "a4cddff4-2227-41e3-9e43-abcfc88a0b2c",
    "lastReloadTime": "2020-04-24T13:15:19.202Z",
    "modifiedDate": "2020-06-05T10:56:25.028Z",
    "name": "cli-created-app",
    "originAppId": "",
    "owner": "auth0|a09D0010XXHBXVqAiP",
    "ownerId": "NsBYNuvXRvJdlwX2sLlqqlhAD2_DK3S",
    "publishTime": "",
    "published": false,
    "thumbnail": ""
  },
  "create": [
    {
      "canCreate": true,
      "resource": "sheet"
    },
    {
      "canCreate": true,
      "resource": "bookmark"
    },
    {
      "canCreate": true,
      "resource": "snapshot"
    },
    {
      "canCreate": true,
      "resource": "story"
    },
    {
      "canCreate": true,
      "resource": "dimension"
    },
    {
      "canCreate": true,
      "resource": "measure"
    },
    {
      "canCreate": true,
      "resource": "masterobject"
    },
    {
      "canCreate": true,
      "resource": "variable"
    }
  ],
  "privileges": [
    "read",
    "update",
    "delete",
    "reload",
    "export",
    "duplicate",
    "change_owner",
    "change_space"
  ]
}

You can retrieve more tenant-related data of the app by using the item ls command:

qlik item ls --resourceId <appId> --resourceType app

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 ID:
qlik app script set ./documents/qlikscripts/basescript.qvs --app d4b79fd4-d851-42b4-be05-0e64b803811b

The response should look like this:

Saving app...
App successfully saved

Reload the app

To reload the app, use the reload command to create the reload task.

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

# 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. These are 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 towards 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

# metadata for the app
qlik app get <appId>

# sets the load script from a supplied file name for a given Qlik app ID
qlik app script set <scriptFileName> --app <appId>

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

# returns status information for the reload associated with 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";