PrelintDocs

CLI

Use Prelint from your terminal. Install the prelint command, sign in, and bind a repository to a project.

The prelint command reads and writes the same decision ledger the dashboard shows. A CI job or a coding agent runs it and reads its JSON.

Install

On macOS or Linux, run one of these:

brew install prelint/tap/prelint
curl -fsSL https://install.prelint.com | sh

Homebrew puts prelint on your PATH. The script does the rest of this section.

The script downloads the binary for your platform, checks its SHA256 against the published SHA256SUMS file, and puts it in ~/.local/bin. If that folder is not on your PATH, the script prints the line to add to your shell profile.

Two variables change what the script does. PRELINT_VERSION pins a release and turns off automatic updates. PRELINT_INSTALL_DIR changes the folder.

curl -fsSL https://install.prelint.com | PRELINT_VERSION=v0.1.0 sh
curl -fsSL https://install.prelint.com | sudo PRELINT_INSTALL_DIR=/usr/local/bin sh

Manual download

Each release on the releases page holds one file per platform and a SHA256SUMS file. Download both. Then check the sum, make the file executable, and move it onto your PATH:

shasum -a 256 -c SHA256SUMS --ignore-missing
chmod +x prelint-macos-arm64
mkdir -p ~/.local/bin
mv prelint-macos-arm64 ~/.local/bin/prelint
PlatformFile
macOS, Apple Siliconprelint-macos-arm64
macOS, Intelprelint-macos-x86_64
Linux, x86_64 (musl)prelint-linux-x86_64-musl
Windows, x86_64prelint-windows-x86_64.exe

The script does not support Windows. Download the .exe and put it on your PATH.

Sign in

prelint login

The command opens your browser. Sign in to Prelint there. The command waits, then stores a session token in ~/.config/prelint/. You sign in once. Every later command reuses the token, and so does a coding agent that runs prelint for you.

If a command needs a login and you have none, the CLI asks on a terminal: "Log in now?" Enter starts the browser login. In a pipe, with JSON output, or with CI set, the command exits 3 instead.

prelint status   # which account is signed in
prelint logout   # delete the token

Bind a repository to a project

Run this anywhere inside the checkout:

prelint init

init does six things:

  1. Finds the repository on the server by its origin remote.
  2. Puts the repository in a project. If the dashboard already set one, the file follows it, and init asks nothing. If not, a picker lists your projects. An admin can create one from the last entry.
  3. Asks to turn on documents and reviews. Enter means yes. It asks only about a switch that is off. Reviews spend credits.
  4. Writes prelint.json at the repository root with the project_id. An existing file keeps its ignore_patterns, author lists, and trigger_mode. A file the server would reject does not stop init. Each problem becomes a checklist item, and the skill fixes it.
  5. Installs the agent skill when the checkout holds a file a coding agent left, such as AGENTS.md, CLAUDE.md, or .cursorrules. When claude or codex is on your PATH, it asks to run the skill now. See Set up the agent skill.
  6. On a Homebrew install, asks once whether to update in the background. See Update.

Then it prints what is left: a connected repository with documents and reviews on, a project, and a valid prelint.json on the default branch. Commit the file. The server reads it from the default branch only.

FlagEffect
--project-id NUse this project. Skips the picker. An error when the dashboard set another project.
--create-project NAMECreate a project and use it. Admins only.
--defaultsWrite the file with no ignore patterns, over an existing file too. Asks nothing.
--ignore-pattern GLOBReplace the ignore list. Repeat the flag for more patterns.
--repository-id IDName the repository when the checkout has no origin remote, or when two connected repositories share its name.
--enable-documentsTurn documents on. Asks nothing.
--enable-reviewsTurn reviews on. Asks nothing.
--no-skillDo not install the skill.
--run-skillRun the skill. Asks nothing. --run-skill=claude or --run-skill=codex names the agent. Exits 9 when the run does not finish.

To see the checklist again, run prelint doctor --repo. See Check the setup.

The other commands read project_id from prelint.json. They do not check the dashboard. If an admin moves the repository to another project, run prelint init again.

Set up the agent skill

Prelint reads every markdown file on the default branch into the decision ledger. Test fixtures, generated docs, and changelogs add noise. Which file is product knowledge is a judgment call, so a coding agent makes it. The prelint-setup skill tells the agent how.

prelint init installs the skill when it finds an agent file. To install it by hand, or again after an update, run:

prelint skill install

It writes .agents/skills/prelint-setup/SKILL.md, which Codex, Cursor, Gemini CLI, and Copilot read. When the checkout has a .claude/ folder or a CLAUDE.md file, it also writes .claude/skills/prelint-setup/SKILL.md for Claude Code. --claude adds that copy anywhere. A copy you edited is kept. --replace overwrites it.

Then open your coding agent in the repository and run the skill:

AgentRun
Claude Code/prelint-setup
Codex$prelint-setup
CursorType / and pick prelint-setup

The skill reads the checkout only. It needs no network and no CLI. First it fixes a prelint.json the server would reject. Then it lists the markdown files, judges each folder, and asks you when it is not sure. Then it writes ignore_patterns into prelint.json and stages the file. Commit the skill file too, so the whole team gets it.

A run that init starts asks nothing. It keeps every file it is not sure about and lists them at the end. Run the skill in your agent to clear those doubts.

Check the setup

When a command fails, run:

prelint doctor

It prints the auth state, environment, project, CLI version, and update state. The report needs no network. ok is true when the next command should reach the server with no action from you.

To check a repository, run this inside the checkout:

prelint doctor --repo

It prints the same checklist as init, and writes nothing. Each item says what is left. Documents that are off count as an item. While an item is left, the command exits 8, so a CI job fails until the setup is done:

prelint doctor --repo                  # exit 8 fails the job
prelint doctor --repo || [ $? -eq 8 ]  # under set -e, allow exit 8

Below the checklist, it says whether the documents became statements. It shows the last scan, the file count, the extraction state per file, the failed files, and the statement counts. With no accepted statement, it names the reason. In JSON, knowledge.reason holds a code, such as scan_running or statements_pending. knowledge.wait is true when the state clears by itself, so an agent checks again later. knowledge.wait_max_seconds caps that wait.

--repository-id ID names the repository, as in init.

Commands

CommandWhat it does
project listProjects you can see.
statement listStatements in the project. Filter with --status, --certainty, or --repository-id.
statement search "..."Statements that match by meaning.
statement accept | reject | confirm --id NAccept a pending statement, reject one, or confirm a stale one.
statement provenance --id NWhere a statement came from and what replaced it.
statement location --id NWhich project holds a statement. Needs no project.
statement set-metadata --id N key=valueSet your own key-value tags on a statement.
statement delete-metadata --id N keyRemove tags from a statement.
ingest --text "..." --source "notes.md"Push text into the decision ledger. --source-date YYYY-MM-DD dates it.
ingestions list | get | deletePast ingestions. get and delete take --id.
topic listTopics in the project.
topic events list | resolveTopic changes that wait for a decision. resolve takes --id, --resolution, and --note.
glossary listGlossary terms. -q filters them.
glossary events list | resolveTerm changes that wait for a decision. Same flags as topic events.
contradictions list | resolveContradictions between statements. Same flags as topic events.
doctorAuth, environment, project, version, and update state. --repo checks the repository. See above.
skill installAdd the agent skill. --claude and --replace, see above.
config set | showLocal settings, such as auto_update.
updateInstall the newest release now.
changelogRelease notes built into the CLI. --version shows one release.

A command finds its project in this order:

  1. The --project-id flag.
  2. prelint.json at the checkout root, or the nearest one above the current folder.
  3. Without both, an error that says to run prelint init.

A list command takes --page and --page-size, from 1 to 100. The JSON holds total and has_more.

Output and exit codes

On a terminal, prelint prints tables. In a pipe, it prints JSON. --format json or --format table forces one.

The JSON has a stable envelope:

{
  "schema_version": "1",
  "kind": "statements",
  "data": { }
}

schema_version changes only when the envelope shape changes. A script can pin to it. A table can change between releases.

An error in JSON mode goes to stderr in the same shape, with an error object and the exit_code.

CodeMeaning
0Success
1Other error
2Usage error, such as a bad flag or a missing argument
3Auth error. Not signed in, session expired, or token rejected
4Network error, such as a timeout
5Not found
6Rate limit
7Server error
8Setup items left. Only doctor --repo returns it. Not an error
9Skill run did not finish. Only init --run-skill returns it. prelint.json is written

Environment variables

NameEffect
PRELINT_ENVTarget environment, production or staging. Same as --env.
PRELINT_OUTPUTForce json or table output.
PRELINT_CONFIG_DIRReplace ~/.config/prelint/.
PRELINT_NO_UPDATE_CHECKAny value turns off the daily update check and the automatic update. CI does the same.
PRELINT_NO_AUTO_UPDATEAny value keeps the check but installs nothing. You get a notice instead.
PRELINT_HOMEBREW_AUTO_UPDATEAny value lets a Homebrew install update in the background.

Update

The CLI updates itself. Once a day, a command checks github.com for a newer release. The check runs in the background and sends only the CLI version. When a newer release exists, the same background process installs it. The command you ran does not wait. The new version runs from your next command, and on a terminal it prints what changed. To read the notes again, run prelint changelog.

A Homebrew install updates itself only when you allow it. prelint init asks once on a terminal. If you say no, the CLI prints a notice once a day. To change the answer, run:

prelint config set homebrew_auto_update true

To update now:

prelint update

On a Homebrew install, it runs brew upgrade prelint/tap/prelint. Both paths check the download against the SHA256 the release publishes.

If an automatic update fails, for example because the install folder needs root, the daily notice shows the error. prelint doctor shows it in update_error.

To turn automatic updates off on a direct install, run prelint config set auto_update false. PRELINT_NO_AUTO_UPDATE=1 turns them off on every install. PRELINT_NO_UPDATE_CHECK=1 turns off the check too.

Report a problem

Open an issue at github.com/prelint/cli/issues, or write to support@prelint.com. Add the output of prelint doctor.

See also