How to use the ClearRun CLI

Install and sign in

npm install -g @clearrun/cli
clearrun login

clearrun login opens the API keys page and asks you to paste a key. It saves the key on your computer at ~/.config/clearrun/config.json, readable only by you. It does not send the key to ClearRun, so it can't tell you if the key works.

clearrun whoami shows which key is in use (masked). clearrun logout removes the saved key.

You can also set the key yourself. Do not commit it.

export CLEARRUN_API_KEY=YOUR_CLEARRUN_API_KEY

Score text

clearrun score --text "The capital of France is Paris."
clearrun score answer.txt
clearrun score responses/

A folder is searched for .txt, .md and .markdown files.

Fail a build on low scores

Add --threshold:

clearrun score responses/ --threshold 70

The command exits with code 1 if any answer scores below 70, has no score, or fails. Otherwise it exits 0.

To save the rule, add clearrun.config.json:

{
  "paths": ["responses/"],
  "threshold": 70,
  "maxIssues": 3
}

Then run clearrun score with no file. Paths are relative to the config file. --threshold on the command line wins over the file. --json prints the results as JSON for scripts.

Look up a verdict

clearrun verify 6e07586d-e028-43d6-bec3-0f4821b22ca0

This checks the record for that id. It does not score anything, uses no credits, and needs no key.

Which key the CLI uses

It checks, in order: --api-key, then CLEARRUN_API_KEY, then the file from clearrun login, then apiKey in clearrun.config.json.

Node.js 18 or newer is required. The current @clearrun/cli package is 1.2.0. Run clearrun --help for every option.

On an older version?

Check with clearrun --version. Before 0.3.0, clearrun verify scored text and there was no clearrun score. Update with npm install -g @clearrun/cli@latest.