Skip to content

Checking Rules Locally

Once you have rules in your .taskless/ directory, you can run them locally to catch issues before they reach code review.

Run your rules through the project launcher the installer wrote:

Terminal window
./.taskless/bin/cli.mjs check

This scans your codebase and reports any matches. The command exits with code 1 if any error-severity matches are found, making it suitable for CI pipelines. You can scope the scan to specific paths:

Terminal window
./.taskless/bin/cli.mjs check src/foo.ts src/bar.ts

A path that doesn’t exist is skipped and named in a notice, so you can pipe a raw git diff straight in. Run it from the repository root, since git diff paths are relative to the root and a path outside the project is refused:

Terminal window
./.taskless/bin/cli.mjs check $(git diff --name-only main...HEAD)

To measure one rule over the whole project, name it. --rule repeats, and refuses an id no rule directory has:

Terminal window
./.taskless/bin/cli.mjs check --rule no-console-log

check runs the rules Taskless owns, and they behave differently by engine (see Engines):

  • sg rules (.taskless/rules/sg/) are inert ast-grep patterns. They run offline, with no account.
  • vale rules (.taskless/rules/vale/) are equally inert, and run the same way. Checking prose needs no account.
  • Runtime rules (.taskless/rules/runtime/) execute a check.ts, so they run only when that code is verified. When you’re logged out, pass --anonymous, have no GitHub remote, or the service is unavailable, runtime rules are reported but not run. Everything else still runs normally.

Logged in, check also verifies the sg and vale rules Taskless issued, file by file. One that was edited since it was issued does not run, and the check fails naming each changed file. Put it back with rule restore <ruleId> rather than by hand; Security covers why.

check does not run your linters. A rule authored into ESLint, Ruff, RuboCop, or Stylelint is enforced by that tool in your own lint step. Taskless writes it, your toolchain runs it.

check itself never requires authentication. For the full verification model, and why runtime rules are gated this way, see Security.

Flag Effect
--json Machine-readable output (see below)
--rule <id> Run only the named rule; repeat for several
--anonymous Skip runtime rules entirely; sg and vale rules still run
--dangerously-run-scripts Run runtime rules without server verification, trusting local signatures
--timeout <seconds> Per-runtime-check wall-clock bound (default 10)
--include-warnings Under CI, print warnings, infos, and hints too (see below)
--preserve-logs, -l Keep this run’s directory under .taskless/.run/, engine logs included, to debug a rule

--dangerously-run-scripts is a deliberate escape hatch that runs unverified code. See Security before using it.

When the CI environment variable is true or 1, the human-readable output prints only error-severity findings, and ends with a count of the warnings, infos, and hints it left out. They never affect the exit code, and nobody reads them in a job log. --include-warnings prints them anyway. --json always carries every finding.

For machine-readable results, add --json:

Terminal window
./.taskless/bin/cli.mjs check --json

The output is { success, results, skipped?, failures?, notices?, integrity?, entitlement? }. When runtime rules were present but not run (for example, because you’re logged out), the additive skipped array lists them:

{
"success": true,
"results": [],
"skipped": [{ "rule": "env-read", "reason": "not verified (logged out)" }]
}

Surface skipped so a pipeline can tell that runtime rules did not execute.

notices is the advisory array, present when there is something to say: that the rules ran unverified and what would verify them, the paths you passed that do not exist, or a file over 128KB that a Vale rule’s scope would have reached and check skipped rather than let one oversized document consume the Vale run’s time budget. A prose file that Vale cannot parse (broken front matter, for instance) is different: it is reported as a per-file finding with ruleId: "vale-parse-error", and every other file’s findings are still returned.

failures and integrity describe a rule that did not run because it was edited, copied, or unaccounted for. entitlement names runtime rules withheld for your plan.

  • 0: all checks passed, no rules configured, or every path you passed was missing (named in a notice).
  • 1: at least one error-severity match, the scan failed, an issued sg or vale rule was edited or copied under a new id, runtime rules were withheld because your plan does not include them, two engines share a rule id, or a path you passed is outside the project.

Runtime rules skipped because nothing verified them are reported, and never change the exit code.

Add a taskless check step to your pipeline so rules run on every push and pull request. See Continuous Integration for the patterns (full scan vs diff scan), a GitHub Actions reference, and how to enable server-enforced rules in CI.

When you have agent skills installed (see Using Agent Skills), rules from .taskless/ are automatically available to your coding agents. The agents reference these rules during code generation to avoid patterns your team has already flagged.