docs/workflow/cli

CLI reference

One binary. Every command takes a path or a glob and a config; everything else is a flag. Exit codes follow the rule severity in the config.

last updated · apr 18, 2026·10 min readedit on github →

Everything runs through one command. The first positional argument is the subcommand; everything after it is a file path, a glob, or a flag. No global config flag. If you need a non-default config, pass --config.

$ driftlog <command> [path|glob] [flags]

driftlog check

Run all rules. The default.

Scans the repo (or the path you pass) and reports rule violations. Exits 0 on a clean run or one with only warnings, 1 on any error-severity violation.

$ driftlog check
$ driftlog check src/
$ driftlog check --strict --json > drift.json

flags

--strictPromote warnings to errors. Useful during a migration window.

--include <glob>Only scan paths matching the glob. Repeatable.

--exclude <glob>Skip paths matching the glob. Repeatable.

--rule <id>Run only this rule by name or index. Repeatable.

--changed-onlyOnly files changed against base ref. Defaults to origin/main.

--base <ref>Override base ref for --changed-only.

$ driftlog check
Loading .driftlog.yaml
Parsing 2,847 files
Applying 12 rules
2 errors, 1 warning
Drift score 71/100

driftlog fix

Apply autofixes to the repo.Coming in v1.1

Runs the same scan as check, then applies any safe rewrite the rule author marked as autofixable. Prints a diff before writing; pass --yes to skip the prompt in CI.

note

This command is documented for v1.1 and is not implemented in v1.0.0. Running driftlog fix today prints a placeholder message and exits successfully. Documented flags below are accepted as no-ops so scripts written against v1.1 will not error.

$ driftlog fix
$ driftlog fix --rule layers.app --yes
$ driftlog fix --dry-run

flags

--dry-runPrint the diff and exit without writing.

--yesSkip the confirmation prompt. Required in non-TTY environments.

--rule <id>Only apply fixes from the named rule.

$ driftlog fix
Applying autofix to 2 files
ui/Cart.tsx
ui/Review.tsx
Re-running check
All rules passing.

driftlog score

Print the current drift score.

Aggregates rule pass-rates over time into a single 0-100 number. Useful as a one-line PR comment or an SLO probe.

$ driftlog score
$ driftlog score --window 30d --json

flags

--window <duration>Trailing window. Accepts 7d, 30d, 90d. Default 30d.

--rule <id>Score a single rule rather than the whole config.

$ driftlog score
Repo: acme/checkout-service
Score: 87/100
Trend: +22 over 30 days
Top rule: layers.app (93%)
Weakest: cycles.src (68%)

driftlog init

Drop a starter .driftlog.yaml.

Inspects the repo, guesses a layer ordering from your folder structure, and writes a minimal config you can sharpen. Refuses to overwrite an existing config unless you pass --force.

$ driftlog init
$ driftlog init --force --layers ui,domain,infra

flags

--forceOverwrite an existing .driftlog.yaml.

--layers <list>Comma-separated layer names, top-down.

--no-ciSkip the prompt offering to wire up CI.

$ driftlog init
Scanning repo
Detected ui/, domain/, infra/
Wrote .driftlog.yaml

driftlog rule

Manage rules in the config.

Subcommands for adding, listing, and testing rules without hand-editing the YAML. Useful when you are bootstrapping a config across many repos.

$ driftlog rule list
$ driftlog rule new layer
$ driftlog rule test layers.app

flags

listPrint every rule with its scope and severity.

new <type>Append a starter rule of the given type.

test <id>Run a single rule against the repo with verbose tracing.

$ driftlog rule list
layers.app          error  src/**
boundary.billing    error  billing/**, catalog/**
forbidden.no-moment warn   src/**

driftlog ci

Wire up CI in one line.

Generates a CI config tailored to your provider and writes it in place. Always idempotent; rerunning produces the same file.

$ driftlog ci github
$ driftlog ci gitlab --strict
$ driftlog ci circle

flags

githubWrite .github/workflows/driftlog.yml.

gitlabAppend a driftlog stage to .gitlab-ci.yml.

circleAdd a driftlog orb step to .circleci/config.yml.

--strictPass --strict to driftlog check in the generated config.

$ driftlog ci github
Wrote .github/workflows/driftlog.yml
Add this to repo settings -> branch protection

Pre-commit hook

A pre-commit hook keeps drift from landing on a branch in the first place. Driftlog doesn't ship its own git-hook installer — wire it up with husky or lefthook. The recommended command is driftlog check --changed-only so the hook scans only files in the staged commit, not the whole tree — a typical mid-size repo runs in well under a second that way.

# husky/.husky/pre-commit
driftlog check --changed-only

Make it opt-in for the team. Some folks like a tight inner loop; others want to commit fast and rely on CI to catch issues. The hook should be installable, never mandatory — every team member runs pnpm exec husky install (or the lefthook equivalent) themselves. A repo-level setting that force-installs hooks onpnpm install tends to breed workarounds.

If a developer's commit is genuinely time-sensitive (hotfix on a Friday), they can bypass the hook with git commit --no-verify. CI still catches the violation on push — the hook is the cheap fast layer, not the gate.

Global flags

These flags work on every command above.

global

--config <path>Path to config file. Default .driftlog.yaml at repo root.

--cwd <dir>Working directory for resolution. Default $PWD.

--no-colorDisable ANSI color in output. Auto-detected for CI.

--jsonEmit a single JSON document. Mutes human-readable output.

--quietSuppress info/dim lines. Errors and warnings still print.

-v, --verboseVerbose progress including parser timing per file.

-h, --helpPrint help for the current command.

--versionPrint Driftlog version and exit.

← previous

Rules

Changelog