Use qube with an AI agent

qube is a command line that checks, inspects and tests QubeSurvey scripts on your computer. The QubeSurvey extension puts it on the PATH of VS Code’s integrated terminal, so an AI agent that can run shell commands can use it. You choose the agent and model account. The local commands need no QubeSurvey sign-in and never use the network; the hosted commands do.

A survey script puts its questions, answer domains and routing in one source that you and your agent can inspect and edit. qube lets the agent read the language rules and check the complete script instead of guessing the syntax. Follow Getting started from authoring to data.

On this page

Set up

  1. Install the QubeSurvey extension and open your questionnaire folder in VS Code.
  2. Open a terminal (Terminal → New Terminal) and run qube --help. A terminal that was already open before the extension was installed or updated needs to be restarted.
  3. Run QubeSurvey: Set Up AI Agent from the Command Palette. It needs a trusted workspace with a folder open. It shows what it will write and asks you to confirm. It then writes the output of qube agent-guide into AGENTS.md in the folder root, between the markers <!-- qube:agent-guide:start --> and <!-- qube:agent-guide:end -->. If the file exists, only the marked section is replaced and the rest is not touched. Running it again gives the same file. Run it again after an extension update to refresh the guide.
  4. Start your agent in that terminal or folder. Agents that read AGENTS.md find the instructions there; for others, paste the output of qube agent-guide into their instructions.

qube needs Node.js 22 or later. It uses the node on your PATH; if there is none, it uses VS Code’s own runtime in VS Code terminals. The extension changes only the environment of VS Code’s integrated terminals. It installs nothing globally.

Commands, all printing JSON on stdout and a plain cause on stderr:

CommandPurpose
qube check <file>Parse and check complete source. Exits 1 when any error is found.
qube symbols <file>Outline, questions, option domains and routes.
qube transform <file>Odin: format, fix or unfix data positions, renumber, prepare translations.
qube explain <id>Explain an Odin diagnostic.
qube guide [odin|qube], qube reference <query>Authoring guide and focused language search.
qube patterns search <query>Observed survey-design patterns, with their review status.
qube interview start|answer|back|stateWalk a QubeScript or Odin interview step by step.
qube interview run <file>Take an interview in the terminal.
qube journeys run <journeys.json>Scripted Odin interviews with assertions.
qube capabilitiesParser versions and limits.

The language follows the file extension (.qube or .odin). QubeScript and Odin have independent native engines. Use the guides and checks alongside the QubeScript reference or Odin reference. Review pattern status before reusing an example.

The check and interview loop

Give your agent a concrete task, for example:

Run qube guide qube, then propose a short AI-usage survey. Show me the questions before coding. Write survey.qube, run qube check survey.qube until it reports no errors, and walk each route with qube interview. Describe the expected answers and ending for each route.

The loop the guide gives the agent is:

  1. Write or edit the complete source file.
  2. Run qube check. Fix every error first. qube explain covers Odin diagnostics.
  3. Walk the questionnaire with qube interview (Odin also: qube journeys run) and compare each route with the specification.
  4. Repeat until the check reports no errors and the routes behave as intended.

A parser check shows supported syntax and types, not that the questionnaire is right. Review the source diff, then run QubeSurvey: Run Interview with invented answers. Test a normal completion, each branch and a correction using Back.

An interview is a session file that records the accepted steps. Each call replays them. For QubeScript, answers are a JSON object keyed by the question ids shown on the page:

qube interview start survey.qube --session s.json --text
qube interview answer --session s.json --text '{"like":1,"age":42,"note":null}'
qube interview back --session s.json --text

null means no answer and is not 0. If the source file changes, the session is refused until you pass --rebase, which replays the recorded steps against the new source and reports the first step that no longer applies. --text prints a plain page instead of JSON. qube interview --help lists every answer form.

Take an interview yourself

qube interview run survey.qube asks the questions in the terminal. Enter a code (2), several codes (1 3), an option label, a number, free text, or an empty line for no answer. :back steps back, :state reprints the page and :quit leaves the session file to resume later. When standard input is a pipe, it reads one answer per line and exits 1 on the first refusal.

Test Odin routes

qube runs Odin scripts in the same runtime as the extension’s interview runner, so an agent can test routing without clicking through the debugger.

Step by step. qube interview start questionnaire.odin --session s.json returns the first page: question id, prompt, options, *BUT buttons, form fields and constraints. Odin options: --profile cawi|cati|capi|casi|full, --seed, --sample-data name=value for *SAMPLEDATA and --quota-full to answer every *STRAT quota check as full. qube interview answer takes one answer as JSON:

AnswerMeaning
2Select code 2. For a NUMBER/ALPHA *LIST question this selects the list entry; a *BUT code selects that button.
[1, 3]Select several codes (*MULTI).
"42"Type a NUMBER, ALPHA or OPEN value.
{"label": "Northgate"}Select the one option or button whose label equals or contains the text.
{"fields": {"1": 50}}Answer a *FORM by field number.
{"skip": true}Continue past a display screen.

If the runtime refuses the answer, nothing is recorded and the same question stays open. qube interview state returns the visited route, answers, variables and the end code; --name narrows the variables returned.

Many journeys. qube journeys run journeys.json runs up to 100 journeys in one call. Each journey has answer rules keyed by question id. Questions without a rule get the first offered option, the lowest allowed number or the text test; set unlisted to stop to stop at them instead. For a question asked more than once, {"perVisit": [...]} answers the first, second and later visits in turn; the last entry repeats. The checks are:

CheckPasses when
completed, endCodeThe interview ended with that state and *ENDST code (18 for a plain *END).
lastQuestionThe last answered question is this one.
visited, notVisitedEach question was asked at least once, or never.
visitsEach question was asked exactly this many times.
sequenceThe questions were asked in this order, with other questions allowed in between.
answers, varsStored answers and variables have these values.
{
  "sourcePath": "/absolute/path/study.q",
  "profile": "cawi",
  "journeys": [
    { "name": "no site: screen-out",
      "answers": { "201": 99999, "202": 99999 },
      "expect": { "endCode": "42", "notVisited": ["300"] } },
    { "name": "two used blocks, one separator",
      "answers": { "201": 101, "202": { "label": "Northgate" }, "40": { "perVisit": [1, 2, 1, 2] } },
      "expect": { "completed": true, "visits": { "410": 1 }, "lastQuestion": "900" } }
  ]
}

The report lists each journey’s pass or failure, the failed checks, end code, step count and the full visited route. A journey stops at an answer the runtime rejects or after maxSteps (default 600, at most 2,000). A sourcePath must be an absolute path to a .q, .odin, .qs or .txt file of at most 2 MiB. It is read as UTF-8 when its bytes are valid UTF-8 and as Windows-1252 otherwise.

These commands exercise QubeSurvey’s runtime, which follows NIPO behaviour where it is known. A passing journey does not replace testing on the target fieldwork system.

If qube is not found

  • qube: command not found: open a new integrated terminal. The extension sets the PATH when it activates, and a terminal that was open at the time keeps its old environment. Terminals outside VS Code do not get qube; run node <extension folder>/qube/qube.mjs there, or use QubeSurvey: Show Extension Status to see the exact path.
  • needs Node.js 22 or newer: install Node.js 22 or later, or use a VS Code terminal, where the extension provides VS Code’s own runtime as a fallback.
  • Set Up AI Agent refuses: it names the cause. Trust the workspace, open a folder, or fix unmatched qube:agent-guide markers in AGENTS.md.
  • Files failed verification: qube checks each bundled file against its manifest before use. Reinstall the extension.

Hosted commands

These commands talk to your QubeSurvey app and are the only qube commands that use the network. They print JSON on stdout and a plain cause on stderr; exit 0 is success, 1 a refusal, 2 a usage error. They use the screen words Script, Version, Run and Response.

CommandPurpose
qube login [--url <base>]Sign in with the device flow: prints a URL and a code on stderr, waits for you to approve in the browser. Default https://app.qubesurvey.com.
qube logout, qube whoamiRemove the local token and ask the server to end the session (the output says whether the server confirmed it); show your Accounts and Scripts.
qube upload <file> [--script <id|name>] [--create <name> --account <id>]Check the file locally, refuse on errors, then create a new immutable Version and print its id, number and test URL. The Script chosen for a file is remembered.
qube script list, qube version list --script <id>List Scripts and their Versions.
qube run list|show|createList Runs, show one, or create an open-link survey Run as a draft (create --version <id>).
qube run activate <run> --yesMake the link live. Accepted responses are charged to the Account’s prepaid credit.
qube run pause|resume <run>, qube run close <run> --yesPause or resume; closing is irreversible.
qube export create <run> --format csv|jsonl|sss [--wait] [--out <dir>]Create an export job; with --wait, poll (at most --timeout seconds) and download. export list and export download <run> <job> complete the set. An existing file is never overwritten without --force.
qube ticket list|show|comment|fix|bundleWork tickets. fix marks a ticket fixed with the latest uploaded Version for you to verify; it never resolves or closes one.

activate and close print what would happen and exit 2 until you repeat them with --yes. An agent should run upload, activate and close only when you asked for that action.

The token is stored per base URL in tokens.json inside ~/.config/qube/ ($XDG_CONFIG_HOME/qube/, or %APPDATA%\qube\ on Windows), in a directory readable only by you with the file at mode 0600. qube refuses to use a token file that other users can read, and never prints a token. Set QUBE_TOKEN to override the file, for example in a harness. The remembered Script per file is kept in scripts.json in the same folder. The extension’s sign-in is separate.

Data and cloud work

The local commands run on this computer. They send no script anywhere and use no hosted AI credit. Your agent and model are configured separately; their data settings and charges apply to source you share with them.

The hosted commands send what you ask them to (a script on upload, an export request) to the app you signed in to. Run settings, quotas and Groups are still managed in the QubeSurvey app.