{"id":50941600,"url":"https://github.com/aks-builds/cliproof","last_synced_at":"2026-06-17T15:30:42.328Z","repository":{"id":362693695,"uuid":"1260392513","full_name":"aks-builds/cliproof","owner":"aks-builds","description":"Prove your CLI actually works. A Claude Code skill that captures a real terminal command and its real output as a polished screenshot or GIF — secrets redacted, command-guarded — and embeds it into your README as proof-it-runs evidence.","archived":false,"fork":false,"pushed_at":"2026-06-05T14:52:27.000Z","size":276,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T15:02:32.095Z","etag":null,"topics":["agent-skills","ai","claude-code","claude-skills","cli","developer-tools","devtools","documentation","freeze","gif","readme","screenshot","terminal","vhs"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aks-builds.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-05T12:53:40.000Z","updated_at":"2026-06-05T14:52:31.000Z","dependencies_parsed_at":"2026-06-05T15:02:47.759Z","dependency_job_id":null,"html_url":"https://github.com/aks-builds/cliproof","commit_stats":null,"previous_names":["aks-builds/proofshot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aks-builds/cliproof","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aks-builds%2Fcliproof","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aks-builds%2Fcliproof/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aks-builds%2Fcliproof/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aks-builds%2Fcliproof/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aks-builds","download_url":"https://codeload.github.com/aks-builds/cliproof/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aks-builds%2Fcliproof/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34453440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai","claude-code","claude-skills","cli","developer-tools","devtools","documentation","freeze","gif","readme","screenshot","terminal","vhs"],"created_at":"2026-06-17T15:30:41.769Z","updated_at":"2026-06-17T15:30:42.323Z","avatar_url":"https://github.com/aks-builds.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 📸 cliproof\n\n**Your README should show it works — not just say it.**\n\nCapture any real command and its real output — tests, builds, servers,\nscripts, pipelines — as a polished screenshot or GIF, redact any secrets,\nand embed it into your `README.md` as honest, durable evidence it works.\nThen let CI fail the moment that evidence goes stale.\n\n[![CI](https://github.com/aks-builds/cliproof/actions/workflows/ci.yml/badge.svg)](https://github.com/aks-builds/cliproof/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/aks-builds/cliproof/actions/workflows/codeql.yml/badge.svg)](https://github.com/aks-builds/cliproof/actions/workflows/codeql.yml)\n[![npm](https://img.shields.io/npm/v/cliproof.svg)](https://www.npmjs.com/package/cliproof)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE.md)\n[![Agent Skill](https://img.shields.io/badge/Agent-Skill-8A63D2.svg)](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)\n\n\u003cbr/\u003e\n\n\u003cimg src=\"./.github/media/hero.svg\" width=\"720\" alt=\"cliproof preflight running in a styled terminal, detecting capture tools on the machine\" /\u003e\n\n\u003csub\u003e☝️ A real cliproof capture — generated by this repo's own skill, of its own \u003ccode\u003epreflight\u003c/code\u003e command.\u003c/sub\u003e\n\n\u003c/div\u003e\n\n---\n\n## Why cliproof\n\nA README that *says* \"it works\" convinces no one. A screenshot of the command\nactually running — version banner, passing tests, real output — convinces\neveryone in two seconds. cliproof makes that screenshot **honest, repeatable,\nand durable**: it runs the real command, captures the genuine output, strips\nany secrets, embeds it in your README, and can re-check in CI that the command\nstill produces the same result.\n\nIt works as a **Claude Code Agent Skill**, an installable **plugin**, and an\n**agent-agnostic npm CLI** (`npm i -g cliproof`) for Cursor, Codex, OpenCode,\nGemini CLI, Windsurf, or any agent that runs shell commands.\n\n## How is this different?\n\nMost \"agent eyes\" tools verify *browser/UI* sessions. cliproof verifies the\n**terminal** — the build, the test run, the CLI itself — and turns it into\ndurable README proof.\n\n| | screenshot/GIF tools | browser-proof tools | **cliproof** |\n|---|:---:|:---:|:---:|\n| Real command + real output | ✅ | ➖ (browser) | ✅ |\n| Static screenshot (themed window) | some | ❌ | ✅ |\n| Animated GIF | ✅ | ✅ | ✅ |\n| Enforced secret redaction | ❌ | ❌ | ✅ |\n| Destructive-command guard | ❌ | ❌ | ✅ |\n| Idempotent README embed | ❌ | ❌ | ✅ |\n| **CI freshness check (fails when proof drifts)** | ❌ | ❌ | ✅ |\n| Pass/fail verify (10+ langs) | ❌ | ✅ | ✅ |\n| Proof → PR comment | ❌ | ✅ | ✅ |\n| Agent-agnostic install | ❌ | ✅ | ✅ |\n| Zero-dependency, no-network core | ❌ | ❌ | ✅ |\n\n\u003csub\u003ecliproof's ✅s are backed by tests — see [Testing](#testing). (Animated GIF is exercised best-effort in CI since it needs `ttyd`; the PR-comment *post* is a `gh` side-effect, only its body is unit-tested.)\u003c/sub\u003e\n\n## Who it's for\n\ncliproof works for anyone who runs shell commands and wants durable proof:\n- **Open-source maintainers** — show contributors and users the project ships\n- **Backend \u0026 platform engineers** — prove builds, servers, and scripts run\n- **QA \u0026 DevOps teams** — capture test runs and pipeline output as evidence\n- **AI agent builders** — wire capture → redact → embed as an MCP tool chain\n- **Anyone writing a README** — stop saying it works; show it\n\n## Features\n\n- 📸 **Static screenshots** — macOS/iOS window or Windows-terminal look, one-flag themes (`--preset macos|github-dark|nord|iterm|win11`).\n- 🎬 **Animated GIFs** — scripted typing + live output via `vhs`.\n- 🔒 **Enforced secret redaction** — masks API keys, tokens, JWTs, private keys; normalises emails/IPs/home paths *before* anything is committed. Extend with a `.cliproof/redact.json` policy (custom patterns + allowlist).\n- 🛡️ **Command-safety guard** — refuses destructive/exfiltration commands (`rm -rf /`, `curl … | sh`, credential reads).\n- ♻️ **Idempotent README inserts** — marker blocks with diff preview + backup.\n- 🎯 **Determinism + freshness check** — normalises volatile output (durations, timestamps, paths) and **fails CI when a proof drifts** from reality. Reusable GitHub Action included.\n- ✅ **Verify** — run a command and judge pass/fail from exit code + error signatures across 10+ languages; emit a PR-ready report.\n- 🧠 **Auto-suggest** — scans your repo (`package.json`/`Makefile`/`--help`/quickstart) for the best command to capture.\n- 🎞️ **Storyboard** — stitch a command sequence into one \"session\" image.\n- 💬 **PR proof** — post the screenshot + verdict as a pull-request comment.\n- 🧰 **Zero-dependency core** — pure Python stdlib, no network, fully auditable.\n\n## Install\n\n**npm — works in any agent, pipeline, or IDE:**\n```bash\nnpm install -g cliproof\ncliproof install        # detects Claude Code, Cursor, Codex, OpenCode, Gemini, Windsurf\n```\n\n**MCP server (Claude Code, Cursor, Windsurf, LangChain — any MCP-compatible agent):**\n```json\n// .mcp.json\n{ \"mcpServers\": { \"cliproof\": { \"command\": \"cliproof\", \"args\": [\"mcp\"] } } }\n```\n\n**Python library:**\n```bash\npip install cliproof\n```\n```python\nfrom cliproof import capture, redact, embed\nresult = capture(\"pytest -q\", preset=\"catppuccin\")\nredact(result.image, in_place=True)\nembed(\"README.md\", image=result.image, block_id=\"tests\")\n```\n\n**Docker (any CI — GitHub Actions, GitLab CI, Jenkins, CircleCI):**\n```yaml\n- docker run --rm -v $PWD:/repo \\\n    ghcr.io/aks-builds/cliproof:latest \\\n    capture --execute \"pytest -q\" -o /repo/.github/media/tests.svg --json\n```\n\n**Local HTTP daemon (IDE extensions, polyglot callers):**\n```bash\ncliproof serve            # starts on localhost:7070\ncurl localhost:7070/health\n```\n\n**Claude Code plugin:**\n```bash\n/plugin marketplace add aks-builds/cliproof\n/plugin install cliproof@cliproof   # @cliproof is the marketplace name, not the repo path\n```\n\n**Manual skill:** copy `skills/cliproof/` into `~/.claude/skills/cliproof/`.\n\n**Capture tools** (installed on demand, official sources, version-pinned):\n- `freeze` — `go install github.com/charmbracelet/freeze@v0.2.2` · `brew install charmbracelet/tap/freeze` · `scoop install freeze`\n- `vhs` (GIFs only) — `brew install vhs` (needs `ffmpeg` + `ttyd`; on Windows use WSL)\n\n## Usage\n\nIn your agent, just ask: *\"screenshot `myapp --help` for the README\"* or\n*\"add proof the tests pass\"*. Under the hood (also runnable directly, or via the\n`cliproof \u003ccmd\u003e` CLI):\n\n```bash\ncliproof suggest .                                   # what's the best proof command?\ncliproof guard -- \"myapp --help\"                     # safe to capture?\ncliproof capture --execute \"myapp --help\" \\\n  --preset macos -o .github/media/help.svg           # real capture → redactable SVG\ncliproof redact .github/media/help.svg --in-place    # strip secrets (exit 3 = blocked)\ncliproof embed README.md --image .github/media/help.svg \\\n  --alt \"myapp --help\" --id help --heading Demo       # idempotent insert (diff + .bak)\n```\n\n`embed` maintains a keyed marker block, so re-running with the same `--id`\nupdates in place instead of duplicating:\n\n```html\n\u003c!-- cliproof:start id=help --\u003e\n![myapp --help](.github/media/help.svg)\n\u003c!-- cliproof:end id=help --\u003e\n```\n\n\u003e `capture` wraps `freeze`: it closes stdin (raw `freeze` **hangs** on an\n\u003e inherited pipe in agent/CI shells) and writes **SVG** (its PNG rasterizer can\n\u003e **crash** on Windows). Use `rasterize` to make a PNG after redaction.\n\n## Keep your proofs fresh (the moat)\n\nA screenshot proves your CLI worked *once*. cliproof keeps it honest. Record a\nbaseline of the command's normalised output, list it in `.cliproof/proof.json`,\nand let CI re-run it and **fail if it drifts**:\n\n```jsonc\n// .cliproof/proof.json\n{ \"proofs\": [\n  { \"id\": \"cli-help\", \"command\": \"myapp --help\",\n    \"baseline\": \".github/media/cli-help.cliproof.txt\",\n    \"image\": \".github/media/cli-help.svg\" } ] }\n```\n\n```yaml\n# .github/workflows/freshness.yml\n- uses: aks-builds/cliproof/.github/actions/cliproof-check@v1\n  with: { manifest: .cliproof/proof.json }\n```\n\n`cliproof check --update` records baselines; `cliproof check` compares. Volatile\nnoise (durations, timestamps, temp paths, ports) is normalised so only *real*\ndrift (\"3 tests now fail\") fails the build.\n\n## Security\n\ncliproof runs real shell commands and writes into your repo, so security is\nenforced by code, not by convention:\n\n- **Pure stdlib, no network** — zero third-party deps, no build step, no telemetry. Audit [`skills/cliproof/scripts/`](./skills/cliproof/scripts/).\n- **Redaction before embedding** — `redact.py` blocks SECRET-class findings (exit 3); extend via `.cliproof/redact.json`.\n- **Command guard** — `guard.py` refuses destructive/exfiltration commands.\n- **Pinned, official tools** — `freeze`/`vhs` version-pinned, installed only with confirmation.\n\nThreat model: [`references/security.md`](./skills/cliproof/references/security.md). Report privately: [SECURITY.md](./SECURITY.md).\n\n## Repository layout\n\n```\ncliproof/\n├── .claude-plugin/        plugin.json · marketplace.json\n├── bin/cli.js             agent-agnostic npm CLI (install + passthrough)\n├── skills/cliproof/\n│   ├── SKILL.md           the skill (rules, workflow, gates)\n│   ├── references/        tooling.md · security.md\n│   ├── scripts/           preflight · guard · capture · redact · rasterize · embed\n│   │                      · normalize · check · suggest · verify · storyboard · annotate · pr\n│   └── assets/            demo.tape.template (VHS)\n├── .cliproof/             proof.json (freshness manifest) · redact.json (policy)\n├── tests/                 pytest (87 tests)\n└── .github/               CI · CodeQL · Dependabot · release/publish · freshness action\n```\n\n## Testing\n\nEvery claim above is backed by tests, at one of two levels:\n\n- **Unit (114 pytest + 5 Node tests, runs on every PR):** redaction (+ policy/allowlist), command guard, idempotent embed, determinism + freshness engine, verify across languages, suggest, storyboard, annotate, capture-wrapper + theme presets, rasterizer selection, manifest validation, the agent-agnostic `install`, and a guard test that asserts the scripts import **only stdlib and no network modules**.\n- **Integration (`integration.yml`, real tools on Linux):** installs `freeze` and runs the full pipeline end-to-end — `capture --execute` → assert SVG → `redact` → `embed` (asserts idempotency) → `check` round-trip. A real `vhs` GIF is rendered **best-effort** (needs `ttyd`).\n\nNot asserted by tests: the `freeze` PNG rasterizer on Windows (it crashes there — that's *why* cliproof captures SVG), and the `gh` PR-comment network call (only the comment body is unit-tested). Run it all locally with `pytest -q` and `npm test`.\n\n## Contributing\n\nPRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Good first contributions:\nredaction patterns, guard rules, themes, language signatures for `verify`. Found\na security issue? See [SECURITY.md](./SECURITY.md). Licensed under [MIT](./LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faks-builds%2Fcliproof","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faks-builds%2Fcliproof","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faks-builds%2Fcliproof/lists"}