slopvac CLI reference

slopvac lints prose and comments in source files. It checks for AI writing patterns, documentation discipline, technical writing, and general prose. The rules include constraints derived from Simplified Technical English and Orwell.

The linter ships 165 checked rules across 26 categories. The CLI reports findings, scores, and incomplete coverage when selected checks cannot run. The catalogue also carries 66 judgement rules that lint never reports; agents apply them through writing guidance and semantic review.

See the project overview for agent setup and CI integration.

Lint documents · Profiles · Configuration · Scoring · Metrics · Finding triage · Semantic guidance · Rule coverage

Install

The package needs Python 3.11 or later. Choose a persistent installation or run it through uvx.

# Persistent installation.
uv tool install slopvac
slopvac --help
uv tool upgrade slopvac

# One-off run; uvx reuses its cached environment.
uvx slopvac README.md

# Force uvx to use the latest release.
uvx slopvac@latest README.md

# Alternative persistent installation.
pipx install slopvac
pipx upgrade slopvac

After an eligible command finishes, Slopvac prints a notice only if its cache contains a newer stable PyPI release. It refreshes the cache in the background. Set NO_UPDATE_NOTIFIER=1, SLOPVAC_NO_UPDATE_CHECK=1, or DO_NOT_TRACK=1 to disable the check. Slopvac skips prime, non-text output formats, reports written to a file or opened in a browser, non-terminal stderr, or when CI is set.

Vale is optional.

For full deterministic coverage, install Vale 3.15 or later and put it on PATH. We highly recommend doing so because Vale executes most deterministic rules. slopvac generates the Vale configuration and styles.

Without Vale, only the native checks run. Missing Vale, or --no-vale, leaves selected Vale-backed checks UNCHECKED and returns exit 2. Native findings remain in the report, but this is an incomplete check.

Agent steering

Slopvac installs a managed steering block that tells the agent to run slopvac prime, and a thin slopvac-prose skill for harnesses that load project skills. Detailed instructions stay in the installed CLI, which only prints them:

slopvac prime
slopvac prime write
slopvac prime review

slopvac prime prints the lint workflow and says when to run the write and review topics. Both topics are described in semantic guidance.

Two commands write the steering files:

• slopvac init creates slopvac.toml when absent and keeps an existing file unless you pass --force. Repeat --harness <name> to write steering for several harnesses. Without --harness, it writes generic AGENTS.md steering; naming a harness replaces that default, so add --harness agents to keep it. --no-skills writes steering without skills. --skip-agents writes only the config and cannot be combined with --harness or --no-skills.
• slopvac setup <harness> writes, checks, or removes one harness's steering and its skill when available. It never writes slopvac.toml; without a config it uses default [guidance] settings. It works with or without init. slopvac setup <harness> --remove removes Slopvac's block and skill. It deletes the skill directory only when that directory is empty. slopvac setup --list prints each harness with its steering and skill paths.

slopvac init --harness claude --harness omp   # config plus Claude Code and Oh My Pi
slopvac init --harness codex --no-skills      # config plus Codex steering, no skill
slopvac setup kiro                            # one harness; reads config, never writes it

In steering files, both commands keep content outside Slopvac's managed markers. Neither touches a skill file that Slopvac did not write. slopvac setup <harness> --check reports the block as current, missing, stale, or malformed, and the skill as one of those or disabled, without changing files. It exits 0 when everything is current or disabled, 1 when something is missing or stale, and 2 when a file is malformed. slopvac setup <harness> --remove removes its managed steering block and skill. The skill directory is deleted only when empty. slopvac setup --list lists each harness and its steering and skill paths.

Lint documents

slopvac README.md docs/
slopvac --profile strict docs/
slopvac --category prose-craft README.md
slopvac --disable prose-craft.relative-date README.md
slopvac --format json docs/ | jq .summary

slopvac <paths> and slopvac lint <paths> invoke the same command. Repeat --category to select categories or --disable to disable named categories or rules.

Changed lines and fixes

slopvac --diff-base main README.md docs/
slopvac --diff-working-tree README.md docs/
slopvac --fix README.md

--diff-base REV limits findings to added lines in the committed REV...HEAD diff. --diff-working-tree uses the index and working tree relative to HEAD; untracked files are included with all lines in scope.

--fix edits source files using deterministic replacements with a single alternative. It preserves match case and skips replacements that offer multiple choices. In a diff-scoped run, it leaves unchanged lines alone. The CLI lints again after applying replacements. Review the resulting diff for meaning.

Supported file types

Prose directory targets select .md, .mdx, .markdown, .txt, .rst, and .html files. An explicitly named TOML file is accepted only in code-comments mode, where Slopvac checks its comments. Comment-mode directory scans also include TOML files.

RST processing needs Docutils's rst2html or rst2html.py command on PATH. Install it with pip install docutils. A selected RST target without the converter reports an incomplete check and exits 2.

Comment mode

slopvac lint --mode code-comments src/

Comment mode selects supported source extensions and runs comment-safe lexical rules through Vale. It checks ordinary line and block comments, including documentation comments that the language exposes through those scopes. Source code and strings are outside those checks. --comments is an alias for this mode.

Reports retain source paths and finding locations. Directory scans skip unsupported source types with a non-failing note. An explicitly named unsupported file is an error. Configured exclusions still apply.

--mode applies to the whole invocation and cannot appear in [[overrides]]. Comment mode uses the Vale configuration and styles that Slopvac compiles. vale.config and vale.styles settings do not change that configuration.

Profiles

normal is the default. Profiles set rule tiers, severities, and density budgets. Individual rules can have different treatment within a profile.

The density budgets count errors at 1.0 and warnings at 0.5. Category budgets also apply, including in relaxed. All profiles default to max_unicode_dashes = 0. See scoring for the gates.

A tier is separate from configured severity. severity = "off" disables an otherwise admitted category or rule. A project setting can override a profile-default off at the same level: use [categories] for a category setting and [rules] for a rule setting. A rule setting cannot override a category-level off or an excluded tier.

For rules admitted by their tier, explicit category and rule settings can override profile-default severity. An excluded tier remains final. Inspect effective rules with slopvac rules --profile strict or use --explain-config to inspect a file's settings.

Categories also carry recommended_for genres for agent review. Reference material maps to strict, informal text to relaxed, and consumer, internal, and change-communication documents to normal. Genre recommendations do not replace file configuration.

Configuration

slopvac init
slopvac lint --explain-config README.md

The CLI discovers configuration separately for each target by searching its parent directories. It accepts slopvac.toml, .slopvac.toml, or a [tool.slopvac] table in pyproject.toml. --config PATH applies an explicit configuration to all targets.

profile = "normal"
exclude = ["vendor/**", "generated/**"]

[thresholds]
max_errors = 0
max_warnings = 10

[categories]
prose-promotion = "warning"

[rules]
"prose-craft.relative-date" = "error"

[locale]
default = "en-US"

[[overrides]]
files = ["docs/reference/**/*.md", "runbooks/**/*.md"]
profile = "strict"

Agent guidance

[guidance]
write = "auto"             # auto | off
review = "auto"            # auto | ask | off
review_depth = "subagent"  # self | subagent | adversary

write = "off" drops the writing step. review = "ask" prompts before review; review = "off" disables review. The default review_depth = "subagent" uses one fresh-context reviewer pass. The author gives the subagent the document and the slopvac prime review output, plus the original and any source or brief. The subagent runs lint, the semantic checklist, and a fact check, and edits nothing. It reports each finding once with rule id, quoted text, and proposed rewrite, and it lists lost facts and claims stronger than the source. The author fixes or rebuts each finding.

Set review_depth = "self" for an author-run pass, or "adversary" for repeated rounds. Each round gets the earlier rebuttals, and the loop stops when a round reports no finding the author accepts. If no subagent is available, the author runs the pass and reports self (no subagent available). review = "off" still disables review. Guidance keys cannot appear in [[overrides]]. With both modes off, init --harness and setup install no skill. See semantic guidance.

Precedence

Configuration starts with the profile, applies top-level settings, then applies every matching [[overrides]] block in file order. Later blocks replace only the fields they set. Other fields retain their values.

[[overrides]]
files = ["docs/**"]
profile = "strict"

[[overrides]]
files = ["docs/notes/**"]
profile = "relaxed"

A file under docs/notes/ uses relaxed in this example. The last matching block to set profile determines the value. Duplicate override scopes are configuration errors.

--explain-config shows the resolved settings and the blocks that supplied them. Unknown category names or rule IDs cause an error, including inside overrides.

Severity and weight

Severity settings can promote or demote findings. A per-rule setting takes precedence over the category. The string shorthand "prose-craft.relative-date" = "error" is equivalent to a rule table with severity = "error".

A category's minimum_severity raises findings below that level while retaining higher severities. Per-rule overrides still take precedence.

A category with weight = 0 reports findings without contributing to the score, error and warning counts, or density gates when any category has a positive weight. If every category has zero weight, the document score and document-level error, warning, and density thresholds use all categories together. The Unicode dash gate always counts its named findings regardless of category weight.

Spelling

[locale] default accepts en-US, en-GB, or und. Use und to disable spelling checks. The allow array lists spellings the project accepts regardless of locale.

Word blocklist

Project word restrictions need a blocklist:

[vocabulary]
path = "docs/blocklist.toml"

The path is relative to the configuration file. A blocklist entry identifies a word and its part of speech:

[[entries]]
word = "deploy"
pos = "noun"
replacement = "deployment"
reason = "Use the noun deployment for the result of deploying."

Vale's sequence tagger applies the blocklist entry only when its part-of-speech tag matches. Every entry needs a reason. replacement is optional. Invalid or unreadable blocklists are configuration errors.

Use examples/blocklist.toml as a starter. TOML, YAML, and JSON formats work. If vocabulary.path is unset, the project blocklist is inactive. Other spelling and word rules use their configured settings.

Suppress a finding

Use a reason from the rule's exception list:

<!-- slopvac-allow: rule=orwell.stale-figure reason=quotation -->

slopvac explain orwell.stale-figure lists the accepted reasons. An unknown reason or malformed directive produces meta.invalid-suppression.

The annotation covers the following block, such as a paragraph, list entry, or table. <!-- slopvac-disable-next-line --> suppresses all rules in that block. Use <!-- slopvac-disable --> and <!-- slopvac-enable --> around a region. Directives quoted in inline code or fenced blocks do not suppress findings.

Output formats

slopvac docs/
slopvac --format json docs/ | jq .
slopvac --format github docs/
slopvac --format sarif docs/ > out.sarif
slopvac --open docs/
slopvac --out report.html docs/
slopvac --format json --out report.json docs/

The default output is a terminal report. JSON includes findings, document scores, and a summary. github produces workflow annotations. SARIF supports code-scanning integrations.

--open writes a self-contained HTML report and opens it in a browser. --out chooses the destination and implies HTML unless --format selects another format. The HTML report needs no external assets.

Inspect documents[].unchecked in JSON results. An incomplete check can include scores and useful findings, but it cannot report a pass.

Report axes

Reports group findings under prose quality and AI register. AI-register counts separate strong and weak signals. Rules with ai_signal: none contribute to the prose-quality group.

ai_signal_source records the evidence behind a signal: measured, catalog, or unmeasured. These labels do not change scores or gates and do not estimate the probability that a document has an AI author.

Scoring

For documents of at least 60 words:

raw density = findings / words * 100
gating density = (errors + 0.5 * warnings) / words * 100
suggestion penalty = min(15, 2.5 * suggestions / words * 100)

For a category with a positive density budget, its base score decreases linearly from 100 to 70 at the budget. It reaches zero at four times that budget. The scorer then subtracts the suggestion penalty, with a floor of zero.

A zero budget gives a base score of 100 at zero gating density and zero above it. Without a category budget, each unit of gating density costs 10 points.

The document score is the lower of the weighted category mean and the score computed over all scoring categories together. Categories with zero weight do not contribute to the weighted mean. If all categories have zero weight, the weighted mean is 100, so the whole-document score determines the result.

Below 60 words, the scorer uses absolute counts: 20 points per error and 10 per warning. Each suggestion costs 2.5 points, capped at 15. Density fields are zero for these short documents.

What fails a run

Suggestions alone do not trigger the ordinary score or density gates. The Unicode dash limit counts its named findings at any severity. Turning off or suppressing that rule removes those findings from the count.

Incomplete checks take exit 2. Otherwise, a failed gate takes exit 1 and a passing run takes exit 0.

Word counting

Sentence-length checks use STE counting conventions. Numbers with units, abbreviations, quoted spans, and hyphenated terms each count as one word. Parenthesized text counts as one word in its surrounding sentence. Step and paragraph numbers do not count.

See metrics for counting and text-type classification details.

Rules

In the generated rule reference, you can find all 26 categories and profile tiers for the 165 checked rules, followed by the 66 judgement rules with their review questions and examples.

slopvac rules --profile strict
slopvac explain ste-sentences.sentence-not-short-or-clear
slopvac lint --rules-dir ./my-rules docs/

--rules-dir adds project categories over packaged YAML and is repeatable. A project category with the same id replaces the packaged category. Each directory must exist; it can be empty if the packaged rules provide files. Rule files that it contains must be valid.

slopvac rules also includes the spelling rule generated for the configured locale. The YAML rule count excludes that generated rule.

The compiled-rule cache

Compiled Vale styles are cached between runs. Use these commands to inspect or reclaim the cache:

slopvac cache
slopvac cache --prune
slopvac cache --all

--prune removes older compiled trees; --all clears the cache. Set SLOPVAC_CACHE_DIR to choose a location. Otherwise Slopvac uses $XDG_CACHE_HOME/slopvac, or a directory under the platform temporary directory when XDG_CACHE_HOME is unset.

To inspect the compiled styles directly:

slopvac compile --outdir build/vale
slopvac compile --format json
vale --config=build/vale/.vale.ini docs/

The routing report separates Vale, native, and disabled entries. Running Vale directly checks only the compiled Vale subset.

Exit codes

These codes describe deterministic lint runs:

A passing score does not verify factual correctness or establish authorship.

In development

Slopvac is evaluating a separate semantic layer with typed decisions; the current semantic review is a checklist an agent applies, with no model calls from Slopvac. The typed layer would run after the current parser has produced exact spans and deterministic candidates. A provider such as Jev, Laya, Nimble, Kev, or a SemIf-compatible backend would answer bounded questions while Slopvac code keeps ownership of the final policy. The same provider interface would support two jobs: detect semantic-only cases the linter cannot express reliably, and check a finding from the linter against the rule's intended meaning.

A local reranker such as Qwen3-Reranker-0.6B may be tested before the typed provider when candidate volume is high. It is a recall-first prefilter, never the final judge, and filtered candidates must remain visible in coverage measurement. This work lives on the separate feat/judgement-rewrite branch; it is not part of the current CLI or deterministic exit status. See the project overview and issue #162.

Sources

Each rule's provenance identifies its source. The rules include material derived from hardikpandya/stop-slop, independent restatements of STE principles, and Orwell-derived checks. Prose and documentation categories have their own per-rule references.

ASD-STE100 is copyright ASD and an EU registered trademark. This package reproduces none of its rule text, definitions, or examples. Project word restrictions use the blocklist.

License

Apache-2.0. The stop-slop source material is MIT-licensed.