# SurrealQL 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`](/docs/reference/cli/surrealdb-cli/overview.md) and [`surrealctl`](/docs/reference/cli/surrealctl/overview.md). 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](https://www.npmjs.com/package/@surrealdb/surql-fmt):

```bash
npm install -g @surrealdb/surql-fmt
```

## Usage

<Synopsis>
surqlfmt [OPTIONS] [FILES]...
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[FILES]...",
            "description": "Files to format, given as paths or glob patterns. Omit them when reading from stdin."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--write",
            "description": "Reformat each file in place instead of printing the result."
        },
        {
            "name": "--check",
            "description": "Report whether the files are already formatted, without changing them. Useful in CI."
        },
        {
            "name": "--stdin",
            "description": "Read SurrealQL from standard input and write the formatted result to standard output."
        },
        {
            "name": "--indent",
            "value": "<WIDTH>",
            "description": "Number of indent characters per level."
        },
        {
            "name": "--indent-char",
            "value": "<CHAR>",
            "description": "Character used for indentation, for example `tab`."
        },
        {
            "name": "--max-line-length",
            "value": "<LENGTH>",
            "description": "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.

```bash
# 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](/docs/reference/cli.md).