Skip to main content
Version: V3.8

Command Line Interface (CLI)

As an alternative to the QSDA browser interface, the QSDA CLI may be used to perform tasks like starting an analysis or extracting analysis output. This is useful when building site specific automations or using AI agents.

Location​

qsda-cli.exe is a standalone module and may be copied and run from any windows directory. It is recommended to use the version of qsda-cli.exe that matches the version of your QSDA Pro server.

The CLI can be found in the folder:

C:\Program Files\Qsda Pro\QsdaCli If installed "for all users"

C:\Users\_userid_\AppData\Local\Programs\Qsda Pro\QsdaCli if installed "only for me"

To run qsda-cli from any directory, add the QsdaCli folder to your Windows PATH.

Connecting to the QSDA Server​

The CLI communicates with the QSDA Server over its web address, by default http://localhost:5003. When running the CLI on a different machine, or when Use HTTPS is enabled, provide the UI address with the --server option or the QSDA_SERVER environment variable. Include the UI Base Path when configured, for example https://qsda.mycompany.com/qsda. Use the UI port (default 5003); the internal API port (default 5000) is loopback-only.

qsda-cli connections list --server https://qsda.mycompany.com:5003

Authentication​

If "Use API Auth" is enabled (default) in API Security, each CLI command must present an API key. Create a key in the Admin > API Keys page and provide it with the --api-key option or, preferably, the QSDA_API_KEY environment variable so the key does not appear in command history or scripts.

setx QSDA_API_KEY "<your key>"

Note: setx affects new command windows only. Open a new window after setting the variable.

An API key grants full access to the QSDA API, including commands that delete collections and connections. Create a separate key for each automation or agent, choose an expiration, and disable or delete the key when it is no longer needed.

Getting Help​

Use the -h help option to explore the available commands and parameters.

qsda-cli -h

qsda-cli _command_ -h

The options for a command, including the global options --server, --api-key and --debug, are listed at the command level. For example:

qsda-cli collectors view -h

Add --debug to a command to print HTTP requests and responses to stderr when diagnosing a problem. Debug output includes headers, including the bearer token, and response content. Remove credentials and sensitive application information before sharing captured output.

Commands​

The CLI refers to an analysis of an app (a collection) as a collector.

CommandDescription
apps listList apps available on a connection
apps streamsList streams on a QSEoW connection
apps bookmarks <app>List bookmarks for an app
collectors listList all collections
collectors statusShow the collection queue status
collectors show <collectorId>Show details for a collection
collectors create <app>Analyze an app, creating a new collection
collectors load <collectorId>Load a collection into memory and start analysis
collectors unload <collectorId>Unload a collection from memory. The stored collection is kept
collectors delete <collectorId>Delete a collection
collectors export <collectorId>Export a collection to a zip file
collectors import <file>Import a collection from a zip file
collectors view <collectorId> <view>Display a view from a collection, such as flags, expressions or fields
collectors export-views <collectorId>Export all views from a collection as CSV, Excel or SQLite
collectors html <collectorId>Generate an HTML report for a collection
history listList recorded analysis runs, including retained entries for deleted collections
history summarySummarize analysis activity by month, user, or connection
history coverageCompare available apps on a connection with recorded history
history exportExport analysis history to CSV or Excel
connections listList configured connections
connections show <id>Show details for a connection
connections test <id>Test a connection
connections delete <id>Delete a connection
support packageCreate a support package zip file

Connection options accept either the connection ID or name. App commands, collectors create, and history coverage use the first configured connection when it is omitted. For history list, history summary, and history export, omitting --connection leaves history unrestricted by connection.

Commands that take an app (<app>) accept either the app ID or the app title. Titles are matched ignoring case. If more than one app has the title, the command lists the matching apps with their IDs and streams or spaces and stops with an error. Use the app ID, or add --stream <name> (or its alias --space <name>) to choose the QSEoW stream or Qlik Cloud space. Qlik Sense Desktop has no streams, so use the app ID when two Desktop apps share a title.

Output​

By default, results are displayed as formatted tables. Add --json to output JSON, which is better suited for scripts and AI agents. apps list, collectors list, connections list, and history list accept --sort <column>[:asc|desc]. Commands that produce a file accept -o to choose the output path.

A collection must be loaded and analyzed before its views can be displayed or exported. Add --load to collectors view or collectors export-views to load the collection and wait for analysis to complete. When --load has to load a collection, it requests a 30-second idle timeout; the server checks for idle collections every 15 seconds. An already-ready collection retains its existing policy. Opening the analysis in the browser clears that short timeout. For a series of commands, use collectors load before the first on-demand load to start under the site-wide idle policy. This command starts analysis without waiting: check collectors show until Ready, or use collectors view --load to wait. If you call collectors load on an already-loaded collection, the server restores the site-wide policy but returns an Already loaded error (HTTP 409), so scripts should not treat it as an idempotent success.

Collection and export options​

  • apps list: --stream <name> lists only the apps in a QSEoW stream or Qlik Cloud space. The special names described in Filter a Connection, such as personal, are also accepted.
  • collectors create: --description labels the collection, --no-calctime skips calculation timings, --bookmark applies a bookmark by name, and --timeout sets the maximum seconds to wait for each Qlik engine operation (default: the project's Qlik Timeout setting, initially 90). By default the command waits for the collection to complete and shows its progress. Add --no-wait to print the new collection ID and return immediately.
  • collectors view and collectors export-views: --load loads a collection when necessary and waits for analysis. --timeout controls that wait (default 120 seconds).
  • collectors export-views: --format csv|xlsx|sqlite selects the output (CSV is a ZIP archive). --schema V37|V38.Migrate|V38|Latest overrides the server's project setting for this export. The default project setting is Latest, which resolves to V38 in 3.8. Review schema compatibility before upgrading a scripted ingestion workflow.
  • collectors html: --template selects a server-side template name (default default); --output chooses the report file. Load the collection first if it is not ready.

Analysis history​

history list, history summary, and history export accept --from, --to, --connection, repeatable --space (alias --stream), --app, --user, --status, and --exclude-deleted. Deleted entries are included by default. --app accepts an app ID or an unambiguous title from the recorded history; narrow by connection or space if necessary. Imported collections are excluded.

history summary --group-by month|user|connection controls the breakdown. history export --format csv|xlsx --output <file> writes the matching history. Use --json for structured output from history list, summary, or coverage.

history coverage --connection <name> --unanalyzed shows coverage for the apps currently accessible to a connection and also lists apps never analyzed. It does not take the date and other history-list filters. The analyzed-ever count uses any retained request, including queued, failed, or cancelled requests; its never-analyzed list contains apps with no recorded request. The recent 30/90-day counts use successful (Ready) analyses. Retained entries for deleted collections contribute, and purging history can reduce coverage. See Analysis History.

qsda-cli history list --from 2026-01-01 --connection "QSEoW Prod" --json
qsda-cli history summary --group-by user --exclude-deleted
qsda-cli history export --format xlsx --output history.xlsx
qsda-cli collectors export-views <collectorId> --format csv --schema V37 --load --output analysis.zip

Examples​

Analyze an app and display its flags:

qsda-cli apps list --connection "QSEoW Prod" --json
qsda-cli collectors create 4a7a2f8e-1c2b-4b9e-9a51-2f0c3d1e5b77 --connection "QSEoW Prod"
qsda-cli collectors view <collectorId> flags --load

Analyze an app by its title, choosing the stream when several apps share the title:

qsda-cli collectors create "Sales Dashboard" --stream Finance --connection "QSEoW Prod"

Export every view of a collection to a SQLite database:

qsda-cli collectors export-views <collectorId> --format sqlite --load --output analysis.sqlite

List the apps on a connection that have never been analyzed:

qsda-cli history coverage --connection "QSEoW Prod" --unanalyzed

Using the CLI with AI Agents​

AI agents that can run commands on your computer, such as Claude Code, OpenAI Codex, GitHub Copilot or Cursor in agent mode, can use the CLI to analyze apps and answer questions about the results. Chat applications that cannot run local programs cannot use the CLI.

QSDA includes an agent skill file that describes the CLI to an agent: how to connect and authenticate, which commands to use for common tasks, and which commands require your confirmation before they run. The file is installed at:

QsdaCli\skills\qsda-cli\SKILL.md

To give an agent access to QSDA:

  1. Add the QsdaCli folder to your PATH, or let the agent find qsda-cli.exe in the install folder.
  2. Create an API key for the agent in Admin > API Keys and set it in the QSDA_API_KEY environment variable of the account the agent runs under. Also set QSDA_SERVER if the QSDA Server is not on the same machine. Provide the key through the environment rather than typing it into the agent's chat.
  3. Make the skill available to the agent:
    • Claude Code: copy the qsda-cli folder to %USERPROFILE%\.claude\skills\.
    • Other agents that support skills: copy the qsda-cli folder to the agent's skills folder. See the agent's documentation for its location.
    • Agents without skill support: add a line to the agent's instructions file (for example AGENTS.md) telling it to read the SKILL.md file before using qsda-cli.
  4. Ask the agent a question, for example "Analyze the Sales Dashboard app with QSDA and summarize its most serious flags."

The skill instructs the agent to ask for confirmation before deleting, importing or unloading collections and before deleting connections. Because the API key permits these actions, use a dedicated key for the agent and review the agent's commands before approving them.

For a step-by-step walkthrough, including setup on a separate computer and an example task, see Using AI Agents with QSDA.