Command line

The quantum command. Every command takes -h / --help. The Guide explains the everyday ones: CLI commands.

Option	Meaning
--version	The installed version.
-h, --help	The commands and their options.

quantum run

Execute a .q file, or run an application in one of its versions (--on).

Argument	Meaning	Default	Values
file	.q file to execute, or with --on the application (its folder)
--on	The application's version: web (the browser), desktop (a window of its own), tui (a text screen drawn by Godot) or terminal (UI-18)		web, desktop, tui, terminal
--page	With --on desktop or terminal: the page to open (default: /)	/
--port	With --on web: the port (overrides the config)
--debug	Debug mode
--config	Config file	quantum.config.yaml
--target	UI target (for type="ui" apps): html or textual (layout only)	html	html, textual
--out	For a hive or a screen: write what it compiles to here (projects/<id>/hive or projects/<id>/screen by default)
--check	For a game: after the build, open the Godot project headless and fail on any script error (needs Godot; python scripts/godot.py install)
--watch	For a game: play it in Godot, and each time the .q (or a file beside it) is saved, build again and go on where the game was, under the new build

Specified by: IA-7 · CFG-1 · UI-0 · UI-2 · UI-8 · UI-18 · UI-20

quantum start

Start web server.

Argument	Meaning	Default	Values
--port	Port (overrides config)
--config	Config file	quantum.config.yaml
--debug	Print the traceback when the server fails to start (debug mode is server.debug in the config)
--hot-reload	Reload the open pages when a component or static file changes
--hot-reload-port	WebSocket port for --hot-reload (default 35729)

Specified by: ROUTE-1 · CFG-1 · APP-1 · UI-18 · DEV-1 · DEV-4 · TEST-1

quantum stop

Stop running web server.

Specified by: RUN-3

quantum console

Open the application's pages in the terminal.

Argument	Meaning	Default	Values
[path]	Page to open (default: /)	/
--config	Config file	quantum.config.yaml

Specified by: UI-3 · UI-15 · UI-18

quantum pixel

Open the application's pages on the Hive's screen (the machine's console).

Argument	Meaning	Default	Values
[path]	Page to open (default: /)	/
--config	Config file	quantum.config.yaml
--socket	hive-screen's pixel socket (default: /run/hive-screen/pixel.sock)	/run/hive-screen/pixel.sock

Specified by: UI-15

quantum check

Check pages, SQL and query fields against the database.

Argument	Meaning	Default	Values
--config	Config file	quantum.config.yaml
--openapi	Also write the API's OpenAPI document (what /api/openapi.json serves) to FILE

Specified by: ROUTE-4 · API-7 · UI-10 · DEV-3

quantum test

Run the app's *.test.q tests.

Argument	Meaning	Default	Values
[paths]	Test files or folders to search for *.test.q (default: .)	.

Specified by: APP-2 · TEST-1

quantum desktop

Open the application's pages in a desktop window.

Argument	Meaning	Default	Values
[path]	Page to open (default: /)	/
--config	Config file	quantum.config.yaml
--width	Window width (default: 1024)	1024
--height	Window height (default: 720)	720

Specified by: UI-4 · UI-8 · UI-18 · UI-22

quantum package

Make one file to hand someone: the application's TUI and its server, for a system.

Argument	Meaning	Default	Values
app	the application's folder (its quantum.config.yaml)
--on	its program: the TUI (default), or a window of its own (Windows, macOS)	tui	tui, desktop
--target	the system it runs on (default: linux); any can be made on any; web: the TUI in the browser, in the application's static/tui/, which its server serves; android, ios: a phone, with --server	linux	linux, windows, macos, web, android, ios
--out	where the file goes (default: the application's dist/; for web, its static/tui/)
--server	a client of the application hosted at URL (https://...): its program alone, no server or Python of its own beside a TUI
--with-data	carry its SQLite databases as they are (left out by default: its migrations make them when it starts)

Specified by: UI-8 · UI-22

quantum play

Play a game step by step (or serve it to an agent, --mcp).

Argument	Meaning	Default	Values
[game]	a game of projects/ (rpg, chess...) or a .q
--mcp	serve the play tools over MCP (stdio)
--frames	draw on a virtual display, for "frame"
--live	the game runs at its own speed, not request by request
--host	host a networked game on this port (live)
--join	join a networked game, a person's or another agent's (live)
--seat	with --join: the seat to sit in (else the lowest free)
--lang	the language of the game's texts, when it has it (pt, es...)
--transport	the network's transport (websocket: the one a browser joins)		enet, websocket

quantum gameserver

Run a world: a q:application type="gameserver" (PLAN_GAME_SERVER.md).

quantum gameserver run

Run a world (a q:application type="gameserver").

Argument	Meaning	Default	Values
file	the world's .q
--host		127.0.0.1
--port		7700
--step	a test world: it ticks only when a client says "step"
--data	where the world keeps its snapshot and log (.quantum/gameserver/<name>)
--snapshot-every		300.0
--stats	say the numbers (the ticks' time, what went out) every so often
--no-minds	the NPCs say the lines of their fallback, and no model is asked
--engine	what runs the world: python; rust (native/world, PLAN_WORLD_ENGINE.md: the views and the network on every core); or native (the world itself too: its state, its tick and its rules, E3); else QUANTUM_WORLD_ENGINE, else native where the engine is built here (pip install ./native/world), else python		python, rust, native
--rules	what runs its blocks: python (the interpreter), or machine (the Rust engine's, as bytecode: PLAN_WORLD_ENGINE.md, E2); else QUANTUM_WORLD_RULES, else python		python, machine
--digest-every	write the world's digest into its log every so often, for conform to check a replay against (a digest copies the whole world: a pause of its own)

quantum gameserver conform

Run a world's log again on an engine, against the record or another engine, and say the first tick where they differ (PLAN_WORLD_ENGINE.md).

Argument	Meaning	Default	Values
file	the world's .q
--data	its snapshot and log (.quantum/gameserver/<name>)
--engine	the engine to run it on (python; rust: its frames; machine: its rules as bytecode; native: its state and tick)	python
--against	a second engine: the two compared tick by tick, frames and all
--digest-every	compare the two worlds' digests every so many ticks (0: only at the end)	1

quantum gameserver bytecode

Each expression of a world as the Rust engine's machine runs it, or each block with --blocks (PLAN_WORLD_ENGINE.md, E2).

Argument	Meaning	Default	Values
file	the world's .q
--expression	this expression alone (its braces off)
--blocks	each block instead: its q:commands, q:functions and rules, statement by statement
--summary	only how many compiled

quantum gameserver check

Read a world against its schema, and say what is wrong.

Argument	Meaning	Default	Values
file

quantum gameserver ticket

A ticket into a world of a site's accounts (accounts="site"), signed with QUANTUM_WORLD_SECRET from the environment.

Argument	Meaning	Default	Values
--account	the site's id of the account (its hero: hero:<it>)
--name	the name its hero shows (else the account)
--seconds	how long it lasts (a minute)	60.0

quantum relay

Where browsers meet to play a networked game (rooms over WebSocket).

Argument	Meaning	Default	Values
--port	the port players join (default 8765)	8765
--bind	the address to listen on (default all)	0.0.0.0
--cert	a TLS certificate (PEM): the relay is then wss://, as a page on HTTPS needs
--key	the certificate's private key (PEM)
--projects	the folder of games (default: projects/)
--max-rooms	rooms open at once (default 50)	50
--builds	a folder that keeps the compiled games between runs
--prebuild	compile every networked game before serving
--prebuild-only	compile them, then stop (a container image)

quantum playtest

An agent tries to finish each game (projects/games.json goals).

Argument	Meaning	Default	Values
[games]	games of projects/ with a goal (all, by default)
--out	where the report and the tapes go (default ./playtest)	playtest
--model	the Claude model that plays	claude-opus-5-5
--effort	how hard the model thinks before each call	medium	low, medium, high, xhigh, max

quantum admin

Start the Quantum Admin.

Argument	Meaning	Default	Values
--port	Port (default 8090)	8090
--data	Folder for the admin database and settings (default ./.quantum-admin)	.quantum-admin
--root	Folder the project paths are relative to (default: current folder)	.

quantum pkg

Package management commands.

quantum pkg init

Initialize a new package.

Argument	Meaning	Default	Values
[path]	Directory to initialize (default: current directory)	.
-n, --name	Package name (default: directory name)
-d, --description	Package description
-a, --author	Package author
-l, --license	License identifier (default: MIT)	MIT

quantum pkg publish

Create publishable package archive.

Argument	Meaning	Default	Values
[path]	Package directory (default: current directory)	.

quantum pkg install

Install a package.

Argument	Meaning	Default	Values
source	Package source (local path or git URL)
-v, --version	Specific version to install
--no-deps	Skip dependency resolution

quantum pkg remove

Remove an installed package.

Argument	Meaning	Default	Values
name	Package name to remove
-v, --version	Specific version to remove (default: all versions)

quantum pkg list

List installed packages.

quantum pkg search

Search installed packages.

Argument	Meaning	Default	Values
query	Search query

quantum pkg info

Show package details.

Argument	Meaning	Default	Values
name	Package name
-v, --version	Specific version

quantum jobs

Manage scheduled jobs and job queues.

quantum jobs list

List all scheduled jobs.

Argument	Meaning	Default	Values
--status	Filter by status	all	all, active, paused, pending, running, failed
--queue	Filter by queue name
--format	Output format	table	table, json

quantum jobs status

Get detailed job status.

Argument	Meaning	Default	Values
name	Job name
--format	Output format	table	table, json

quantum jobs run

Run a job manually.

Argument	Meaning	Default	Values
name	Job name
--sync	Wait for job to complete
--params	JSON parameters for the job

quantum jobs pause

Pause a scheduled job.

Argument	Meaning	Default	Values
name	Job name

quantum jobs resume

Resume a paused job.

Argument	Meaning	Default	Values
name	Job name

quantum jobs cancel

Cancel a running or pending job.

Argument	Meaning	Default	Values
name	Job name or job ID

quantum jobs history

View job execution history.

Argument	Meaning	Default	Values
[name]	Job name (optional, shows all if not specified)
--limit	Number of entries to show	10
--status		all	all, success, failed
--format	Output format	table	table, json

quantum jobs worker

Start a job worker process.

quantum jobs worker start

Start worker.

Argument	Meaning	Default	Values
--queue	Queue(s) to process (comma-separated)	default
--concurrency	Number of concurrent workers	4
--poll-interval	Poll interval in seconds	1.0

quantum jobs worker stop

Stop worker.

Argument	Meaning	Default	Values
--graceful	Wait for running jobs to complete

quantum jobs queues

Manage job queues.

quantum jobs queues list

List all queues.

Argument	Meaning	Default	Values
--format		table	table, json

quantum jobs queues purge

Purge all jobs from a queue.

Argument	Meaning	Default	Values
name	Queue name
--status		all	all, pending, failed

quantum jobs queues stats

Show queue statistics.

Argument	Meaning	Default	Values
[name]	Queue name (optional)

quantum mq

Message queue operations.

quantum mq queues

Manage message queues.

quantum mq queues list

List all queues.

Argument	Meaning	Default	Values
--format		table	table, json

quantum mq queues create

Create a queue.

Argument	Meaning	Default	Values
name	Queue name
--durable	Durable queue	True
--dlq	Dead letter queue name
--ttl	Message TTL in milliseconds

quantum mq queues delete

Delete a queue.

Argument	Meaning	Default	Values
name	Queue name
--force	Force delete even if not empty

quantum mq queues purge

Purge all messages from a queue.

Argument	Meaning	Default	Values
name	Queue name

quantum mq queues peek

Peek messages without consuming.

Argument	Meaning	Default	Values
name	Queue name
--limit	Number of messages to peek	10
--format		table	table, json

quantum mq topics

Manage topics.

quantum mq topics list

List all topics.

Argument	Meaning	Default	Values
--format		table	table, json

quantum mq publish

Publish a message to a topic.

Argument	Meaning	Default	Values
topic	Topic name
[message]	Message body (JSON string or plain text)
--file	Read message from file
--header	Add header (format: key=value)

quantum mq send

Send a message to a queue.

Argument	Meaning	Default	Values
queue	Queue name
[message]	Message body (JSON string or plain text)
--file	Read message from file
--header	Add header (format: key=value)
--delay	Delay in seconds before delivery

quantum mq consume

Consume messages from a queue.

Argument	Meaning	Default	Values
queue	Queue name
--limit	Number of messages to consume	1
--timeout	Timeout in seconds	5
--ack	Auto-acknowledge messages
--format		json	table, json

quantum mq subscribe

Subscribe to a topic (real-time).

Argument	Meaning	Default	Values
topic	Topic pattern (supports wildcards)
--format		json	raw, json

quantum mq worker

Start a message worker.

Argument	Meaning	Default	Values
--queues	Queues to consume (comma-separated)
--handler	Handler script (.q file)
--concurrency	Number of concurrent consumers	4
--prefetch	Prefetch count	1

quantum mq stats

Show message broker statistics.

Argument	Meaning	Default	Values
--format		table	table, json

quantum mq info

Show connection information.

quantum migrate

Database migration commands.

Argument	Meaning	Default	Values
--datasource	Datasource from quantum.config.yaml (default: the only one declared)

Specified by: DB-6 · DB-7 · DB-10 · CFG-3

quantum migrate status

Show migration status.

quantum migrate up

Apply pending migrations.

Argument	Meaning	Default	Values
-n, --count	Number of migrations to apply

Specified by: DB-7

quantum migrate down

Rollback migrations.

Argument	Meaning	Default	Values
-n, --count	Number of migrations to rollback	1

quantum migrate create

Create a new migration.

Argument	Meaning	Default	Values
name	Migration name

quantum migrate plan

Compare schema.sql with the migrations and plan the migration.

Argument	Meaning	Default	Values
--schema	Schema file (default: schema.sql)	schema.sql
--write	Save the plan as migration V00N_NAME
--yes	Do not ask before writing
--allow-data-loss	Write a plan that drops tables or columns

Specified by: DB-10