Getting started with QubeScript
QubeScript is QubeSurvey’s default questionnaire language. A .qube file contains
the questions, answer options and rules for what to ask next. Test it in VS Code,
then upload it to QubeSurvey for team testing and data collection. Existing Odin
questionnaires are also supported.
For the full path from authoring through export, follow Getting started. Install the QubeSurvey extension and set up an AI agent if you want one to help write and check the source. Fictional examples provide complete studies; the language reference covers the syntax.
Write and test a first script
Save this source as feedback.qube:
@survey feedback @language en @mode cawi
@question comment text
What should we improve?
@question thanks display
Thank you.
@outcome complete
Finished.With the file active in VS Code, run QubeSurvey: Run Interview from the Command Palette. Enter an invented answer and continue through Thank you to Finished. Review the questions and ending against your expectations. Local editing and interview testing need no QubeSurvey sign-in.
@survey names the questionnaire and sets its language and interview mode
(cawi means a web survey). Each @question has a name and an answer type,
followed by the wording shown to the respondent. Here, comment accepts a text
answer and thanks displays a page. @outcome complete ends the interview with
the name complete; you choose how that ending is recorded when setting up a Run.
A welcome page, consent, and a closing page
A page with no answer is an ordinary question with the display contract. That is all
a welcome or closing screen is, so the questionnaire carries the words the respondent
reads:
@survey staff-pulse @language en @mode cawi
@question welcome display
This is a five minute staff pulse. Your answers are anonymous: no name, email or
device is stored with them, and results are reported only in groups of five or more.
Contact people@example.org with any question.
@question consent single
Do you agree to take part?
@options
1: Yes, take part
2: No, thanks
@route consent_route
if answers.consent == 2 -> declined
else -> mood
@section pulse
@question mood single
How is your week going?
@options
1: Good
2: Mixed
3: Hard
@question thanks display
Thank you. Your answer is submitted and this survey is now closed.
@outcome complete
Finished.
@outcome declined
You chose not to take part. Nothing has been recorded.A refusal ending should keep no data. Point the refusal route at an outcome whose Keep data (charged) box is unticked: the case is still recorded as refused, nothing is retained, and nothing is charged. Ticking the box on a refusal would bill the respondent for declining — the one combination to avoid.
Prose outside a question is not a page. A paragraph written between questions is
ignored rather than rendered, with no error; put every welcome or closing sentence
inside its own display question. Keep each paragraph on one physical line, because
line breaks in the source are line breaks on the page.
Consent is a question, not a page: the answer is recorded, exported, and can be routed, which is what an ethics review asks you to prove. A display page cannot do that. Both the welcome and closing pages appear in the preview and in the live interview, and any redirect configured on the ending applies after the closing page.
Next, try the commuter-travel survey. It screens for recent commuters, asks which transport they use, and carries their choices into a follow-up question. Change an earlier answer with Back to see how the later questions change. The example studies contain longer questionnaires with their study specifications.
Use an AI agent
The extension bundles the qube command line and puts it on the PATH of VS
Code’s integrated terminal. Run QubeSurvey: Set Up AI Agent to write the
qube instructions into a marked section of your workspace AGENTS.md. See
Use qube with an AI agent for the commands.
Then prompt your agent in plain English to write, modify or review your
questionnaire (for example: “Add an eligibility screener asking if the
respondent commutes by transit, and route non-commuters to a thank-you page”).
Ask it to read the language guide and check the complete source with qube check
before proposing edits. Review its changes and run the local interview yourself
before uploading.
The qube local commands check the script on your computer. You choose the AI
agent and model separately; their data settings and charges apply to scripts you
share with them.
Upload and continue
Upload the reviewed .qube file to a Script’s Versions in
QubeSurvey. Each uploaded version stays unchanged;
upload another version when you edit the script. The Test view checks that
version without creating a live Run response. Uploading requires Script edit
permission; see People, access and billing.
Continue with Getting started for team testing,
tickets, fieldwork and exports. For Odin questionnaires, use a .odin editor
copy of the conventionally extensionless NIPO file; see
Using existing Odin scripts.
Where to go next
The QubeScript reference has a section for each part of the language:
- Questions and options for what a respondent answers.
- Pages, routing and repeats for interview flow.
- Frames, ordering and validation for instrument design.
- Languages and endings for delivery.
- Values and functions and the standard library for calculations.
- Current limits before relying on a helper that is designed but not implemented.