SurrealQL formatter | Formatter

The surqlfmt command automatically formats SurrealQL files for consistent style and readability.

The surqlfmt tool reformats .surql files to follow a consistent style. It adjusts whitespace, indentation, and keyword casing so that SurrealQL code is easy to read and review.

surqlfmt is a third command-line tool alongside surreal and surrealctl. It is shipped as an npm package rather than as part of the surreal binary, it never connects to a database, and it only reads and writes files.

Installation

The tool can be installed through a single npm install command:

npm install -g @surrealdb/surql-fmt

Usage

surqlfmt [OPTIONS] [FILES]...

Arguments

Name	Description
`[FILES]...`	Files to format, given as paths or glob patterns. Omit them when reading from stdin.

Options

Name	Description
`--write`	Reformat each file in place instead of printing the result.
`--check`	Report whether the files are already formatted, without changing them. Useful in CI.
`--stdin`	Read SurrealQL from standard input and write the formatted result to standard output.
`--indent<WIDTH>`	Number of indent characters per level.
`--indent-char<CHAR>`	Character used for indentation, for example `tab`.
`--max-line-length<LENGTH>`	Column at which the formatter wraps long lines.

The tool prints the reformatted file by default, and reformats a .surql file in place when --write is passed.

# Format a single file
surqlfmt ./query.surql

# Check if files are formatted
surqlfmt --check ./src/**/*.surql

# Format from stdin
cat query.surql | surqlfmt --stdin

# Configure indentation and line length
surqlfmt --indent 4 --indent-char tab --max-line-length 120 *.surql

# Write files in-place
surqlfmt --write ./src/**/*.surql

For the options of the version you have installed, run surqlfmt --help.

When to use the formatter

Before committing - run surqlfmt on any .surql migration or seed files to keep diffs clean.
In CI - add a surqlfmt --check step to catch inconsistencies early.
During development - pipe ad-hoc queries through the formatter for readability.

For the other command-line tools, see the CLI tools overview.