Commands
Every ranwhat command
Nineteen commands in one tool. Only login, whoami and logout work with an account, update and push need a Plus token, and the other fourteen need neither. Start with check: it reads what your agents ran and what they left on disk, and changes nothing.
A bare ranwhat lists them all.
watch, clean and scan each have a page of their own. The other sixteen are below, and every flag is at the end.
ranwhat · find out what your AI agents actually did check watch and clean in one pass, changing nothing watch what your agents already ran on this machine ignore stop listing actions you expected; all: only new ones from now on clean credentials sitting in plaintext in agent transcripts sources every agent ranwhat reads, and where it looked reach MCP servers and credential files your agents can reach scan the authority a set of credentials carries live the same, asked of each token's own provider callers who used a key, from the provider's own log revoke take back what your agents are allowed (asks first) demo see the output without setting anything up bench run ranwhat's detection on made-up data, and score it update refresh the capability catalogue (needs Plus) login link this machine to your ranwhat.com account whoami which account, organisation and plan this machine uses logout unlink this machine and delete its token push send this machine's findings to your account, as metadata only hook opt in: ask before a high-risk Claude Code call runs ledger keep a tamper-evident record of what watch flagged, on this machine Start here: uvx ranwhat check uvx ranwhat demo No account needed. live, callers, --pull-usage and clean's revoke ask only the provider that issued each token, and update, login, whoami, logout and push talk only to ranwhat.com. push sends derived metadata only, and only when you run it. Everything else reads locally and sends nothing. Full options: uvx ranwhat --help
check: watch and clean in one pass.
The one to start with. It reads every agent's history for the last 30 days and reports both halves: the actions watch flags, and the secrets clean finds. Every secret it finds is hidden in what it prints.
It never changes a file: check --apply is refused, and masking is left to clean. --json prints the actions and the secrets as one document. It exits with status 2 when it found no history to read, so a script can tell a machine with nothing on it from a clean one, and 1 on an error. With --fail-on high it exits 3 when it finds anything that high or higher, and --sarif PATH writes the findings for code scanning, every secret masked. In CI, the GitHub Action runs it with both. For Claude Code, a flagged action also says when part of it, such as a URL, appeared earlier in the same session: in the output of a web fetch, an MCP tool or a file it read, or in your own message. That is where the text was seen, not proof it caused the call, and the output itself is never quoted.

Flags: --days N, --source ID, --path ID=PATH, --root PATH, --state-dir PATH, --json, --fail-on SEVERITY, --sarif PATH, --ignore PATH, --no-ignore.
ignore: stop listing what you expected.
Every action watch and check list has an id, the 16 characters at the end of its line. ignore ID leaves that action out of later reports, and ignore all leaves out every action listed now, so later runs list only what is new.
$ ranwhat ignore 3fa9c2d81b7e4a06 Package or release published (publish, critical) 2026-10-20 03:33 Claude Code npm publish ran in ~/work/mylib Leave out of later reports: 1 this action only 2 `npm publish` run in ~/work/mylib or below it, until 2027-10-20 c cancel ranwhat> 2 Added to ~/.ranwhat/ignore (line 14): publish 'npm publish' in=~/work/mylib until=2027-10-20
Both write ~/.ranwhat/ignore, a plain-text file you can read and edit, one entry a line: an action's id, or a rule with the command it leaves out, word for word, where it ran (in=) and until when (until=). A * stands for any run of characters within one word. ignore alone lists the file, and exits 3 when a line in it cannot be read; ignore - reads the ids from watch --json on stdin, so a cron job alerts on each new action once.
Every report says how many actions the file left out, and by which line, --no-ignore lists them all again, and --fail-on counts only what is listed. A secret is never left out: clean masks it, or keeps it. A critical action is left out only by its id, or by an entry that names the program in full, with in= and an until= no more than 400 days ahead. A change an agent makes to the file, or to anything else that decides what ranwhat reports, is always listed, until you acknowledge it on a terminal. The hook never reads the file, so a call you left out of reports is still asked about.
Flags: --days N, --source ID, --path ID=PATH, --root PATH, --state-dir PATH, --ignore PATH, --no-interactive, --json.
sources: every agent it reads, and where it looked.
Thirty agents, each from where it keeps its history. sources says which it found on this machine, the folders it checked, and whether clean can mask secrets there or only read them.
ranwhat sources · the agents ranwhat reads Claude Code (claude-code): found, 1 transcript ~/.claude/projects (default) clean can mask it Codex (codex): found, 1 session ~/.codex (default) clean can mask it GitHub Copilot CLI (copilot-cli): not found ~/.copilot (default) … Point an agent elsewhere with --path ID=PATH; --source ID reads only that one.
check, watch and clean read them all by default. --source ID reads only that agent, and --path ID=PATH reads one from somewhere else, a backup or a copy from another machine. The watch page lists every agent. On one machine, sources also shows which of those thirty agents have run here, going by the history each one left. It does not see an agent ranwhat does not read.
Flags: --source ID, --path ID=PATH, --json.
reach: MCP servers and credential files your agents can reach.
reach reads the MCP server configuration agents keep on disk and says what each server launches or connects to. Then it lists the credential files an agent could read that no Claude Code deny rule covers, and prints the rules that would.
ranwhat reach · what your agents can reach MCP servers 2 github Claude Code, user scope ~/.claude.json runs npx -y @modelcontextprotocol/server-github ! secret inline in env GITHUB_PERSONAL_ACCESS_TOKEN: <ghp…x4> (GitHub personal access token). Move it to the environment and rotate it. ! unpinned: npx fetches @modelcontextprotocol/server-github at its newest version on every start … Credential files an agent can read 2 ~/.aws/credentials AWS credentials ~/code/app/.env env file Deny them Add these to permissions.deny in ~/.claude/settings.json (nothing was written): { "permissions": { "deny": [ "Read(~/.aws/credentials)", "Read(//**/.env)" ] } }
Servers come from Claude Code's ~/.claude.json, managed-mcp.json and each project's .mcp.json, and the MCP configs of Claude Desktop, Cursor, VS Code, Gemini CLI, Qwen Code, GitHub Copilot CLI, Windsurf and Codex. It flags a secret written inline in env, an argument, a header or the URL, masked the way clean masks one; a package npx or uvx fetches with no exact version; a remote URL; and a project .mcp.json Claude Code starts without asking. It reads the configuration, not the server's code or its tool descriptions.
Credential files are .env files, private keys and token files under each project Claude Code knows and the current directory, and ~/.aws/credentials, ~/.ssh/id_* and the like in your home folder. Only paths are printed, never what is in them. It writes no settings: copy the block into place yourself. A Read rule stops Claude's file tools and the Bash file commands Claude Code recognises; the .env guide covers the rest. reach DIR looks at one project.
Flags: --json.
live: the same scan, asked of each token's provider.
scan scores the credentials a profile file describes. live asks the tokens themselves: each one goes to the provider that issued it, for read-only introspection, and nowhere else.
It reads GitHub, Google, Slack and Stripe tokens from the environment: RANWHAT_GITHUB_TOKEN, RANWHAT_GOOGLE_TOKEN, RANWHAT_SLACK_TOKEN and RANWHAT_STRIPE_TOKEN. The matching flags work too, but a token on the command line is visible to every user on the machine through ps, and lands in your shell history. --pull-usage also reads which grants were used, from each provider's own record.
Flags: --pull-usage, --github-org ORG, --window-days N, --controls PATH, --html PATH, --json.
callers: was the key used by someone else?
clean says a key leaked. Only the provider can say whether anyone used it. callers asks the provider's own log for the calls made with one key and groups them by where they came from. Read-only.
No calls in the window means none that log recorded, not none at all. If a caller is not yours, rotate the key at the provider first.
Flags: --aws-key-id ID, --aws-profile NAME, --aws-region REGION, --github-org ORG, --mine CIDR, --window-days N, --json.
revoke: take back what an agent was allowed.
Every allow rule is a call that no longer asks you. revoke reads Claude Code's settings and lists the grants that let an agent act on its own, then takes them back when you say so.
Flags: --apply, --scope SCOPE, --json.
demo: a whole report, with nothing to set up.
demo runs scan on a profile that ships with ranwhat: an agent called support-copilot, holding Google, GitHub, AWS, Slack and Stripe credentials. Read a report before you point ranwhat at anything of yours.
--html report.html writes it as a page as well: the example report is that file, published as it comes out. Nothing goes online.
Flags: --html PATH, --json.
bench: what ranwhat catches, on made-up data.
bench builds a Claude Code session and the credential files it printed, in a temporary directory, with fake secrets drawn from a seed. It runs the detection check, watch and clean use over it, and scores what they report against an answer key.
update: a newer capability catalogue.
scan, live and demo rate each scope against a catalogue of what it allows, and one ships with ranwhat. update fetches a newer one for a Plus subscription, which is live now at €12 a month per organisation.
$ uvx ranwhat update --status No feed cached. The catalogue bundled with 0.10.0 is in use. Plus gets new scopes the day they are added; the next free release gets them too: https://ranwhat.com/pricing
It sends ranwhat's own server your token and nothing else. ranwhat login saves a token for this machine where update reads it. A CI token goes in RANWHAT_TOKEN, and so can a subscription token emailed before accounts, or pass that once with --token and --save-token. --status stays offline.
On a terminal, scan, live and update --status may add one dim line about the feed, on stderr and never with --json. RANWHAT_NO_HINTS=1 turns it off.
Flags: --token TOKEN, --save-token, --status.
login, whoami, logout: link a machine to an account.
Optional: nothing else here needs an account. login gives this machine a token of its own from your account at account.ranwhat.com, which update then uses while the account's organisation is on Plus, so no shared token is copied from machine to machine.
$ uvx ranwhat login $ uvx ranwhat whoami $ uvx ranwhat logout
login prints a code and https://ranwhat.com/device, and opens that page in your browser when it can. Sign in there, type the code, name the machine and approve it, which asks for an emailed code typed in the last 15 minutes, and the machine's token is saved at ~/.ranwhat/token, readable by you alone. The code is never in a link, so a link someone sends you cannot approve a terminal. Type a code only because you ran login yourself, just then.
whoami shows the account, organisation, role, plan and machine name a token belongs to. logout asks the server to revoke this machine's token, then deletes it; a shared token, a subscription's or a CI token, is only deleted here. Machines can also be named and revoked on the account page, and a terminal's token unused for 90 days is revoked by itself.
They talk to feed.ranwhat.com and nowhere else, and send a code or the token, never a hostname, operating system, user name or machine identifier.
Flags: --force, --no-browser (login), --token TOKEN (whoami), --local (logout).
push: send this machine's findings to your account.
A Plus feature, and only ever something you run: push reads what watch reads, leaves out what your ignore file leaves out, and sends the result to your account, so the findings of every linked machine can be read side by side at account.ranwhat.com. It is never run by the hook, by check or by watch.
$ uvx ranwhat push --dry-run $ uvx ranwhat push
What it sends is derived metadata: for each flagged action, the rule id and severity of each rule it tripped, a 16-character action id (a hash, not the action; where an agent writes no call id, a guess at a plain command can be checked against it), the agent and the time in UTC, and counts, ranwhat's version and the window in days. The machine is the token that signs the request. It never sends a command, a path, evidence, a working directory, a session id, file contents, a secret, your hostname or your user name, and the server refuses a document with any other field. --dry-run prints the exact JSON and sends nothing; without it, push says what it will send and asks, and on a pipe it refuses unless you pass --yes.
It goes only to feed.ranwhat.com, over HTTPS, with this machine's token from ranwhat login (or a CI token in RANWHAT_TOKEN). An organisation on Free is refused, and nothing is stored. Plus keeps each machine's latest push whole and a summary of the pushes before it for 30 days, at most 30; that is not the 13-month record, which is a separate feature that is still coming. Everyone in the organisation can read it, and logout or revoking the machine deletes what it pushed. The privacy page has the rest.
Flags: --dry-run, --yes, --days N, --json, --source ID, --path ID=PATH, --root PATH, --state-dir PATH, --ignore PATH.
hook: ask before the call, not after.
Every other command works after the fact, and the agent never knows. hook install is the opt-in exception: it adds a PreToolUse hook to Claude Code's settings, and each tool call watch would rate high or critical then waits for your yes before it runs.
$ uv tool install ranwhat $ ranwhat hook install $ ranwhat hook status $ ranwhat hook uninstall
It runs watch's own rules on the call, on your machine, and sends nothing anywhere. A call no rule rates high or critical gets no answer, so Claude Code decides as it would have without the hook. If the hook itself fails, the call goes ahead. --mode deny refuses critical calls outright and still asks for high ones, for an agent you check on only now and then. RANWHAT_HOOK=0 lets everything through for one session.
It needs a lasting install, uv tool install, pipx install or pip install, because Claude Code runs it again on every call; a uvx run is refused. Each check takes about a fifth of a second. --scope project writes .claude/settings.json for everyone on the repository, --scope local .claude/settings.local.json for you alone.
ledger: a record that shows if it was changed.
ledger record reads what watch reads and appends one line to ~/.ranwhat/ledger.jsonl for each flagged action it has not recorded yet. Each line carries the SHA-256 of the line before it, so a line that is edited, taken out or moved no longer fits, and ledger verify names the first one that does not.
$ ranwhat ledger record $ ranwhat ledger verify $ ranwhat ledger verify --head HASH $ ranwhat ledger show
A line holds the same five facts push sends and nothing else: the action’s id (a hash), the agent, the time, and the rule and severity of each hit, with its place in the file, when it was written and the hashes. No command, path, evidence or secret. It runs on your machine, sends nothing, and only record writes the file, which ranwhat makes with mode 0600. The ignore file applies, as in watch.
What a chain cannot show: lines cut off its end, or a file written again whole by someone who can write to it, leave a chain that still fits. record prints the head, the hash of the last line; keep it somewhere else, and verify --head HASH then finds both. A ledger that does not verify is not added to. Exit status 0 when it verifies, 3 when it does not, 1 on an error.
Flags: --head, --json, and for record --days, --source, --ignore.
Every flag, and the commands that take it.
Flags go before or after the command. A flag a command does not take is refused, not ignored.
| Flag | Commands | What it does |
|---|---|---|
--days N |
check, watch, clean, ignore, push, ledger record | How far back to read each agent's history, in days. 30 by default. |
--seed N |
bench | Draw the made-up secrets from this seed, a whole number from 0, so a run can be repeated. 2026 by default. Another seed gives other values and the same expectations. |
--source ID |
check, watch, clean, ignore, push, ledger record, sources | Read only this agent, and repeat it for more; every agent by default. IDs: claude-code, codex, gemini, antigravity, copilot-cli, vscode-copilot, cursor, windsurf, cline, roo, kilo, opencode, continue, aider, goose, zed, warp, amazon-q, qwen, codebuddy, grok, droid, kimi-code, kimi, pi, omp, muse-code, mistral-vibe, dsh, openclaw. |
--path ID=PATH |
check, watch, clean, ignore, push, ledger record, sources | Read this agent's history from PATH instead of its default place, one per agent. sources says what each PATH is. |
--root PATH |
check, watch, clean, ignore, push, ledger record | Claude Code's transcript directory, ~/.claude/projects by default. The same as --path claude-code=PATH. |
--state-dir PATH |
check, watch, clean, ignore, push, ledger record | OpenClaw's state directory, ~/.openclaw by default. The same as --path openclaw=PATH. |
--json |
every command but update, login, whoami and logout; push only with --dry-run or --yes; hook only with status | Print the result as JSON instead of the report. |
--apply |
clean, revoke | clean: mask everything found without asking, after a backup to ~/.ranwhat/backups. check refuses it. revoke: take back what it lists, keeping a copy of each settings file beside it. |
--no-interactive |
clean, ignore | clean: report and exit, instead of opening the review session. ignore: add the action's id without asking. |
--ignore PATH |
check, watch, ignore, push, ledger record | Use the ignore file at PATH, such as a repository's .ranwhatignore, instead of ~/.ranwhat/ignore. check and watch exit 1 when it cannot be read; ignore makes it. |
--no-ignore |
check, watch | Leave nothing out, and mark each action the ignore file would leave out with the line that does. |
--fail-on SEVERITY |
check, watch, clean | Exit with status 3 when anything at or above medium, high or critical is found. Every secret clean finds is critical, masked or not. 1 stays an error and 2 nothing read, and either wins over 3. |
--sarif PATH |
check, watch, clean | Also write what was found to PATH as SARIF 2.1.0, for code scanning. Each secret is in it as the report shows it, masked. |
--html PATH |
demo, scan, live | Write the report as a page to PATH as well. |
--pull-usage |
scan, live | Read which grants were used from each provider's own record, read only: AWS, GitHub, Google and Stripe. Slack has no usage pull. |
--aws-profile NAME |
scan, with --pull-usage; callers | The AWS CLI profile to read usage or CloudTrail with. It needs the aws command on your PATH. |
--github-org ORG |
scan and live, with --pull-usage; callers | The GitHub organisation whose audit log holds the usage, or the calls made with a token. GitHub needs it. |
--window-days N |
scan and live, with --pull-usage; callers | How far back to read usage or calls, in days. 90 by default; CloudTrail keeps 90 at most. |
--aws-key-id ID |
callers | The AWS access key ID to look up, by default the one --aws-profile signs with. The ID names the key; it is not the secret. |
--aws-region REGION |
callers | A region to read CloudTrail in. Repeatable. us-east-1 is always read as well, since IAM and STS calls are logged there. |
--mine CIDR |
callers | An address or range that is yours. Repeatable, or comma-separated. Callers outside every one are flagged. |
--github, --google, --slack, --stripe TOKEN |
live, and --pull-usage | A token for that provider. Prefer RANWHAT_GITHUB_TOKEN and the like: a value given as a flag is visible to every user on the machine through ps, and lands in your shell history. |
--controls PATH |
live | A controls JSON to pair with what the tokens report. |
--token TOKEN |
update, whoami | A subscription or CI token to use instead of the saved one. Prefer RANWHAT_TOKEN, ranwhat login, or saving it once with --save-token: a value given as a flag is visible to every user on the machine through ps. |
--save-token |
update | Write the token to ~/.ranwhat/token, readable by you alone, so later runs need no flag. |
--status |
update | Report the cached catalogue and exit, without going online. |
--force |
login | Replace the token this machine already has, and ask the server to revoke the one it replaced. |
--no-browser |
login | Print the page to open without opening a browser. None is opened over SSH or without a display either. |
--local |
logout | Delete the saved token without asking the server to revoke it; revoke it on the account page instead. |
--dry-run |
push | Print the exact JSON push would send and exit, without a token and without going online. |
--yes |
push | Send without asking first. Without it push asks on a terminal and refuses on a pipe. |
--head HASH |
ledger verify | Also require the ledger to end at this hash, the head ledger record printed, so lines cut off its end are found. |
--scope SCOPE |
hook, revoke | Which Claude Code settings file: user (~/.claude/settings.json, or $CLAUDE_CONFIG_DIR/settings.json when that is set; the default), project (.claude/settings.json here) or local (.claude/settings.local.json here). hook status shows all three without it. |
--mode MODE |
hook install | ask, the default, makes each call watch would rate high or critical wait for your yes. deny refuses the critical ones and still asks for the high ones. |