staleless check

staleless check

export STALELESS_TOKEN=sls_...
npx staleless check

Everything check reports is state only the server holds: when a person last reviewed a page, what the last publish was, which external links failed twice overnight.

There is nothing to compute locally, so it asks the API.

Flags

--api <url>string

Where the API is. Defaults to the hosted API, or the STALELESS_API environment variable.

--strictflag

Count warnings as failures.

--advisoryflag

Report everything and never fail.

--jsonflag

Machine-readable output.

The token has no flag

Read from STALELESS_TOKEN only, and there is no --token flag on purpose: a runner echoes the command it runs, and a CI log is kept for months.

The token needs docs:read. See Tokens.

What it reports

• pages whose review is overdue;
• pages Pulse marks outdated, with the evidence;
• external links that have failed more than once;
• the last publish, and whether it succeeded;
• OpenAPI sync state, where a document is connected.

In a scheduled job

check is better on a schedule than on a pull request. A pull request should fail for something the pull request did; an overdue review is not that.

name: Documentation health
on:
  schedule:
    - cron: '0 9 * * 1'

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npx staleless check --json > health.json
        env:
          STALELESS_TOKEN: ${{ secrets.STALELESS_TOKEN }}

Exit codes

Code	Meaning
0	Nothing to report.
1	Found problems.
2	Could not run. A missing or rejected token lands here.
3	The API did not answer. Retry.

Note

3 exists so your CI can tell a network blip from a bad token. Retry a 3; fix a 2.