drp-cli

A small Node.js CLI for creating private, exact-commit DRP evidence reports and deriving a separate public Release safely. It uses the DRP HTTP API directly and has no MCP dependency.

Security model

• DRP_API_KEY is the only credential source. There is no credential flag.
• The key is never placed in argv, output, errors, or logs. Signed image uploads intentionally omit the authorization header.
• Evidence reports and all intermediate Release copies are private.
• A Release is made public only after its supplied body has passed the server redaction gate, the private duplicate has been updated and read back successfully, its assets are ready, and the source is confirmed unchanged.
• Failures before the final share request never publish anything. Private temporary artifacts are cleaned up on a best-effort basis; after a share request is attempted, an ambiguous response never triggers deletion of the fully verified Release.

Requirements

• Node.js 20 or newer
• A DRP API key with drops:read and drops:write scopes

files:write is not needed by these commands: local screenshots use DRP's short-lived signed upload capability. Grant only the scopes required by the orb.

Amp project secret

In the Amp project settings, add a project secret named DRP_API_KEY. Fresh orbs receive it as an environment variable. Do not put the value in an AGENTS.md, shell command, prompt, repository file, or command-line option. The CLI does not recognize legacy or alternate credential environment variables.

Use a dedicated, least-privilege DRP key for Amp. Give the key record an auditable name such as DRP CLI | <project/device> so its owner and purpose are clear in DRP. Rotate it by creating a replacement key in DRP, updating the Amp project secret, verifying drp whoami --json in a fresh orb, and then revoking the old key in DRP. Revoke the key immediately if an orb or project is no longer trusted.

Install and invoke before npm publication

Pin GitHub installs to a reviewed full 40-character commit rather than a branch or tag:

npm install --global 'github:martincolley/drp-cli#FULL_40_CHARACTER_COMMIT_SHA'
drp whoami --json

For a one-off invocation in an Amp orb:

npm exec --yes --package='github:martincolley/drp-cli#FULL_40_CHARACTER_COMMIT_SHA' -- drp whoami --json

Replace FULL_40_CHARACTER_COMMIT_SHA with the reviewed commit. The package's prepare script builds the TypeScript executable during a GitHub install. Once published, npm install --global @mcolley/drp-cli will expose the same drp command.

Commands

Identify the account and default destination

drp whoami --json

Create private exact-SHA evidence

The markdown may reference screenshots with ![description](drp:slot-name). Pass local files as repeatable --image SLOT=FILE options; raw bytes are streamed and are never base64-encoded into argv. Every drp:slot-name reference must have exactly one matching image, and every supplied image must be referenced, or the command fails before contacting DRP.

drp evidence create \
  --body ./evidence.md \
  --repository owner/project \
  --pr-url https://github.com/owner/project/pull/123 \
  --commit 0123456789abcdef0123456789abcdef01234567 \
  --image desktop=./artifacts/desktop.png \
  --image mobile=./artifacts/mobile.webp \
  --json

The CLI validates a full 40-character hexadecimal SHA and adds repository, PR URL, and exact commit metadata to the report body. The PR URL must use HTTPS on github.com, contain no URL credentials, point to a pull request, and have an owner/repository path that exactly matches --repository. The report is always created with visibility: private and server-side redaction enabled. --team, --folder, and --title are optional; the default folder is the repository name.

Create a public Release from private evidence

Supply a public-audience markdown body. The source must be a private DRP report. The command never edits or shares it.

drp release create \
  --source https://drp.dev/r/source-slug \
  --body ./release.md \
  --repository owner/project \
  --pr-url https://github.com/owner/project/pull/123 \
  --commit 0123456789abcdef0123456789abcdef01234567 \
  --title 'Release 1.4' \
  --json

Before creating a staging report or duplicate, the CLI validates the supplied GitHub repository, matching PR URL, and full commit SHA, fetches the private source, and requires its leading delivery metadata to match all three. It then sends the public body and title through POST /v1/drops with redact: true in a private staging report because that endpoint is DRP's server redaction boundary. It duplicates the private source (preserving its image assets), replaces only the duplicate's body with the server-returned redacted body, verifies the duplicate's body and complete asset set while private, rechecks source body, visibility, and assets for concurrent changes, and finally publishes only the duplicate. Release titles must be a single line and cannot contain the CLI's reserved internal separator.

Because DRP duplication copies all report assets, the public body must reference exactly the source report's complete image-slot set; this prevents an unreferenced private screenshot from becoming reachable on the public duplicate. Invalid or mismatched delivery identity, missing or extra assets, absent/inconsistent server redaction metrics, an incomplete report, failed read-back, source changes, or any API failure abort publication.

Exact-SHA workflow

1. Fetch the PR and check out the commit that was actually reviewed and tested.
2. Confirm the worktree is clean and record git rev-parse HEAD; it must produce 40 hexadecimal characters.
3. Capture evidence against that checkout, not a moving branch.
4. Pass that exact value to --commit with the matching repository and PR URL.
5. Keep the resulting evidence report private. Prepare a separate public markdown file and pass the same --repository, --pr-url, and --commit values to drp release create; the command refuses a source whose stored metadata differs.

Output and failures

Use --json for stable machine-readable success and error output. Errors are bounded and sanitized. The CLI never prints response bodies wholesale, authorization headers, signed upload URLs, or credentials.

If an image upload fails, the evidence report can remain as a private incomplete report for diagnosis. If Release creation fails before sharing, best-effort cleanup removes private staging/copy artifacts; cleanup failure can leave private artifacts, but cannot publish them. Once the final share request is sent, a malformed or lost success response is ambiguous, so the CLI deliberately retains the already verified duplicate rather than risk deleting content the server made public. The DRP API does not provide a transaction spanning duplication, update, verification, and share, so publication remains the final request.

Development

npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm pack --dry-run

License

MIT