CLI¶

v1.2.0 added a surql CLI (./src/cli/main.ts) for operator-level tasks: migrations, schema inspection, connection diagnostics, and multi-environment orchestration. It is published alongside the library as a Deno binary and as a JSR export (@oneiriq/surql/cli).

Install & invoke¶

deno run \
  --allow-read --allow-write --allow-net --allow-env --allow-sys \
  --allow-run=git,deno \
  jsr:@oneiriq/surql/cli \
  --help

deno task cli --help

deno install --global \
  --allow-read --allow-write --allow-net --allow-env --allow-sys \
  --allow-run=git,deno \
  -n surql \
  jsr:@oneiriq/surql/cli

All subcommands accept --config <path:string> (YAML or TOML). Without --config, settings are resolved from env vars, .env, surql.yaml, and surql.toml via the shared settings loader.

Top level¶

surql                                 # show help
surql --version                       # print CLI version
surql version                         # same
surql --config ./surql.yaml <cmd>     # override config resolution
surql settings                        # dump the resolved settings as JSON

surql migrate¶

Migration lifecycle commands. Most of these require a live database connection; create and validate operate on the filesystem only.

surql migrate squash¶

Squash multiple .surql migrations into one atomic file while preserving checksums and ordering:

surql migrate squash \
  --migrations migrations/ \
  --output migrations/20260101000000_squashed.surql \
  --from 20240101000001 \
  --to   20240315000000 \
  --description "squash_q1"

Flags:

• -m, --migrations <dir> — migrations directory (default migrations).
• -o, --output <path> — output file path (auto-generated if omitted).
• --from <version> — inclusive start version.
• --to <version> — inclusive end version.
• --dry-run — preview without writing.
• --keep-originals — keep original migration files after squash.
• --force — remove the originals as part of the squash.
• --description <text> — description for the squashed migration.

surql schema¶

Schema inspection, validation, visualisation, and drift detection.

Pre-commit integration¶

Generate a pre-commit fragment and paste it into .pre-commit-config.yaml:

surql schema hook-config --schema schemas/ > .pre-commit/surql.yaml

surql db¶

Connectivity diagnostics and ad-hoc queries.

surql orchestrate¶

Deploy migrations across multiple environments. Environment configuration is an array of EnvironmentConfig entries stored in JSON (default: environments.json).

[
  {
    "name": "staging",
    "connection": {
      "host": "staging.db.internal", "port": "8000",
      "namespace": "myapp", "database": "staging",
      "username": "admin", "password": "..."
    }
  },
  {
    "name": "production",
    "connection": {
      "host": "prod.db.internal", "port": "8000",
      "namespace": "myapp", "database": "prod",
      "username": "admin", "password": "..."
    }
  }
]

Strategies map to the orchestration API documented in Orchestration: sequential, parallel, rolling (honours --batch-size), and canary.

surql settings¶

Prints the fully-resolved Settings object (env vars + .env + surql.yaml / surql.toml) as JSON. Use it to verify which config file a CI job is picking up:

surql --config ./ops/surql.production.yaml settings \
  | jq '.database | { host, namespace, database, protocol }'

Embedding the CLI¶

If you need to wrap the CLI in your own Deno task runner, import the run() function from @oneiriq/surql/cli and pass your args. buildRootCommand() is also exposed so tests (or plugin authors) can introspect the command tree.

import { run } from 'jsr:@oneiriq/surql/cli'

await run(['migrate', 'up', '--directory', 'migrations'])

Errors raised from @cliffy/command validation are mapped to the CLI's ExitCode.Usage; everything else resolves to ExitCode.Failure.