Blockchain-Stamped Credentials,
Guided by AI

Step 1 — Install Node.js (>= 18)

CredCLI requires Node.js 18 or later. Download it from nodejs.org or use a version manager:

nvm install 20
nvm use 20
node --version

winget install OpenJS.NodeJS.LTS
node --version

Step 2 — Install CredCLI

Install globally for persistent use, or run one-off with npx:

# Option A: Install globally (recommended)
npm install -g @credcli/cli

# Option B: Run without installing
npx @credcli/cli <command>

Step 3 — Verify installation

credcli help

You should see a list of commands. If not, ensure npm bin -g is on your PATH.

Cowork VMs have two constraints that require a one-time workaround:

• The default npm global prefix is not writable — install into ~/.npm-global instead.
• The mounted workspace folder blocks file deletion (EPERM) — a one-line patch silences this after render.

Step 1 — Install into a writable prefix

npm install -g @credcli/cli --prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
credcli --version

Step 2 — Run the Cowork setup script

This installs Playwright's Chromium browser into the package directory (so it survives session resets) and applies the EPERM patch to cli.mjs. Safe to re-run — each step checks before acting.

bash ~/.npm-global/lib/node_modules/@credcli/cli/scripts/setup.sh

Step 3 — Use the browser path when rendering

Every credcli run command needs the PLAYWRIGHT_BROWSERS_PATH variable pointing at the package-local browser:

PLAYWRIGHT_BROWSERS_PATH=~/.npm-global/lib/node_modules/@credcli/cli/.browsers \
  credcli run <job> --format png

The setup script prints this exact command at the end so you can copy it from there.

Every CredCLI operation requires a Chainletter workspace token. You receive this as a shortlink URL from your Chainletter account.

# Claim your token from a Chainletter shortlink
credcli register https://yourserver.chainletter.io/jwt/abc123

# Verify it was saved correctly
credcli register -i

This creates a token.json file in your working directory containing:

{
  "jwt":        "eyJhbGci...",   // Bearer token for API calls
  "webhookUrl": "https://yourserver.chainletter.io/webhook/...",
  "tenant":     "yourname",      // Used as .data/ subdirectory
  "groupname":  "spring-2026",
  "expires":    "2027-01-01T00:00:00Z"
}

Set workspace identity

Your issuer name and logo are automatically injected into every rendered credential as {{WorkspaceIssuer}} and {{WorkspaceLogo}}. Set them once:

credcli workspace --issuer "Acme University"
credcli workspace --logo ./logo.png   # PNG/JPG/SVG → embedded as base64
credcli workspace                     # view current values

CredCLI is designed to be orchestrated by Claude Code. Run the commands below in your working directory — Claude Code picks up the reference files automatically and gains detailed knowledge of every command, flag, and workflow:

# Write CLAUDE.md (short quick-reference, auto-loaded by Claude Code)
credcli help -c

# Write SKILL.MD (full agent reference with API docs and patterns)
credcli help -s

The full end-to-end workflow takes a CSV of recipients, renders one credential per row, uploads to IPFS, and blockchain-stamps the collection. Each step is idempotent — safe to repeat or resume.

credcli workspace --issuer "Acme University"
credcli workspace --logo ./logo.png

credcli templates

credcli new --template 4   # template 4 = Diploma
# Creates: .data/{tenant}/jobs/job001/

credcli csv job001 students.csv

FullName,Title,Institution,Major,IssueDate,CredentialID
Jane Smith,Bachelor of Science,Acme University,Computer Science,2026-06-01,CRED-0001
Alex Jones,Bachelor of Arts,Acme University,History,2026-06-01,CRED-0002

credcli run job001 --format pdf
# or: --format png  (default)
# or: --limit 5     (render first 5 rows only, for testing)
# or: --resume      (skip already-rendered files)

credcli output job001   # list generated file paths

credcli assign job001 spring-2026 --network public

credcli send job001 --yes

credcli stamp job001

credcli email job001

# To use a specific email template:
credcli email job001 --email-template credential-claim-email_600x900.html

Full workflow at a glance

# ── One-shot copy-paste workflow ─────────────────────────────────────────────
credcli register https://server.chainletter.io/jwt/abc123
credcli workspace --issuer "Acme University" --logo ./logo.png
credcli templates
credcli new --template 4
credcli csv job001 students.csv
credcli run job001 --format pdf
credcli assign job001 spring-2026 --network public
credcli send job001 --yes
credcli stamp job001
credcli email job001

Check remaining credits

credcli credits

Mail merge is the core of CredCLI's batch processing: one CSV row = one credential = one email. You don't have to use the email step, but it completes the delivery loop from stamped credential to recipient inbox.

How it works

After credcli stamp job001, each credential has a unique claim URL stored in job.json. The email command uses your CSV data plus those claim URLs to render an email template for each recipient:

credcli email job001
# Output: job001/output/mail_merge/
#   ├── Jane_Smith_CRED-0001.eml
#   ├── Alex_Jones_CRED-0002.eml
#   ├── all_recipients.mbox       ← archive of all emails
#   └── mail_merge_manifest.csv   ← metadata: name, email, file, claim URL

CSV format rules

• First row is the header — column names are case-sensitive and must match the template's field list exactly
• One row per credential; blank rows are skipped
• {{FieldName}} placeholders in the HTML template are replaced by the matching column value
• Extra columns in the CSV are ignored; missing columns render as empty string
• Include an Email column if you want email delivery

All available field names

These are the recognized placeholder names for use in templates and CSV headers:

Custom email templates

The email template is itself an HTML file with {{Placeholder}} syntax. The built-in template (template #6) works out of the box. To use a custom one:

credcli email job001 --email-template my-email-template.html

SMTP auto-send

If SMTP credentials are stored in workspace settings (.data/{tenant}/workspace.json), emails are sent automatically rather than written to .eml files. Configure SMTP via the web UI (credcli serve) or set environment variables:

[email protected]
TEST_SENDER_PW=your-app-password

Public vs. private collections

Every CLI command has a browser-based equivalent. The web UI is useful for visual template editing, drag-and-drop CSV upload, and monitoring render progress.

credcli serve              # opens localhost:3037
credcli serve --port 8080  # custom port

Run credcli templates to see the full field list for each template at any time.

Custom templates

Any HTML file in .data/{tenant}/templates/ with a metadata comment is recognized as a template:

<!-- Add this near the top of your HTML file -->
<!--CREDCLI:{"name":"My Diploma","width":1200,"height":900,
             "fields":["FullName","Programme","IssueDate","CredentialID"]}-->

<!-- Use {{FieldName}} placeholders in the body -->
<h1>{{FullName}}</h1>
<p>{{Programme}} — {{IssueDate}}</p>

After saving, run credcli templates — your template appears immediately. Use credcli serve for a live browser-based editor.

Full command reference