promptreports-cli
Advanced tools
AI Token Operations CLI for PromptReports.ai — secure, optimize, audit, and run every AI consumption surface your team touches. One terminal command finds the spend your proxy can't see across Claude Code, Cursor, Copilot, Codex, MCP servers, and 22+ prov
The local CLI for PromptReports.ai — AI Token Operations for engineering teams.
One terminal command finds the AI spend your proxy can't see, ships the PR to fix it, and signs the audit bundle. Scans Claude Code session JSONLs, CLAUDE.md, skills, stop_reason, and 22+ provider APIs (Cursor, Copilot, Codex, OpenAI, Anthropic, OpenRouter, Stripe, Vercel, Sentry, GitHub, …) — the editor- and surface-layer signals that proxy tools (Helicone, Datadog) structurally cannot read — and pushes per-turn telemetry to your PromptReports.ai dashboards where 27 calibrated detectors find waste and draft fix PRs.
npx promptreports-cli
Zero external dependencies. Runs on your machine. Nothing leaves your computer unless you explicitly push.
The first three commands need no signup. They run fully on your machine.
# 1. See what the CLI is and what to type next (welcome screen)
npx promptreports-cli
# 2. Inventory your AI stack (sessions, providers, costs) — no auth, no upload
npx promptreports-cli summary
# 3. Run a local Token Forensics scan — 5 portable detectors, no auth
npx promptreports-cli forensics
When you want findings + fix-PRs in your dashboard, sign up:
# 4. Sign up / sign in via device-code flow
npx promptreports-cli login
login opens your browser to https://www.promptreports.ai/cli-auth with an 8-character code pre-filled. If you don't have an account yet, the page lets you sign up with Google or email first, then approve the CLI session. Credentials land in ~/.promptreports/config.json (chmod 600) — no copy-paste of API keys.
# 5. Push your local telemetry to your dashboards
npx promptreports-cli push
# 6. Open the dashboards
# https://www.promptreports.ai/swarm/token-forensics
That's it. From here every other command in the reference below is opt-in.
Mid-to-large engineering teams running AI at scale ($50K–$2M/mo across multiple vendors — Claude Code, Cursor, Copilot, Codex, MCP servers, npm packages, customer APIs) have:
CLAUDE.md, skills, sessions, stop_reason, MCP tool invocations) where 60–80% of the waste and risk lives.PromptReports.ai is the AI Token Operations hub: secure, optimize, forensic, operations. The CLI is the local read layer; the dashboards are the act layer. Cost is the wedge — security, governance, and per-team unit economics grow on top of the same data plane.
| CLI command | Dashboard surface | What the dashboard does |
|---|---|---|
summary + push | Token Forensics (/swarm/token-forensics) | Per-turn token attribution, session replay, model-cost breakdown, 27 calibrated detector findings |
forensics (with --auth) | Token Forensics — full detector pass | 5 detectors locally; --auth adds 22 server-side detectors against your full ingest history |
push --editor cursor|copilot|codex|aider|cline | Token Forensics — multi-editor view | Same dashboard, scoped per editor; portability gate on the detector matrix |
providers + push | Provider Cost Center (/admin?tab=providers) | Multi-provider burn-rate over time, anomaly detection, monthly projections |
costs --push-to-app | Cost Attribution (inside Token Forensics) | Cost per feature / per model / per git commit |
cost-per-quality | Routing Recommendations | Per-prompt judge-delta scoring; surfaces routes where a cheaper model performs as well as the expensive one |
recommend | Routing Recommendations queue | Top open RoutingRecommendation rows ≥$1/mo with confidence tiers |
rollup | PR Cost Decoration | Generates the same per-PR cost rollup the GitHub App uses, locally |
context --ghosts (with --json push) | Ghost-Token Scanner | Trends silent waste over time, alerts when ghosts spike |
audit + audit claude-md | Token Forensics Audit | CLAUDE.md slim-down, skill review, env hygiene |
audit-stack | Codebase Audit | Cross-system audit (env + secrets + dependencies + schema drift) in one pass |
health | SRE Department | Post-deploy health checks, infra reliability scoring |
git-intel | Engineering Velocity | Hotspots, churn, ownership, auto-changelogs |
dead-code / deps / schema | Codebase Audit | Drift detection, security findings, dependency hygiene |
prompts audit | Prompt Drift | Catches prompt regressions across releases |
campaign launch | Demand Gen Department (/campaigns) | Multi-channel campaign generation with brand-playbook gating |
sessions / logs | Unified Session Replay | Full session history with cross-tool log correlation |
generate / reports list | Research & Reports (/reports) | Full SOAR-V verified-research pipeline from terminal |
publish / share | Public Viewer / Signed Share | /r/<id> public + /s/<token> private with referral attribution |
status / telemetry | Account & CLI Metrics (/admin/cli-metrics) | Quota + plan; DAU/WAU/MAU, activation funnel |
export-skill-pack / import-skill-pack | Skill Pack Marketplace | Bundle and share .claude/skills/ directories across teams |
Free tier covers all local scans. Pushing to dashboards is free up to a soft limit; team dashboards, alerts, and auto-PR generation are pro features.
1.8.1 and 1.8.2The push command got hardened against transient timeouts that hit teams pushing thousands of new turns:
PROMPTREPORTS_TIMEOUT_MS=120000 for very slow networks.AbortError and 5xx responses before giving up.1.8.0push now ingests Cursor, Copilot, Codex, Aider, and Cline turns alongside Claude Code:
# Claude Code (default, scans ~/.claude/projects/)
npx promptreports-cli push
# Other editors — export the session JSON, pipe it in
npx promptreports-cli push --editor cursor --from-file ./cursor-export.json
npx promptreports-cli push --editor copilot --from-file ./copilot-export.json
Each turn gets tagged with its editor so the dashboard's portability matrix gates detectors correctly (some detectors only fire on CC; others are editor-portable).
1.8.0push now ships full prompt and response text by default (capped at 100KB per turn). The dashboard's Submissions tab uses this for the Trace modal and ±2-turn session-history panel. Opt out per push:
npx promptreports-cli push --no-text
With --no-text, the dashboard shows the 120-char preview and a "text not captured" badge. Server-side text storage is provenance-logged behind a reveal route — same SOC2 posture either way.
1.8.0Run the same 5 portable detectors that ship inside Claude Code's /forensics skill, but from any terminal:
# Local-only — 5 detectors, no auth
npx promptreports-cli forensics
npx promptreports-cli forensics --session ~/.claude/projects/foo/sessions/abc.jsonl
# Auth mode — 22 additional server-side detectors against your full ingest history
npx promptreports-cli forensics --auth
npx promptreports-cli forensics --auth --json
Useful in IDEs that don't run Claude Code (Cursor, Codex, plain terminal).
Every command in 1.8.2, what it does, and when you'd reach for it.
summary — token usage across your AI sessions (default command)Inventory all ~/.claude/projects/*/sessions/*.jsonl files. Reports total tokens, cost (priced via the bundled model-pricing.json), and the top sessions by burn.
npx promptreports-cli summary
npx promptreports-cli summary --days 30 # lookback window
npx promptreports-cli summary --json # machine-readable
Why: zero-config sanity check on your weekly Claude Code spend. If the number surprises you, run forensics next.
forensics — Token Forensics scan (new in 1.8)Five portable detectors against your most-recent CC session (or --session <path>). Mirrors the /forensics slash command shipped as a Claude Code skill.
npx promptreports-cli forensics
npx promptreports-cli forensics --session ~/.claude/projects/foo/sessions/abc.jsonl
npx promptreports-cli forensics --auth # adds 22 server-side detectors
npx promptreports-cli forensics --json
Why: instant local audit without leaving the terminal. --auth upgrades to the full 27-detector pass against your ingest history.
providers — multi-provider cost scanHits 22+ provider APIs in parallel: OpenAI, Anthropic, OpenRouter, Cursor, Copilot, Vercel, Stripe, Railway, Sentry, GitHub, PostHog, Supabase, Pinecone, Tavily, and more. Reports current spend, monthly projection, and anomalies.
npx promptreports-cli providers
npx promptreports-cli providers --days 30
npx promptreports-cli providers --json | jq '.providers[] | select(.monthly_projection > 50)'
Why: catches anomalies your provider's own dashboard buries. Set keys via env vars (the CLI reads OPENAI_API_KEY, STRIPE_SECRET_KEY, etc. — only what you've set; nothing required).
doctor — environment health checkNode version, env-var presence, file permissions, network reachability to PromptReports.ai.
npx promptreports-cli doctor
Why: first thing to run if anything else is misbehaving.
audit — Claude Code expert auditAudits .claude/, skills, env hygiene, and CLAUDE.md size against best-practice checklists.
npx promptreports-cli audit
npx promptreports-cli audit claude-md # deep slim-down analysis
npx promptreports-cli audit claude-md --json
audit claude-md detects:
LESSONS.md, TECH_STACK.md, etc.)Output includes projected token count, estimated savings per session, prioritized fix list.
Why: every line in CLAUDE.md taxes every turn. Operators report 20–40% prompt-token reduction after one slim-down pass.
audit-stack — full-stack audit (new in 1.8)Cross-system audit in one pass: secrets in .env*, dependency CVEs, Prisma schema drift vs. live DB, dead routes, stale skills, MCP server health.
npx promptreports-cli audit-stack
npx promptreports-cli audit-stack --json
Why: before a deploy, before an external audit, or any time you want one terminal command that covers what deps + dead-code + schema + audit would each say individually.
filter -- <cmd> — compress subprocess outputWraps any command. Stdout/stderr gets deduplicated, stack-frame-collapsed, and tail-preserved before your agent reads it. Errors and warnings always pass through. Exit code preserved.
npx promptreports-cli filter -- npm test
npx promptreports-cli filter -- playwright test --reporter=list
npx promptreports-cli filter --keep-last 50 -- npm run ci
What it actually does:
[repeated N-1 more times][... N similar lines elided ...]error/fail/warn/exception/traceback--keep-last)Flags: --keep-last N (default 20), --max-repeat N (default 2), --truncate-after N (default 50).
Why: giving an AI agent the raw output of npm test burns 4–10× more tokens than it needs. filter keeps signal, drops slop.
context — context-window optimizerFinds bloat patterns in your sessions.
npx promptreports-cli context
npx promptreports-cli context --ghosts # silent waste scanner
npx promptreports-cli context --ghosts --days 30
--ghosts detects:
audit claude-md)Why: ghosts are the single biggest source of wasted tokens that aggregate dashboards miss.
costs — per-feature / per-model / per-commit cost attributionnpx promptreports-cli costs
npx promptreports-cli costs --days 30 --push-to-app
Why: answers "which feature is burning the most tokens?" before someone asks in standup.
cost-per-quality — routing-recommendation analysis (new in 1.8)Pairs each prompt with judge-delta quality scoring, then surfaces routes where a cheaper model performs as well as the expensive one.
npx promptreports-cli cost-per-quality
npx promptreports-cli cost-per-quality --json
Why: the input to the dashboard's RoutingRecommendation queue. If you want to see what could be re-routed before swallowing the change in production, run this first.
recommend — open routing recommendationsLists open RoutingRecommendation rows with savings, confidence tier, and rationale.
npx promptreports-cli recommend
npx promptreports-cli recommend --json
Why: review queue from the terminal. The accept-and-swap action lives in the dashboard; this command is read-only.
models — model router suggestionsSuggest cheaper models per workload using the same heuristics as the dashboard's model-overkill detector.
npx promptreports-cli models
prompts audit — prompt drift detectorCatches prompt regressions across releases.
npx promptreports-cli prompts audit
login)login / logout / whoamiDevice-code auth. login opens /cli-auth with an 8-char code pre-filled. After approve, credentials land in ~/.promptreports/config.json (chmod 600). If you don't have an account yet, the page lets you sign up with Google or email first.
npx promptreports-cli login
npx promptreports-cli whoami
npx promptreports-cli logout
Token resolver precedence: --token flag → PROMPTREPORTS_TOKEN env → PROMPTREPORTS_BRAIN_TOKEN env → config file. Existing env-var workflows keep working.
status — account dashboardPlan, monthly quota with progress bar, remaining reports, upgrade URL when at limit.
npx promptreports-cli status
Why: one-screen sanity check before generating a report or running a heavy push.
telemetry on|off|status — opt-in usage reportingPrompted once on first command in an interactive TTY. Non-TTY / CI defaults to OFF. Opting out hard-deletes every past event for your install ID server-side. Fire-and-forget 2-second timeout; never blocks command exit.
npx promptreports-cli telemetry on
npx promptreports-cli telemetry status
npx promptreports-cli telemetry off # hard-deletes server-side history
push — ship telemetry to PromptReports.ai# Default — Claude Code, all sessions in window
npx promptreports-cli push
# Lookback override
npx promptreports-cli push --days 30
# Backfill — bypass delta checkpoint, force re-push everything
npx promptreports-cli push --backfill
# Other editors
npx promptreports-cli push --editor cursor --from-file ./cursor-export.json
npx promptreports-cli push --editor copilot --from-file ./copilot-export.json
npx promptreports-cli push --editor codex --from-file ./codex-export.json
# Suppress full prompt + response text (privacy mode)
npx promptreports-cli push --no-text
Why: push is what turns your local data into dashboard findings. Without push, the platform has nothing to detect against. Use --backfill once after upgrading to refresh older pre-enrichment data.
push-non-coding — push non-coding agent telemetry (new in 1.8)Subtype of push for non-coding agents (research, content, ops bots). Routes to a separate dashboard scope so coding-agent detectors don't fire on them.
npx promptreports-cli push-non-coding --from-file ./agent-export.json
rollup — local PR cost rollup (new in 1.8)Generates the same per-PR cost rollup the GitHub App posts as a comment, but locally — useful for testing changes to the rollup logic without round-tripping through GitHub.
npx promptreports-cli rollup --pr 412
npx promptreports-cli rollup --pr 412 --json
generate "<topic>" — run a report from the terminalnpx promptreports-cli generate "Q2 AI ops competitive landscape"
Hits /api/reports/generate with PAT auth, respects quota, streams progress to stdout, prints report ID + workspace URL on completion.
Why: verify a research topic without opening the browser. Same SOAR-V verification pipeline as the web UI.
reports list — your recent reportsnpx promptreports-cli reports list
npx promptreports-cli reports list --json
publish <reportId> / unpublish <reportId> — flip visibilityToggles Report.visibility between PRIVATE and PUBLIC. publish prints the /r/<id> short URL. PRIVATE reports 404 for unauthenticated viewers (no existence leak). Free-tier viewers see an upgrade watermark; Pro+ viewers and report owners get the Export PDF button.
npx promptreports-cli publish rpt_01HVabc...
npx promptreports-cli unpublish rpt_01HVabc...
share <reportId> — signed expiring share URLHand a PRIVATE report to a specific person without making it public. Returns /s/<token> URL that expires, caps view count, and can be revoked. Plaintext shown exactly once.
npx promptreports-cli share rpt_01HV... --expires-in-hours 72 --max-views 10 --label "Q2 board review"
Signed links also attribute signups back to you — a pr_ref cookie is set when someone opens your link and recorded as referral attribution if they sign up.
Terminal entry-point into the shared-intelligence layer that every virtual department reads.
npx promptreports-cli brain init # scaffold ~/business/ folder
npx promptreports-cli brain sync # push business context to PromptReports.ai
npx promptreports-cli brain who # inspect account + connected sources
npx promptreports-cli brain context # what the brain knows about your company
npx promptreports-cli brain run "<question>" # one-shot query
npx promptreports-cli dead-code # unused routes, components, deps
npx promptreports-cli deps # CVEs, outdated packages, license compliance
npx promptreports-cli schema # Prisma schema stats + drift vs. live DB
npx promptreports-cli git-intel # hotspots, churn, ownership, auto-changelog
npx promptreports-cli sessions # session history, replay, search
npx promptreports-cli logs # unified Sentry / Vercel / PostHog log stream
npx promptreports-cli env sync # diff/sync .env.local with Vercel/Railway
npx promptreports-cli setup export --all --encrypt mySecret123 --output team.json
npx promptreports-cli setup import team.json --decrypt mySecret123
npx promptreports-cli health # post-deploy health check
Bundle a .claude/skills/ directory into a portable archive other teams can import.
npx promptreports-cli export-skill-pack ./.claude/skills --out ./my-skills.tgz
npx promptreports-cli import-skill-pack ./my-skills.tgz --target ./.claude/skills
npx promptreports-cli campaign launch "V2 export flow"
npx promptreports-cli campaign launch npm:my-package
npx promptreports-cli campaign list
npx promptreports-cli campaign show cmp_01HV9Z...
Brand-playbook review happens server-side before anything sends.
| Flag | Effect |
|---|---|
--days N | Lookback period (default: 7) |
--today | Shorthand for --days 1 |
--json | Machine-readable output |
--quiet | Suppress non-essential output |
--dry-run | Preview changes without writing |
--backfill | Bypass delta checkpoint (push only); defaults --days to 90 |
--editor <kind> | Push adapter: claude-code (default), cursor, aider, cline, codex |
--from-file <path> | Pre-exported turns file (required for non-CC editors) |
--no-text | Suppress full prompt/response text capture on push |
--token <pat> | Override token resolver precedence |
Daily token-burn check (zero-config, no signup):
npx promptreports-cli
Local Token Forensics scan:
npx promptreports-cli forensics
npx promptreports-cli audit claude-md # the usual top finding
Monthly burn-rate review:
npx promptreports-cli providers --days 30 --json | jq '.providers[] | select(.monthly_projection > 50)'
Pre-deploy verification:
npx promptreports-cli doctor && npx promptreports-cli audit-stack && npx promptreports-cli health
Compress noisy CI output for an agent:
npx promptreports-cli filter -- npm run test:e2e
Onboard a new teammate:
# On your machine
npx promptreports-cli setup export --all --encrypt mySecret123 --output team.json
# On their machine
npx promptreports-cli setup import team.json --diff --decrypt mySecret123
npx promptreports-cli setup import team.json --decrypt mySecret123
Generate and share a report:
npx promptreports-cli login
npx promptreports-cli generate "Q2 AI ops competitive landscape"
npx promptreports-cli reports list
npx promptreports-cli share rpt_01HV... --expires-in-hours 72 --max-views 10
Cut a release + announce it:
npm publish && npx promptreports-cli campaign launch npm:my-package
Backfill historical text after upgrading from <1.8:
Older TokenPushTurn rows ingested before 1.8 keep promptText / responseText null and render the "text not captured" badge. The recoverable subset (rows whose metadata stashed text under prompt/promptText/response/completion synonyms) can be backfilled server-side:
# Operator-only — runs against the platform DB, not via the CLI
pnpm tsx scripts/tf-backfill-prompt-fingerprint.ts <userId> --dry-run
pnpm tsx scripts/tf-backfill-prompt-fingerprint.ts <userId>
pnpm tsx scripts/tf-backfill-prompt-fingerprint.ts --all
Rows whose metadata is empty cannot be recovered — the text is gone.
Two commands send data to PromptReports.ai. They run only when you opt in — both require an API key, and audit --push additionally asks for one-time interactive consent the first time you run it.
push — Token Forensics ingestSends the per-turn telemetry the dashboard's detectors need to work:
--no-textclaude-code, cursor, copilot, codex, aider, cline)Server-side text storage is provenance-logged behind a reveal route — only you (the row owner) can re-read it.
audit --push — local environment digestSends a small structured digest so the dashboard's audit-source view can show what providers you're configured for:
| Field | What ships | What does NOT ship |
|---|---|---|
envKeys | ["OPENAI_API_KEY", "DATABASE_URL", …] — names only | Values, comments, file path |
packageDeps | dependencies / devDependencies / peerDependencies maps | scripts, author, repository, publishConfig, custom fields |
packageMeta | { name, version } | Anything else from package.json |
vscodeExtensions | ["github.copilot", "anthropic.claude", …] — opt-in via --include-extensions | Nothing by default; the code subprocess is not spawned unless you pass the flag |
findings / score / recommendations | The audit results you saw on stdout | Source code, file contents, env values |
This shape is payloadVersion: 2 in the request body. Source: tools/cli/src/commands/audit.ts → buildCliPayload(). The 1.8.3 hardening pass replaced an earlier shape that shipped raw .env.local and full package.json blobs (that's what Socket.dev's AI scanner flagged on 1.8.2 — the hardening closes both the over-share and the redirect vector).
The first time you run audit --push interactively, the CLI prints exactly what's about to be sent and asks you to confirm. Your answer (y/n) is stored in ~/.promptreports/config.json under auditPushConsent so subsequent runs don't re-prompt. Non-TTY shells / CI default to false (no push, no prompt) — flip the bit explicitly in the config file if you want to script it.
PROMPTREPORTS_URL (and the legacy PROMPTREPORTS_API_URL) is allowlisted to *.promptreports.ai and localhost. Any other host is rejected with a stderr warning and the CLI falls back to https://www.promptreports.ai. Self-hosted operators set PROMPTREPORTS_ALLOW_CUSTOM_HOST=1 to opt out of the allowlist — the CLI never silently honors an arbitrary host. This closes the redirect vector flagged by Socket.dev on 1.8.2.
The opt-in telemetry command sends only command name, duration, success flag, CLI version, Node version, OS — never prompt content, file paths, env vars, or anything you typed. telemetry off hard-deletes every past event for your install ID server-side.
push, generate, publish, share, campaign, brain sync)Fastest path is device-code login (see Get started). Prefer env vars? Generate a PAT at https://www.promptreports.ai/settings/api-keys and set one of:
export PROMPTREPORTS_TOKEN=pat_...
# or the legacy names (still supported)
export PROMPTREPORTS_API_KEY=pk_...
export PROMPTREPORTS_BRAIN_TOKEN=pat_...
# optional — override the API base for self-hosted / staging
export PROMPTREPORTS_URL=https://www.promptreports.ai
# Per-batch HTTP timeout, default 60000 (60s). Bump for slow networks.
export PROMPTREPORTS_TIMEOUT_MS=120000
telemetry off hard-deletes server-side history. Non-TTY / CI defaults to OFF.
No install needed — use npx:
npx promptreports-cli
Or install globally:
npm install -g promptreports-cli
promptreports-cli
Node ≥18 required.
MIT. See LICENSE.
FAQs
AI Token Operations CLI for PromptReports.ai — secure, optimize, audit, and run every AI consumption surface your team touches. One terminal command finds the spend your proxy can't see across Claude Code, Cursor, Copilot, Codex, MCP servers, and 22+ prov
The npm package promptreports-cli receives a total of 11 weekly downloads. As such, promptreports-cli popularity was classified as not popular.
We found that promptreports-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A malicious NuGet package impersonating Sicoob exfiltrated client IDs, PFX passwords, and banking certificates through Sentry telemetry.
Security News
Feross Aboukhadijeh joins TBPN to discuss Socket's $60M Series C, 500%+ ARR growth, AI's impact on open source, and the rise in supply chain attacks.
Security News
OSV withdrew 157 OSV malware reports after automated false positives incorrectly flagged trusted npm and PyPI packages, sending bad records into tools that rely on OSV data.