// reference

CLI

The surrealguard binary analyzes a workspace of .surql sources and reports findings as text or JSON. It has three subcommands: init, check, and generate.

surrealguard init surrealguard check [--json] surrealguard generate [--out <path>]

init

Writes a starter surrealguard.toml in the current directory. If one already exists, it is left untouched.

$ surrealguard init
Created surrealguard.toml

check

Discovers every .surql/.surrealql file under the workspace root (the nearest ancestor directory containing surrealguard.toml), analyzes them in sorted path order against the schema they define, and reports findings. Severity is resolved through the workspace policy — warnings_as_errors promotion and [lints] levels (named lints, specific codes like E1002, and family wildcards like "7xxx") apply here, at the consumption edge.

$ surrealguard check
Checking SurrealQL sources...
error[E1002]: unknown field `team` on table `user`
 --> queries/users.surql
  ...
check failed: 1 error(s), 1 diagnostic(s)

--json

Emits machine-readable diagnostics instead of the text renderer. The document has two top-level keys, summary and diagnostics:

{
  "summary": {
    "sources_checked": 2,
    "diagnostics": 1,
    "errors": 1
  },
  "diagnostics": [
    {
      "code": "E1002",
      "severity": "error",
      "source": "queries/users.surql",
      "range": { "start": 41, "end": 45 },
      "message": "unknown field `team` on table `user`",
      "help": ["did you mean `name`?"],
      "related": [
        {
          "source": "schema/user.surql",
          "range": { "start": 0, "end": 26 },
          "message": "table `user` defined here"
        }
      ]
    }
  ]
}

Field	Type	Notes
summary.sources_checked	number	Count of analyzed sources.
summary.diagnostics	number	Findings that survived policy (errors + warnings + hints).
summary.errors	number	Error-severity findings; non-zero fails the check.
code	string	Severity-prefixed code — `E` error, `W` warning, `I` hint, `S` syntax (e.g. `E1002`, `W4022`, `I7007`, `S0001`). The prefix reflects the resolved severity, so a promoted warning renders as `E…`.
severity	string	`"error"`, `"warning"`, or `"hint"`.
source	string	The source path/id the span belongs to.
range	{ start, end }	Byte offsets into that source — precise enough for surgical inline edits.
message	string	The finding message.
help	string[]	Zero or more help lines.
related	object[]	Related spans, each `{ source, range, message }` — e.g. where a table was defined.

On a clean run the diagnostics array is empty and only the summary is populated; the diagnostics array is filled when the check fails. The help and related arrays are always present, often empty.

generate

Scans host-language files for embedded SurrealQL, analyzes each query against the workspace schema, and writes a TypeScript module that re-exports a ready SurrealGuardClient and augments its query registry. Host files are discovered by extension — .ts, .tsx, .js, .jsx, .svelte, .vue, .astro — honoring the same ignore patterns as .surql discovery.

# the file re-exports a runtime value, so write it to a .ts
$ surrealguard generate --out src/surrealguard.generated.ts
Generated src/surrealguard.generated.ts

The emitted file both re-exports SurrealGuardClient and augments @surrealguard/client. Import the client from that one file — that also loads the augmentation, so every db.query("…") resolves the result and params of each analyzed query from its exact text, with no separate side-import. See the TypeScript page.

Exit codes

Code	Meaning
0	Success — no error-severity findings survived policy (warnings and hints do not fail the check unless `warnings_as_errors` promotes them).
1	The check found one or more error-severity findings, or a command failed (missing/invalid config, unreadable source, I/O error).

In JSON mode the process still exits 1 on a failing check, but the diagnostics are printed to stdout as JSON rather than to stderr as text — so a wrapper can parse findings on failure and read the exit code as a pass/fail signal.