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
- The check and interview loop
- Take an interview yourself
- Test Odin routes
- If qube is not found
- Hosted commands
- Data and cloud work
Set up
- Install the QubeSurvey extension and open your questionnaire folder in VS Code.
- 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. - 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-guideintoAGENTS.mdin 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. - Start your agent in that terminal or folder. Agents that read
AGENTS.mdfind the instructions there; for others, paste the output ofqube agent-guideinto 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:
| Command | Purpose |
|---|---|
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|state | Walk 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 capabilities | Parser 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. Writesurvey.qube, runqube check survey.qubeuntil it reports no errors, and walk each route withqube interview. Describe the expected answers and ending for each route.
The loop the guide gives the agent is:
- Write or edit the complete source file.
- Run
qube check. Fix every error first.qube explaincovers Odin diagnostics. - Walk the questionnaire with
qube interview(Odin also:qube journeys run) and compare each route with the specification. - 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 --textnull 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:
| Answer | Meaning |
|---|---|
2 | Select 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:
| Check | Passes when |
|---|---|
completed, endCode | The interview ended with that state and *ENDST code (18 for a plain *END). |
lastQuestion | The last answered question is this one. |
visited, notVisited | Each question was asked at least once, or never. |
visits | Each question was asked exactly this many times. |
sequence | The questions were asked in this order, with other questions allowed in between. |
answers, vars | Stored 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 getqube; runnode <extension folder>/qube/qube.mjsthere, 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-guidemarkers inAGENTS.md. - Files failed verification:
qubechecks 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.
| Command | Purpose |
|---|---|
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 whoami | Remove 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|create | List Runs, show one, or create an open-link survey Run as a draft (create --version <id>). |
qube run activate <run> --yes | Make the link live. Accepted responses are charged to the Account’s prepaid credit. |
qube run pause|resume <run>, qube run close <run> --yes | Pause 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|bundle | Work 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.