CLI Commands

pip install quantum-framework installs the quantum command.

quantum <command>
python -m quantum.cli.runner <command>   # the same, without the script on PATH

Every command takes -h / --help. This page is about the everyday ones; the command-line reference, generated from the code, lists every command and option.

Commands Overview

Command	Description
run	Execute a .q file
start	Serve the application's pages
stop	Stop the server quantum start started
console	The application's pages in the terminal
desktop	The application's pages in a desktop window
package	One file of the application to hand someone: its TUI and its server
check	Pages parse, SQL compiles, query fields exist
test	Run the app's *.test.q tests
migrate	Apply, roll back and plan database migrations

quantum run

Execute a Quantum file (.q).

quantum run <file.q> [options]

Option	Description	Default
--debug	Print what is parsed and run	off
--config	Path to config file	quantum.config.yaml
--target	Standalone UI build (type="ui"): html, textual (layout only), mobile (Laboratory)	html

$ quantum run hello.q
[EXEC] Executing component: HelloWorld
[SUCCESS] Result: Hello World!

$ quantum run hello.q --debug
[DEBUG] Parsing file: hello.q
[DEBUG] AST generated: ComponentNode
[DEBUG] Validating AST...
[EXEC] Executing component: HelloWorld
   Type: pure
   Params: 0
   Returns: 1
[SUCCESS] Result: Hello World!

What run does depends on the file:

File	Behavior
q:component	Executes it and prints the result
q:application type="ui"	Builds the standalone UI (Experimental)
q:application type="terminal"	Builds the terminal app (Experimental)
q:application type="game"	Builds the game (Laboratory)
q:job	Runs the job (Experimental)

A web app is not a q:application: it is pages in components/, served by quantum start (APP-1).

A file that does not exist, does not parse or fails exits with 1.

quantum start

Serve the pages in components/ on the port in quantum.config.yaml (8080 by default).

quantum start                  # in the application's folder
quantum start --port 3000
quantum start --hot-reload     # reload the open pages on every save

Debug mode — the /_dev panel and detailed error pages — is server.debug: true in quantum.config.yaml. The --debug flag only prints the traceback when the server fails to start. See also Hot Reload.

quantum stop

Stops the server that quantum start started from this folder (it records its process in .quantum.pid). A process it cannot be sure is that server is not killed: the command says so and exits with 1 (RUN-3).

quantum console

The same pages in the terminal:

quantum console              # the home page
quantum console /reports     # another page
quantum console --config other.config.yaml

quantum desktop

The same pages in a desktop window (Desktop):

quantum desktop
quantum desktop /reports --width 800 --height 600

quantum package

One file of the application for someone without Quantum: its TUI and its server, with a Python of its own, for Linux, Windows or macOS — any of them made on any system (the TUI's guide). --target web is the TUI alone, for the browser, in the application's static/tui/: its own server serves it at /static/tui/index.html (in the browser).

quantum package projects/kanban                    # dist/kanban-linux.tar.gz
quantum package projects/kanban --target windows   # dist/kanban-windows.zip
quantum package projects/kanban --target macos --with-data --out /tmp/release
quantum package projects/kanban --on desktop --target windows   # a window of its own: kanban-windows-desktop.zip
quantum package projects/kanban --target web       # static/tui/index.html
quantum package projects/kanban --server https://kanban.example.com   # a client: the TUI alone
quantum package projects/kanban --server https://kanban.example.com --target android   # a phone's .apk

quantum check

Parses every page and compiles every query against the database, without running them (quantum check):

quantum check
quantum check --config other.config.yaml

quantum test

Runs the *.test.q files of the app (Testing an App):

quantum test                   # every *.test.q under the current folder
quantum test tests/            # a folder, or files

It exits with 1 when a test fails, so it fits in CI.

quantum migrate

Database migrations in migrations/ (Database Queries):

quantum migrate status
quantum migrate up
quantum migrate down           # the last one
quantum migrate create add_due_date
quantum migrate plan           # compare schema.sql with the migrations

Other commands

quantum admin starts the Quantum Admin. quantum jobs and quantum mq belong to jobs and messaging, which are Experimental (see Stability). quantum pkg packs and installs component folders, but a page cannot import a component from an installed package yet: q:import from= is a folder under paths.components. Their options are in the command-line reference.

Related

• Hot Reload - quantum start --hot-reload
• VS Code Extension - Editor support
• Project Structure - File organization