Command line

Command line

The staleless command runs the checks that must work where there is no browser and no session: your CI, failing a build before broken documentation reaches a reader.

npx staleless --help

The five commands

Command	What it answers
audit	Point it at a codebase: a score, and what is missing.
lint	The publish rules, over a checkout. No network.
check	What is wrong in a live workspace right now.
impact	These files changed; which pages describe them.
document	Read the code; say what documentation it would draft.

There is no push

The instinct is staleless push: send my documentation to the host. That is not built and should not be.

You connect the GitHub App and point a project at your own repository and a folder inside it. From then on the repository is the content store, and a merge publishes. There is nothing to push, and a push command would be a second, competing way to change the same files.

Which commands need a network

Command	Network	Token
audit	No	No
lint	No	No
impact	No	No
document --dry	No	No
check	Yes	Yes

lint has no network at all, on purpose. The pull requests that most need checking come from forks, and a fork’s build has no secrets. A check that needed a credential would skip exactly where it matters.

Common flags

--jsonflag

The same answer, for a pull request comment or a dashboard.

--strictflag

Count warnings as failures. Off by default: an error is a site that would be wrong, a warning is something to look at.

--advisoryflag

Report everything and never fail the build.

--fixflag

lint only. Rewrite what has a mechanical repair, then report what is left.

--debugflag

Say what is being asked of the network, on stderr.

Exit codes

Code	Meaning
0	Ran, nothing to report.
1	Ran, and found problems.
2	Could not run, and running it again unchanged will not help.
3	Could not run because the far side did not answer. Worth retrying.

The split between 2 and 3 is for your CI. A 3 is a retry; a 2 is a misconfiguration, and retrying it wastes a runner.

Why the rules are bundled

lint and impact compute over files, and their rules ship inside this one tool rather than as separate packages.

If they were versioned separately you could hold staleless and its rule packages at versions that disagree about what a dead link is. One artifact, one set of rules.