Top-level commands

Commands invoked directly as civex <command>, grouped the same way civex --help groups them.

Start a working area	Description
`demo`	Create a demo project pre-populated with example schemas and records.
`desktop`	Open civex in a window of its own, with a project picker.
`init`	Initialize a new civex project in the given directory.
`license`	Print civex's software license.
`shortcut`	Put a Desktop shortcut that starts civex for this project and opens it.
`update`	Update civex to the latest release.

Work on the current change	Description
`doctor`	Check this civex install and, inside a project, its data.
`resolve`	Identify a resource (schema, dataset, or record) by UUID or prefix.

Collaborate	Description
`clone`	Make a new project that is a copy of an authority's, and keep it in step.
`dump`	Export all schemas, datasets, records, and workflows to a YAML file.
`restore`	Restore schemas, datasets, records, and workflows from a dump file.
`serve`	Start the civex HTTP API server.

Other	Description
`shell`	Start an interactive civex shell (no 'civex' prefix needed).

`civex demo`

Create a demo project pre-populated with example schemas and records.

Usage

civex demo [PATH]

Arguments

Argument	Type	Required	Description
`PATH`	`path`	no	Directory to create the demo project in

`civex desktop`

Open civex in a window of its own, with a project picker.

Needs the desktop extra: uv tool install --force "civex[desktop]".

Usage

civex desktop

`civex init`

Initialize a new civex project in the given directory.

Usage

civex init [OPTIONS] [PATH]

Arguments

Argument	Type	Required	Description
`PATH`	`path`	no	Directory to initialize

Options

Option	Type	Default	Description
`--sqlite`	flag	`false`	Force SQLite instead of Docker PostgreSQL

`civex license`

Print civex's software license.

Usage

civex license

`civex shortcut`

Put a Desktop shortcut that starts civex for this project and opens it.

Usage

civex shortcut

`civex update`

Update civex to the latest release.

Detects whether civex was installed with pipx, uv tool or pip and runs the matching upgrade. Restart any running civex serve afterwards.

Pre-releases are only installed with --pre. Once on one, a plain civex update moves on when the final release is out.

Usage

civex update [OPTIONS]

Options

Option	Type	Default	Description
`--check`	flag	`false`	Only report whether a newer version exists.
`--pre`	flag	`false`	Include pre-releases (release candidates, betas) when looking for a newer version.

`civex doctor`

Check this civex install and, inside a project, its data.

The install checks look for another copy of civex shadowing this one on PATH, for uv, and for a working Python for custom plugins. The project checks look for integrity issues: dangling reference/reference_list values left over from before deletes checked for referrers, and live records that sit under a deleted record (out of sight; civex record restore-above puts one back in place).

With --fix, deletes cached plugin environments that point at a Python that no longer exists (uv rebuilds them the next time the plugin runs).

Usage

civex doctor [OPTIONS]

Options

Option	Type	Default	Description
`--fix`	flag	`false`	Remove cached plugin environments whose Python is gone.

`civex resolve`

Identify a resource (schema, dataset, or record) by UUID or prefix.

Usage

civex resolve ID

Arguments

Argument	Type	Required	Description
`ID`	`str`	yes	UUID or UUID prefix to look up

`civex clone`

Make a new project that is a copy of an authority's, and keep it in step.

Usage

civex clone [OPTIONS] URL [PATH]

Arguments

Argument	Type	Required	Description
`URL`	`str`	yes	The authority's address.
`PATH`	`path`	no	Where to put the copy (default: a new folder here).

Options

Option	Type	Default	Description
`--invite`	`str`		The invite the authority's admin gave. Env: `CIVEX_SYNC_INVITE`. (required)

`civex dump`

Export all schemas, datasets, records, and workflows to a YAML file.

Usage

civex dump [OPTIONS]

Options

Option	Type	Default	Description
`--output`, `-o`	`path`	`civex-dump.yaml`	Destination file
`--no-data`	flag	`false`	Omit records from the export
`--no-workflows`	flag	`false`	Omit workflows and plugins from the export

`civex restore`

Restore schemas, datasets, records, and workflows from a dump file.

Usage

civex restore [OPTIONS] DUMP_FILE

Arguments

Argument	Type	Required	Description
`DUMP_FILE`	`path`	yes	Path to a civex-dump.yaml file

Options

Option	Type	Default	Description
`--yes`, `-y`	flag	`false`	Skip confirmation prompt

`civex serve`

Start the civex HTTP API server.

Usage

civex serve [OPTIONS]

Options

Option	Type	Default	Description
`--host`	`str`	`127.0.0.1`	Bind address
`--port`, `-p`	`int`	`8000`	Port
`--reload`	flag	`false`	Auto-reload on code changes (dev mode)
`--allow-remote`	flag	`false`	Permit binding to a non-loopback address. The server has NO authentication — only use this on a trusted network behind a reverse proxy or firewall.
`--log-level`	`str`	`INFO`	Log level: DEBUG \| INFO \| WARNING \| ERROR. Overrides [logging] in config.toml.
`--open`	flag	`false`	Open the browser once the server is up. If civex is already running on this port, just open the browser.
`--sync-only`	flag	`false`	Serve only what devices following this project call, for an authority on a network: point the HTTPS proxy at this, and run the app itself on this machine.

`civex shell`

Start an interactive civex shell (no 'civex' prefix needed).

Usage

civex shell