Skip to content

CLI

The surql binary ships under the cli feature flag. It is a thin wrapper over the library - every side-effect is delegated to an existing public function.

cargo install oneiriq-surql --features cli

Global flags

Every subcommand accepts:

Flag Purpose
--config <PATH> Read settings from this TOML file (or the Cargo.toml in this directory).
-v, --verbose Emit extra diagnostic output for subcommands that support it.
--help Standard clap help.
--version Print the crate version (propagated to every subcommand).

Without --config, the standard layered lookup runs: environment variables, .env, then the [package.metadata.surql] table of the nearest Cargo.toml above the current directory.

With --config <PATH>, the [package.metadata.surql] table is read from the named file (any name, such as prod.toml, or a directory holding a Cargo.toml) together with the .env beside it; SURQL_* environment variables still take precedence over the file. The file must exist, parse, and contain the table. Anything else (a missing file, invalid TOML, a file without the table) is an error rather than a silent fall back to the defaults.

Exit codes

Code Meaning
0 Success.
1 Operation failure (SurqlError bubbled up), including a migration that failed to apply or roll back, and a declined or impossible confirmation.
2 Usage error (enforced by clap's argument parser), including arguments that are not valid UTF-8.

Confirmation prompts

Commands that destroy data ask before they run: db reset, bucket rm, bucket delete, and orchestrate deploy (unless --dry-run). Answer y or yes to go ahead; anything else aborts with exit code 1. --yes (-y) skips the prompt. When stdin is not a terminal (CI, pipes) there is nobody to answer, so these commands refuse to run unless --yes is given.

Subcommand tree

surql
|- version
|- db
|   |- init
|   |- ping
|   |- info      [--json]
|   |- reset     [--yes]
|   |- query     [<SURQL> | --file PATH]
|   |- version
|- migrate
|   |- up        [--target VERSION] [--dry-run]
|   |- down      [--target VERSION] [--dry-run]
|   |- status
|   |- rehash    [<VERSION>...]
|   |- history
|   |- create    <description> [--schema-dir PATH]
|   |- validate  [<VERSION>]
|   |- generate  [--from VERSION] [--to VERSION]
|   |- squash    <from> <to> [-o PATH] [--dry-run]
|- schema
|   |- show       [<TABLE>]
|   |- diff       [--from PATH] [--to PATH]
|   |- generate   [-o PATH]
|   |- sync       [--dry-run]
|   |- export     [-f json|yaml] [-o PATH]
|   |- tables
|   |- inspect    <TABLE>
|   |- validate
|   |- check
|   |- hook-config
|   |- watch
|   |- visualize  [--theme modern|dark|forest|minimal]
|   |             [-f mermaid|graphviz|ascii]
|   |             [-o PATH]
|- bucket
|   |- define    <NAME> [--backend B] [--readonly] [--comment C] [--if-not-exists]
|   |- list
|   |- rm        <NAME> [--yes]
|   |- put       <BUCKET> <KEY> (--text T | --file PATH) [--if-not-exists]
|   |- get       <BUCKET> <KEY> [-o PATH]
|   |- delete    <BUCKET> <KEY> [--yes]
|   |- exists    <BUCKET> <KEY>
|   |- files     <BUCKET>
|- orchestrate
    |- deploy    [--plan PATH] [--strategy sequential|parallel|rolling|canary]
    |            [--environments LIST] [--dry-run] [--approve] [--yes]
    |            [--no-auto-rollback]
    |- status    [--plan PATH]
    |- validate  [--plan PATH]

surql db

Database utility commands. Each one opens a short-lived connection from the resolved Settings.

  • surql db init - ensure the _migration_history table exists.
  • surql db ping - connect and issue INFO FOR DB.
  • surql db info [--json] - print resolved namespace / database / URL. --json emits a machine-readable payload.
  • surql db reset [--yes] - drop every table in the current database (prompts for confirmation unless --yes is passed). Table names are quoted, so a name such as foo-bar or one containing ; is removed as a name and never run as SurrealQL.
  • surql db query [<SURQL>] [--file PATH] - execute an inline or file-loaded SurrealQL statement and pretty-print the result.
  • surql db version - print the server's INFO FOR DB version line.

surql migrate

Wraps the migration runtime. Mirrors the surql-py migrate typer group.

  • surql migrate up [--target VERSION] [--dry-run] - apply pending migrations up to and including --target (defaults to the latest).
  • surql migrate down [--target VERSION] [--dry-run] - roll back to and including --target.

Both stop at the first migration that fails, print the status table, and exit with code 1 naming the failed version. up (and --dry-run) refuses to start while an applied migration's file differs from the checksum recorded when it was applied, warning about each one. - surql migrate status - show applied vs pending counts for the configured migrations directory; an applied migration whose file was edited since is shown as modified, with a warning. - surql migrate rehash [<VERSION>...] - record the current checksum of modified migrations (all of them, or the listed versions), accepting an edit that needs no applying. Runs nothing against the schema. - surql migrate history - dump the _migration_history rows. - surql migrate create <description> [--schema-dir PATH] - scaffold a blank migration file with -- @metadata / -- @up / -- @down section markers. Slug-cases <description> for the filename. - surql migrate validate [<VERSION>] - structural validation (section markers, version format, checksum). Optional single-version focus. - surql migrate generate [--from VERSION] [--to VERSION] - render a diff-based migration by comparing two snapshot versions on disk. - surql migrate squash <FROM> <TO> [-o PATH] [--dry-run] - squash a contiguous version range into one migration file.

surql schema

Wraps the schema registry, parser, validator, visualiser, and hook helpers.

  • surql schema show [<TABLE>] - execute INFO FOR DB (or INFO FOR TABLE <TABLE>) and print JSON.
  • surql schema diff [--from PATH] [--to PATH] - compare two snapshot files. Defaults (from = latest snapshot, to = live DB) allow bare surql schema diff for drift detection.
  • surql schema generate [-o PATH] - emit the DEFINE SurrealQL for every registered table and edge.
  • surql schema sync [--dry-run] - placeholder for code-to-database synchronisation (stub; will land in a follow-up).
  • surql schema export [-f json|yaml] [-o PATH] - export the live schema to disk. yaml currently emits raw SurrealQL for parity with surql-py's YAML output target.
  • surql schema tables - list every table in the live database.
  • surql schema inspect <TABLE> - show fields / indexes / events / permissions for a single table.
  • surql schema validate - confirm the registered schema matches the live database.
  • surql schema check - detect schema drift against the latest snapshot. Intended for CI.
  • surql schema hook-config - emit a .pre-commit-config.yaml fragment running schema drift checks.
  • surql schema watch - filesystem watcher (requires the watcher feature; shows a helpful message otherwise).
  • surql schema visualize [--theme modern|dark|forest|minimal] [-f mermaid|graphviz|ascii] [-o PATH] - render the registry as a diagram. Defaults to Mermaid with the modern theme.

surql bucket

Object-storage buckets and their files (SurrealDB v3 files). define, list, and rm manage bucket definitions; put, get, delete, exists, and files work on the files inside a bucket. rm (which drops the bucket and every file in it) and delete ask for confirmation unless --yes is passed.

surql orchestrate

Wraps crate::orchestration. Requires the orchestration feature (implied by cli).

  • surql orchestrate deploy [--plan PATH] [--strategy sequential|parallel|rolling|canary] [--environments LIST] [--dry-run] [--approve] [--yes] [--no-auto-rollback] - apply migrations across environments declared in the plan file (default environments.json, format in Orchestration). Each environment receives only the migrations its history does not record yet. --environments accepts a comma-separated subset (blanks and repeats are dropped); omitted, every registered environment is included. --approve is required when a target environment has require_approval. After a failure, what this run applied is rolled back everywhere unless --no-auto-rollback is given. The command asks for confirmation (see above) and exits 1 unless every environment ends deployed; the table shows the versions applied and rolled back per environment.
  • surql orchestrate status [--plan PATH] - show a health table for each environment in the plan.
  • surql orchestrate validate [--plan PATH] - parse the plan and run connectivity checks without applying anything.

What's next