Skip to content

Developers · CLI

Linting Rules

Last updated 18 November 2026

How the Insites CLI linter and audit check your code, and how to configure them.

The Insites CLI has two tools that check your code before it reaches a site. This page describes the CLI 6.4.1.

  • The linter, , parses your Liquid and reports errors and warnings. Run it yourself, in your editor, or in CI.
  • The audit, , looks for deprecated code and files in the wrong place. Every deploy runs it first.

The Linter

insites-cli check run
insites-cli check run app/views/pages

Problems are grouped by file, with the line that causes each one. The command exits with 1 when it finds a problem and 0 when your code is clean, so you can use it in CI or a pre-commit hook. For its options, see Commands and Options.

Every run reports how many files the linter read, as , in the text summary and in the JSON output. When it read no files, for example because the path is wrong, the command exits with 1. A check that read nothing never passes as clean.

The Configuration File

Create a configuration file in your project folder:

insites-cli check init

This writes . It uses the recommended checks, and lists every setting as a comment so you can see what you can change:

extends: insites-check:recommended
ignore:
  - node_modules/**

To turn a check off, or change how serious it is, add it to the file:

UnusedAssign:
  enabled: false
ImgWidthAndHeight:
  severity: 1

Severity 0 is an error and 1 is a warning. The CLI also reads a linter configuration file under another name, and asks you to rename it to .

Turning a Check Off in Your Code

Use a Liquid comment to turn checks off for part of a file. Name one or more checks, separated by commas, or name none to turn off every check.

{% # insites-check-disable UnusedAssign %}
{% assign spare = 1 %}
{% # insites-check-enable UnusedAssign %}

{% # insites-check-disable-next-line UndefinedObject %}
{{ legacy_value }}
  • turns checks off from that point.
  • turns them back on.
  • turns them off for the next line only.

What the Linter Checks

The recommended set includes these checks, among others:

CheckLevelWhat it reports
LiquidHTMLSyntaxErrorErrorLiquid or HTML that cannot be parsed
UnknownFilterErrorA filter that does not exist. If you know it is valid, run first.
MissingPartialErrorA partial that is rendered or included but does not exist
GraphQLCheckErrorA GraphQL file that is not valid
ModuleRouteClashErrorA page that takes the address of a page an Insites module ships. See below.
ReservedNameErrorA page at an address the platform uses itself. See below.
ReservedParameterNameWarningA form field, query string or read that uses the name or . Insites reserves both names.
DeprecatedTag, DeprecatedFilterWarningA tag or filter that Insites has retired
UnusedAssignWarningA variable that is assigned but never used
OrphanedPartialWarningA partial that nothing uses

To see every check and its settings, open the file that writes.

Addresses You Should Not Take

A module page's address. The Insites modules ship their own pages, most of them under , plus the welcome page and the error pages , , , and . If you add a page with the same address, method and format, the site does not refuse it. Your page silently takes over the module page. If you delete your file later, the module page is deleted too. To change the welcome or error pages, edit the existing file in or instead. The linter reports this as ModuleRouteClash.

Platform addresses. The platform itself serves these addresses. Do not create pages there. The linter reports this as ReservedName.

  • , ,
  • , ,
  • ,
  • , , ,

Custom endpoints made with the API module. The API module refuses an endpoint whose address starts with one of 21 words, such as , , or . This applies only to endpoints made through that module. An ordinary page at or deploys and works.

In Your Editor

The same linter runs as a language server. Point your editor at as the language server for files. You then get hover help, completions, go to definition and the linter's problems as you type. You never run this command yourself, so it is hidden from the help.

The Audit

insites-cli audit

The audit takes no options. It reads and and reports:

  • Deprecated tags and filters, each with the current tag or filter to use instead, such as for running a query.
  • Deprecated keys:
    • left on in a page
    • Brackets after an input name
    • , replaced by
    • in a form, replaced by
    • , replaced by
    • , replaced by
    • in an API call, renamed to
    • A model name that is not
  • File types: a folder that holds files with the wrong extension.
  • Duplicates: a partial and an underscore twin at the same path.
  • File names with characters that are not allowed.
  • Orphaned partials: partials that no or uses.

The audit always exits with 0, even when a rule fires. To fail a CI step on it, check that its summary line says A deploy skips the audit when the environment variable is .