Using AI Agents with QSDA
AI agents that can run commands on your computer, such as Claude Code, OpenAI Codex, GitHub Copilot or Cursor in agent mode, can operate QSDA Pro for you. You describe a task in plain language, for example "Analyze every app in the Finance stream that hasn't been analyzed yet", and the agent finds the apps, starts the analyses, waits for them to finish, and reports the results.
The agent works through the QSDA Command Line Interface (CLI). The CLI is the recommended path for agents because:
- It ships with an agent skill file that teaches the agent how to connect, which commands to use, and which commands need your approval.
- Commands return JSON (
--json), which agents read reliably. - Commands such as
collectors createwait for an analysis to finish, so the agent does not need to write polling code. - Every command the agent runs is visible to you, and most agents ask your permission before running it.
Chat applications that cannot run programs on your computer cannot use the CLI. Developers building their own integration can call the QSDA API directly.
This article walks through setup on a new installation and then runs an example task with Claude Code. Other agents follow the same steps; only the skill installation differs.
Example environment
The steps below use this environment. Substitute your own names.
| Item | Value |
|---|---|
| QSDA Server address | http://qsda-server:5003 |
| API authentication | On ("Use API Auth" enabled, the default) |
| QSDA connection | Qlik QA, a Qlik Sense on Windows connection |
| Stream to analyze | Finance |
| Agent | Claude Code, running on the user's Windows workstation |
Step 1: Confirm the QSDA connection
The agent analyzes apps through a QSDA connection, so the connection must exist before the agent can use it. In a new installation, open QSDA in a browser at http://qsda-server:5003 and add the Qlik QA connection in Admin > Connections, if it is not already present. Use the Test button to confirm that QSDA can reach Qlik Sense and list apps.
Step 2: Make the CLI available on the agent's computer
The CLI is installed with QSDA Pro on the QSDA Server, in:
C:\Program Files\Qsda Pro\QsdaCliwhen installed for all usersC:\Users\_userid_\AppData\Local\Programs\Qsda Pro\QsdaCliwhen installed for the current user only
If the agent runs on the QSDA Server, use this folder as it is. If the agent runs on a different computer, as in this example, copy the entire QsdaCli folder, including its skills subfolder, from the server to the agent's computer, for example to C:\Tools\QsdaCli. qsda-cli.exe is a self-contained program and does not need .NET or any other installation. Copy it again after upgrading QSDA so the CLI version matches the server.
Add the QsdaCli folder to your Windows PATH so the agent can run qsda-cli from any directory:
- Open Start, type environment variables, and choose Edit environment variables for your account.
- Select Path, click Edit, click New, and enter the folder, for example
C:\Tools\QsdaCli. - Click OK.
The agent's computer must be able to reach http://qsda-server:5003. If it cannot, check that the Windows Firewall on the QSDA Server allows inbound connections on port 5003. Use the UI port (default 5003); the internal API port (default 5000) accepts only local connections.
Step 3: Create an API key for the agent
Because API authentication is on, every CLI command must present an API key.
- In QSDA, open Admin > API Keys and click Create Key.
- Enter a Name that identifies the agent, for example Claude Code - jsmith, and choose an Expiration. 90 days is a good starting point.
- Click Create and copy the token from the dialog. The token is shown only once.
An API key grants full access to the QSDA API, including commands that delete collections and connections. Create a separate key for each person and agent, so you can disable one without affecting the others.
Step 4: Tell the CLI where QSDA is and which key to use
Store the server address and API key in environment variables. The agent reads them from its environment, so the key never needs to be typed into the agent's chat, where it would be stored in the conversation history.
Open a Command Prompt and run:
setx QSDA_SERVER "http://qsda-server:5003"
setx QSDA_API_KEY "<paste the token here>"
setx affects programs started afterward only. Close and reopen your terminal, and restart the agent (or your editor, if the agent runs inside it), so it sees the new values.
Verify the setup from a new Command Prompt:
qsda-cli connections list
The command lists your QSDA connections, including Qlik QA. If it reports an authentication error (HTTP 401), the key is missing, mistyped, expired or disabled. If it cannot connect, check the server address and the firewall.
Step 5: Install the QSDA skill in the agent
The skill file, QsdaCli\skills\qsda-cli\SKILL.md, describes the CLI to the agent: how to find the executable, how to authenticate, which commands answer common questions, and which commands require your confirmation before they run. The agent loads it automatically when a task involves QSDA.
Claude Code: copy the qsda-cli folder (the folder that contains SKILL.md) to your personal skills folder:
xcopy /E /I "C:\Tools\QsdaCli\skills\qsda-cli" "%USERPROFILE%\.claude\skills\qsda-cli"
To confirm, start Claude Code and type /skills. qsda-cli appears in the list.
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 such as this to the agent's instructions file (for example AGENTS.md or .github/copilot-instructions.md):
Before using qsda-cli, read C:\Tools\QsdaCli\skills\qsda-cli\SKILL.md and follow it.
Replace the skill folder after upgrading QSDA, so the agent learns about new commands.
Step 6: Run the task
Start Claude Code in any folder (for example, a working folder such as C:\Work\qsda) and type the request:
Perform analysis on any app in the Finance stream of connection "Qlik QA" that has not yet been analyzed.
The agent plans the work from the skill and runs CLI commands to carry it out. Claude Code shows each command and asks before running it; review the command and approve it. A typical run looks like this.
1. Check the connection. The agent confirms that the CLI is configured and the connection exists:
qsda-cli connections list --json
2. Find the apps that have never been analyzed. QSDA records every analysis request in its analysis history. The history coverage command compares the apps currently visible to a connection with that history, and --unanalyzed lists the apps that have never been analyzed:
qsda-cli history coverage --connection "Qlik QA" --unanalyzed --json
The agent keeps the apps whose spaceOrStream is Finance. On a new installation, no app has been analyzed yet, so this is every app in the Finance stream.
3. Analyze each app. For each app, the agent starts an analysis by app ID. The command waits until the analysis finishes and prints the new collection ID:
qsda-cli collectors create 7d3f1c2a-5b8e-4f6a-9c1d-2e4b6a8f0c13 --connection "Qlik QA"
Analyzing an app opens it on the Qlik Sense server and can take several minutes for a large app. QSDA queues analyses according to its throttle settings, so the agent may start them with --no-wait and check progress with qsda-cli collectors status.
4. Confirm the results. The agent checks that each collection reached the Ready status:
qsda-cli collectors show <collectorId> --json
5. Report. The agent summarizes what it did, for example:
Analyzed 6 of 6 never-analyzed apps in the Finance stream on "Qlik QA":
App Status Flags Budget vs Actual Ready 42 GL Detail Ready 118 ... All analyses completed successfully. GL Detail has the most flags; ask me to summarize them.
The new collections appear in QSDA's Collections List and in Insights like any other analysis.
"Not yet analyzed" means the app has no analysis request recorded in this QSDA server's history, including failed or since-deleted analyses. Imported collections do not count. To re-analyze apps whose analysis failed, or apps not analyzed recently, describe that in the request instead, for example "analyze Finance apps not analyzed in the last 30 days".
Follow-up tasks
Once the collections exist, ask the agent about the results in the same conversation. For example:
- "Summarize the most serious flags in the GL Detail app."
- "Which Finance apps have unused fields? List the apps and the field count."
- "Export all views of the Budget vs Actual analysis to an Excel file in this folder."
- "Create an HTML report for each new collection."
- "What percentage of apps on Qlik QA has been analyzed, by stream?"
The agent reads views such as flags, fields and expressions with collectors view, writes large results to files rather than displaying them, and loads stored collections as needed. See Command Line Interface for the full command list.
Running the task on a schedule
Claude Code can also run without an interactive session, for example from Windows Task Scheduler, to analyze new Finance apps each night:
claude -p "Perform analysis on any app in the Finance stream of connection \"Qlik QA\" that has not yet been analyzed. Do not delete or unload anything."
In non-interactive mode the agent cannot ask for approval, so it runs only the commands its permission settings allow in advance. Allow the qsda-cli commands the task needs and nothing broader. See the Claude Code documentation on permission settings. Run the scheduled task under the Windows account that has QSDA_SERVER and QSDA_API_KEY set.
For a fixed, repeating task, a script that calls qsda-cli directly is often simpler and more predictable than an agent. Agents are most useful for tasks that change from run to run and for questions about the analysis results.
Security considerations
- Use a dedicated API key for each agent and give it an expiration. Disable or delete the key in Admin > API Keys when the agent no longer needs it. The Last used column shows whether a key is still in use.
- Keep the key out of the conversation. Provide it through the
QSDA_API_KEYenvironment variable rather than typing it into the agent's chat or into a script. - Review commands before approving them. The skill instructs the agent to ask for confirmation before deleting, importing or unloading collections and before deleting connections, but the API key itself permits these actions.
- Consider what the agent sends to its AI provider. Results the agent reads, such as app names, field names, expressions and load script, are sent to the agent's AI model as part of the conversation. Follow your organization's policy for sharing application metadata with AI services.
- Analyses open apps on Qlik Sense. Analyzing many large apps at once places load on the Qlik engine. Run large batches outside business hours.
Troubleshooting
| Symptom | Cause and remedy |
|---|---|
qsda-cli is not recognized | The QsdaCli folder is not on PATH, or the agent was started before PATH was changed. Restart the agent, or tell it the full path to qsda-cli.exe. |
| HTTP 401 / authentication error | QSDA_API_KEY is not set in the agent's environment, or the key is expired or disabled. Check the key in Admin > API Keys and restart the agent after changing the variable. |
| Cannot connect to the server | QSDA_SERVER is not set or is wrong, the QSDA services are stopped, or a firewall blocks port 5003. Test with qsda-cli connections list from the agent's computer. |
| The agent does not use the skill | Confirm the skill is installed (/skills in Claude Code), or mention QSDA or qsda-cli explicitly in the request. |
| An app title matches several apps | The agent should use app IDs. If it uses titles, ask it to add --stream Finance. |
To see the HTTP traffic for a failing command, ask the agent to repeat it with --debug. Debug output includes the API key; remove it before sharing the output.