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.

01 / Overview

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.

uvx ranwhat
  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
02 / check

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.

$ uvx ranwhat check

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.

ranwhat check in a terminal: 6 secrets found in Claude Code, Codex and Gemini CLI transcripts, each shown only as a short hint with where it was read
The secrets half of check: each one shown only as a hint, with the agent and the file it came from. Made-up history.

Flags: --days N, --source ID, --path ID=PATH, --root PATH, --state-dir PATH, --json, --fail-on SEVERITY, --sarif PATH, --ignore PATH, --no-ignore.

03 / 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
$ 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.

04 / sources

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
  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.

05 / reach

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.

$ uvx ranwhat reach
ranwhat reach
  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.

06 / live

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.

$ uvx ranwhat live

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.

07 / callers

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.

$ uvx ranwhat callers --mine 198.51.100.0/24
AWS CloudTrail, by access key ID, through the aws CLI: each call's address, client and action, for the last 90 days. Management events only, unless a trail also records data events. It needs cloudtrail:LookupEvents.
GitHub An organisation's audit log, searched by the token's hash, with --github-org. It needs GitHub Enterprise Cloud, and shows addresses only where the enterprise has turned on IP disclosure.
Stripe, Google, Slack No caller log ranwhat can read. It says so, and where the provider shows one to a person instead.
Yours Give your addresses or ranges with --mine, for an office, a VPN or CI. Callers outside them are flagged. Without it nothing is called foreign, since ranwhat does not look up your address: that would mean asking someone else.

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.

08 / revoke

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.

$ uvx ranwhat revoke
What it lists bypassPermissions as the default mode, enableAllProjectMcpServers, an allow rule for any shell command, for curl, rm, git push, ssh and the like, or for reading or editing a credential file.
Where Your user settings, and this project's shared and local ones. --scope picks one.
Changing them Nothing changes until --apply. Then a copy of each file is kept beside it as settings.json.ranwhat-backup, and the file is rewritten the way hook install writes it. Restart Claude Code afterwards.
A leaked token Revoked from clean's review with revoke N, where its value is. GitHub, Slack and Google let a token be revoked with one call; ranwhat asks you to type yes, then sends it to that provider alone. Anything else is rolled in the provider's dashboard: open N.

Flags: --apply, --scope SCOPE, --json.

09 / demo

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.

$ uvx ranwhat demo

--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.

10 / bench

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.

$ uvx ranwhat bench
What it scores Planted secrets clean must find, decoys it must leave alone (digests, UUIDs, the AWS and Stripe documentation keys, placeholders), risky calls watch must rate under the right rule, and ordinary calls it must not flag. It also checks that no planted value, nor its leading, trailing or middle characters, is in what ranwhat printed for the run.
What it lists apart What ranwhat is known not to catch, such as a script downloaded in one call and run in a later one. Those are never counted and never fail the run. The answer key is written by the people who wrote the detectors, so a pass says that nothing on it has regressed, not how much of your own history ranwhat would catch.
Exit status 0 when every expectation is met, 3 when one is not, 1 on an error. --seed N draws other fake values and the same expectations, so a run can be repeated.
What it touches Its own temporary directory, which it deletes. It does not open your home directory or ~/.ranwhat, and it sends nothing.

Flags: --seed N, --json.

11 / update

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.

ranwhat update
$ 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.

12 / login

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.

ranwhat login
$ 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).

13 / push

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.

ranwhat push
$ 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.

14 / hook

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.

ranwhat hook
$ 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.

Flags: --scope, --mode, --json (status).

15 / ledger

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
$ 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.

16 / Flags

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.

FlagCommandsWhat 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.