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 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: