CLI Reference

Command summary

postgrestools

PostgresTools official CLI. Use it to check the health of your project or run it to check single files.

Usage: postgrestools COMMAND ...

Available options:

  • -h, --help —
    Prints help information
  • -V, --version —
    Prints version information

Available commands:

  • version —
    Shows the version information and quit.
  • check —
    Runs everything to the requested files.
  • start —
    Starts the daemon server process.
  • stop —
    Stops the daemon server process.
  • init —
    Bootstraps a new project. Creates a configuration file with some defaults.
  • lsp-proxy —
    Acts as a server for the Language Server Protocol over stdin/stdout.
  • clean —
    Cleans the logs emitted by the daemon.

postgrestools version

Shows the version information and quit.

Usage: postgrestools version

Global options applied to all commands

  • --colors=<off|force> —
    Set the formatting mode for markup: "off" prints everything as plain text, "force" forces the formatting of markup using ANSI even if the console output is determined to be incompatible
  • --use-server —
    Connect to a running instance of the daemon server.
  • --skip-db —
    Skip connecting to the database and only run checks that don't require a database connection.
  • --verbose —
    Print additional diagnostics, and some diagnostics show more information. Also, print out what files were processed and which ones were modified.
  • --config-path=PATH —
    Set the file path to the configuration file, or the directory path to find postgrestools.jsonc. If used, it disables the default configuration file resolution.
  • --max-diagnostics=<none|<NUMBER>> —
    Cap the amount of diagnostics displayed. When none is provided, the limit is lifted. [default: 20]
  • --skip-errors —
    Skip over files containing syntax errors instead of emitting an error diagnostic.
  • --no-errors-on-unmatched —
    Silence errors that would be emitted in case no files were processed during the execution of the command.
  • --error-on-warnings —
    Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
  • --reporter=<json|json-pretty|github|junit|summary|gitlab> —
    Allows to change how diagnostics and summary are reported.
  • --log-level=<none|debug|info|warn|error> —
    The level of logging. In order, from the most verbose to the least verbose: debug, info, warn, error.

The value none won't show any logging.

[default: none]

  • --log-kind=<pretty|compact|json> —
    How the log should look like. [default: pretty]
  • --diagnostic-level=<info|warn|error> —
    The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing --diagnostic-level=error will cause Postgres Tools to print only diagnostics that contain only errors. [default: info]

Available options:

  • -h, --help —
    Prints help information

postgrestools check

Runs everything to the requested files.

Usage: postgrestools check [--staged] [--changed] [--since=REF] [PATH]...

The configuration that is contained inside the configuration file.

  • --vcs-enabled=<true|false> —
    Whether we should integrate itself with the VCS client
  • --vcs-client-kind=<git> —
    The kind of client.
  • --vcs-use-ignore-file=<true|false> —
    Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.
  • --vcs-root=PATH —
    The folder where we should check for VCS files. By default, we will use the same folder where postgrestools.jsonc was found.

If we can't find the configuration, it will attempt to use the current working directory. If no current working directory can't be found, we won't use the VCS integration, and a diagnostic will be emitted

  • --vcs-default-branch=BRANCH —
    The main branch of the project
  • --files-max-size=NUMBER —
    The maximum allowed size for source code files in bytes. Files above this limit will be ignored for performance reasons. Defaults to 1 MiB
  • --migrations-dir=ARG —
    The directory where the migration files are stored
  • --after=ARG —
    Ignore any migrations before this timestamp
  • --host=ARG —
    The host of the database.
  • --port=ARG —
    The port of the database.
  • --username=ARG —
    The username to connect to the database.
  • --password=ARG —
    The password to connect to the database.
  • --database=ARG —
    The name of the database.
  • --conn_timeout_secs=ARG —
    The connection timeout in seconds. [default: Some(10)]

Global options applied to all commands

  • --colors=<off|force> —
    Set the formatting mode for markup: "off" prints everything as plain text, "force" forces the formatting of markup using ANSI even if the console output is determined to be incompatible
  • --use-server —
    Connect to a running instance of the daemon server.
  • --skip-db —
    Skip connecting to the database and only run checks that don't require a database connection.
  • --verbose —
    Print additional diagnostics, and some diagnostics show more information. Also, print out what files were processed and which ones were modified.
  • --config-path=PATH —
    Set the file path to the configuration file, or the directory path to find postgrestools.jsonc. If used, it disables the default configuration file resolution.
  • --max-diagnostics=<none|<NUMBER>> —
    Cap the amount of diagnostics displayed. When none is provided, the limit is lifted. [default: 20]
  • --skip-errors —
    Skip over files containing syntax errors instead of emitting an error diagnostic.
  • --no-errors-on-unmatched —
    Silence errors that would be emitted in case no files were processed during the execution of the command.
  • --error-on-warnings —
    Tell Postgres Tools to exit with an error code if some diagnostics emit warnings.
  • --reporter=<json|json-pretty|github|junit|summary|gitlab> —
    Allows to change how diagnostics and summary are reported.
  • --log-level=<none|debug|info|warn|error> —
    The level of logging. In order, from the most verbose to the least verbose: debug, info, warn, error.

The value none won't show any logging.

[default: none]

  • --log-kind=<pretty|compact|json> —
    How the log should look like. [default: pretty]
  • --diagnostic-level=<info|warn|error> —
    The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing --diagnostic-level=error will cause Postgres Tools to print only diagnostics that contain only errors. [default: info]

Available positional items:

  • PATH —
    Single file, single path or list of paths

Available options:

  • --stdin-file-path=PATH —
    Use this option when you want to format code piped from stdin, and print the output to stdout.

The file doesn't need to exist on disk, what matters is the extension of the file. Based on the extension, we know how to check the code.

Example: echo 'let a;' | pgt_cli check --stdin-file-path=test.sql

  • --staged —
    When set to true, only the files that have been staged (the ones prepared to be committed) will be linted. This option should be used when working locally.
  • --changed —
    When set to true, only the files that have been changed compared to your defaultBranch configuration will be linted. This option should be used in CI environments.
  • --since=REF —
    Use this to specify the base branch to compare against when you're using the --changed flag and the defaultBranch is not set in your postgrestools.jsonc
  • -h, --help —
    Prints help information

postgrestools start

Starts the daemon server process.

Usage: postgrestools start [--config-path=PATH]

Available options:

  • --log-prefix-name=STRING —
    Allows to change the prefix applied to the file name of the logs. Uses environment variable PGT_LOG_PREFIX_NAME [default: server.log]
  • --log-path=PATH —
    Allows to change the folder where logs are stored. Uses environment variable PGT_LOG_PATH
  • --config-path=PATH —
    Allows to set a custom file path to the configuration file, or a custom directory path to find postgrestools.jsonc Uses environment variable PGT_LOG_PREFIX_NAME
  • -h, --help —
    Prints help information

postgrestools stop

Stops the daemon server process.

Usage: postgrestools stop

Available options:

  • -h, --help —
    Prints help information

postgrestools init

Bootstraps a new project. Creates a configuration file with some defaults.

Usage: postgrestools init

Available options:

  • -h, --help —
    Prints help information

postgrestools lsp-proxy

Acts as a server for the Language Server Protocol over stdin/stdout.

Usage: postgrestools lsp-proxy [--config-path=PATH]

Available options:

  • --log-prefix-name=STRING —
    Allows to change the prefix applied to the file name of the logs. Uses environment variable PGT_LOG_PREFIX_NAME [default: server.log]
  • --log-path=PATH —
    Allows to change the folder where logs are stored. Uses environment variable PGT_LOG_PATH
  • --config-path=PATH —
    Allows to set a custom file path to the configuration file, or a custom directory path to find postgrestools.jsonc Uses environment variable PGT_CONFIG_PATH
  • -h, --help —
    Prints help information

postgrestools clean

Cleans the logs emitted by the daemon.

Usage: postgrestools clean

Available options:

  • -h, --help —
    Prints help information