ClearRun CLI help

Install the CLI (current package 1.2.0), save a key, score text and files, and use it in CI.

Last updated November 9, 2026

Start here

How to install the ClearRun CLI
Run npm install -g @clearrun/cli, then clearrun --version to check it worked. You need Node.js 18 or newer. Step-by-step help from the ClearRun help center.
How to save your API key with clearrun login
Run clearrun login, then paste your key. The CLI saves it on your computer so you don't have to type it again. Step-by-step help from the ClearRun help center.
How to score text from the command line
Run clearrun score --text "your answer". The CLI sends the text to ClearRun and prints an honesty score from 0 to 100. Read more in the ClearRun help center.
How to fail a build when a score is too low (--threshold)
Add --threshold to clearrun score. If any answer scores below that number, the command exits with code 1, and your CI step fails. From the ClearRun help center.

All CLI articles

How to install the ClearRun CLI
Run npm install -g @clearrun/cli, then clearrun --version to check it worked. You need Node.js 18 or newer. Step-by-step help from the ClearRun help center.
How to run the ClearRun CLI without installing it (npx)
Put npx @clearrun/cli in front of any command, such as npx @clearrun/cli score answer.txt. npx downloads the CLI and runs it. Nothing is installed globally.
How to save your API key with clearrun login
Run clearrun login, then paste your key. The CLI saves it on your computer so you don't have to type it again. Step-by-step help from the ClearRun help center.
How to check which API key the CLI is using (clearrun whoami)
Run clearrun whoami. It prints the key masked to its first and last four characters, and where the CLI found it. A plain answer from the ClearRun help center.
How to remove a saved API key (clearrun logout)
Run clearrun logout. It removes the key that clearrun login saved on your computer. It does not turn the key off. A plain answer from the ClearRun help center.
Does clearrun login check my key with ClearRun?
No. clearrun login saves the key on your computer and does not contact api.clearrun.net. A wrong key is saved without an error. From the ClearRun help center.
Where does the ClearRun CLI look for my API key?
In this order: --api-key, then CLEARRUN_API_KEY, then the file saved by clearrun login, then apiKey in clearrun.config.json. The first one found wins.
How to score text from the command line
Run clearrun score --text "your answer". The CLI sends the text to ClearRun and prints an honesty score from 0 to 100. Read more in the ClearRun help center.
How to score a file from the command line
Run clearrun score answer.txt. The CLI reads the whole file as one answer and scores it. You can list several files in one command. ClearRun help center.
How to score a folder of AI answers
Run clearrun score responses/. The CLI scores every .txt, .md and .markdown file in that folder and its subfolders, one call per file. ClearRun help center.
How to fail a build when a score is too low (--threshold)
Add --threshold to clearrun score. If any answer scores below that number, the command exits with code 1, and your CI step fails. From the ClearRun help center.
How to limit issues per answer (maxIssues)
Set maxIssues in clearrun.config.json. Any answer with more issues than that number fails, and the run exits 1. Step-by-step help from the ClearRun help center.
How to set up clearrun.config.json
Create clearrun.config.json in your project folder with the paths to score and your rules. Then clearrun score with no arguments uses it. Steps inside.
How to use a config file in another folder (--config)
Pass --config path/to/clearrun.config.json. paths in that file are read relative to the file, not to where you run the command. From the ClearRun help center.
How to fix clearrun.config.json errors
Each config error names the problem. Fix that field and run again. The run exits 1 until the file is valid. A plain answer from the ClearRun help center.
How to get JSON output from the ClearRun CLI (--json)
Add --json to clearrun score or clearrun verify. The CLI prints one JSON object with passed and a results list, so scripts can read it. ClearRun help center.
How to point the CLI at another API URL (--base-url)
Pass --base-url with the API address, or set baseUrl in clearrun.config.json. The default is https://api.clearrun.net. Most people never change it. Steps inside.
How to pass an API key on the command line (--api-key), and when not to
clearrun --api-key works and wins over every other key, but it can leak into shell history and CI logs. Use CLEARRUN_API_KEY instead. More in ClearRun help.
How to look up a verdict id from the command line (clearrun verify)
Run clearrun verify 6e07586d-e028-43d6-bec3-0f4821b22ca0. It looks up a past score on ClearRun and prints Verified: yes or no with the verdict. It needs no API key and uses no credits.
What do the ClearRun CLI exit codes mean?
There are two. 0 means every input passed (or every verdict id verified). 1 means something failed: a gate, a lookup, a request, or the command itself.
How to see ClearRun CLI help and version
Run clearrun --help for every command and option, and clearrun --version for the version number. -h and -v work too. Read more in the ClearRun help center.
How to read ClearRun CLI output
Each result shows ClearRun Score (0 to 100, or not determined), a grade, Risk, Issues, and a one-line summary. A plain answer from the ClearRun help center.
Why does the CLI say 'No ClearRun API key is configured'?
The CLI found no key in --api-key, CLEARRUN_API_KEY, your saved login, or clearrun.config.json. Run clearrun login, or set CLEARRUN_API_KEY. Steps inside.
Why does clearrun say 'Unknown command: score'?
Your CLI is older than 0.3.0, which added score. The current package is 1.2.0. Update with npm install -g @clearrun/cli@latest. Steps inside.
Why does clearrun verify say my file is not a verdict id?
clearrun verify looks up a past verdict by id. It does not score text. To score a file, run clearrun score <file> instead. From the ClearRun help center.
Why does the CLI say 'Use either --text or file paths, not both'?
clearrun score takes one kind of input per run: --text or file paths. Remove one, or run the command twice. A plain answer from the ClearRun help center.
Why does the CLI say '--threshold must be a number from 0 to 100'?
The value after --threshold is not a number between 0 and 100. Use a plain number, such as --threshold 70. A plain answer from the ClearRun help center.
Why does the CLI say 'No .txt or .md files found'?
The ClearRun CLI found no .txt, .md or .markdown files in that path. Check the path and the extensions, and that files are not in dot folders or node_modules.
Does the ClearRun CLI have a mock or offline mode?
No. clearrun score always calls api.clearrun.net and needs a key. For local, offline local test scores, use the SDK's mock mode. From the ClearRun help center.
How to use the ClearRun CLI from Node code (scoreText, lookupVerdict)
Import scoreText and lookupVerdict from @clearrun/cli. scoreText uses the apiKey you pass in, then CLEARRUN_API_KEY, then the file saved by clearrun login.

Start here

All CLI articles

Other topics