Prove your CLI actually works. Captures a real terminal command and its real output as a polished screenshot or GIF, redacts secrets, and embeds it into your README as proof-it-runs evidence. Agent-agnostic (Claude Code, Cursor, Codex, OpenCode, Gemini, Windsurf).
cliproof exposes 11 tools with complete input schemas and descriptions, but quality is uneven. Naming is domain-specific but lacks consistent verb-noun patterns (e.g., 'capture', 'redact', 'embed' are clear; 'check', 'guard', 'verify', 'suggest' are generic). Descriptions are present (avg ~100 chars) but lack actionable context, they state WHAT but not WHEN or WHY to call each tool. No output schemas documented. Parameters have types and descriptions, but many lack constraints (enums, ranges, defaults). Error handling is absent, no guidance on recovery, retryability, or what to do on failure. No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Security: 'pr' tool accepts image_url as a parameter, risking injection; no mention of auth/permissions.
Add overlays to an SVG capture: caption bar, pass/fail badge, version stamp, CI ribbon.
Capture a real command's output as a styled SVG screenshot. Returns the image path and renderer tier.
Verify all proof baselines are still fresh. Fails if any proof has drifted.
Idempotently insert or update a cliproof image block in README.md.
Check if a command is safe to capture. Returns ok=true if safe.
Report which capture tools are installed and what modes are available.
Post the screenshot and verify report as a pull-request comment.
Generic tool names lack action verbs. 'check', 'guard', 'verify', 'suggest' are vague, LLMs cannot infer intent from names alone. Rename to 'verify_proofs', 'validate_command_safety', 'judge_command_output', 'recommend_capture_command'.
No output schemas documented. LLMs cannot plan downstream calls or extract required fields. Document what each tool returns (e.g., capture returns {path, tier}, redact returns {redacted_count, secrets_found}).
No error handling guidance. Tools fail silently or with raw errors. Add recovery hints: 'If capture times out, increase timeout param or simplify command.' Categorize errors as retryable vs fatal.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 53 | 2026-07-28+ | v2 |
Scan a captured SVG for secrets and redact them. Exits with error if SECRET-class patterns are found.
Stitch multiple SVG captures into a single storyboard image.
Scan the repo and suggest the best command to capture as proof.
Run a command and judge PASS/FAIL from exit code and error signatures.
Missing tool annotations. No readOnlyHint, destructiveHint, or idempotentHint. LLMs cannot determine which tools are safe to retry or have side effects. Mark 'capture', 'redact', 'embed', 'annotate', 'storyboard', 'pr' as destructive; mark 'check', 'guard', 'verify', 'suggest', 'health' as readOnly.
'pr' tool accepts image_url as a parameter, risking URL injection or SSRF. Validate URL format and scheme (https only). Consider server-side image upload instead of client-provided URLs.