CLI

@pinwren/cli (MIT) installs the pinwren command: one self-contained file with no dependencies. It needs Node 20 or newer. Run it with npx, or install it globally:

npx @pinwren/cli --help

npm install -g @pinwren/cli

pinwren init   [--url <instance>] [--key <pk_…>] [--framework html|vite|next] [--write] [--file <path>]
pinwren doctor --url <instance> [--key <pk_…>] [--origin <https://your-site>] [--json]
pinwren status --url <instance> --token <pwt_…> [--json]
pinwren feedback list  --url <instance> --token <pwt_…> [--project <id>] [--status <s>] [--kind <k>] [--text <q>] [--limit <n>] [--json]
pinwren feedback get   <id> --url <instance> --token <pwt_…> [--json]
pinwren feedback brief <id> --url <instance> --token <pwt_…> [--json]
pinwren repro <id>          --url <instance> --token <pwt_…> [--out <file.spec.ts>] [--json]
pinwren release create <version> --project <id|slug> --url <instance> --token <pwt_…> [--commit <sha>] [--notes <text>] [--deployed-at <iso>] [--json]
pinwren release list   --project <id|slug> --url <instance> --token <pwt_…> [--json]

-h / --help prints the usage and -v / --version the version. The environment variables PINWREN_URL, PINWREN_KEY and PINWREN_TOKEN fill the matching flags.

pinwren initCopy Anchor Link

Prints the widget snippet for the project in the current folder — or, with --write, inserts it.

• URL and key. It asks for your Pinwren URL and the project's public key (pk_…, from the project's Install tab) unless you pass --url / --key (or set PINWREN_URL / PINWREN_KEY). Outside an interactive terminal, a missing value is an error.
• Framework. It reads package.json in the current folder: next in the dependencies or devDependencies means Next.js, vite means Vite, anything else plain HTML. Override it with --framework html|vite|next.
• --write. For HTML and Vite it adds the script tag before </body> of index.html (or public/index.html, src/index.html); for Next.js it adds a Script element from next/script before </body> of app/layout.tsx (or src/app/layout.tsx, or the .jsx versions) and imports next/script once. Use --file to choose another file. It never adds the widget twice. Without --write it prints the snippet and the pinwren doctor command to check it.

pinwren init --url https://feedback.example.com --key pk_123… --write
pinwren init --framework html --file public/index.html --write

The HTML snippet is the one-line script tag described in install the widget:

<script src="https://feedback.example.com/widget.js" data-project="pk_…" async></script>

For Next.js it is:

<Script src="https://feedback.example.com/widget.js" data-project="pk_…" strategy="afterInteractive" />

Remember to add the site's origin (e.g. localhost:5173 while you develop) to the project's allowed sites.

pinwren doctorCopy Anchor Link

Checks a running instance and exits with 1 if anything fails. Without --key the widget config check is skipped (shown with -, not a failure):

pinwren doctor --url https://feedback.example.com --key pk_123… --origin https://www.example.com

✓ server: reachable, Pinwren 0.1.0
✓ widget.js: served
✓ widget config: project "Marketing site" accepts https://www.example.com

Add --json for machine-readable output ({ ok, checks: [{ name, ok, detail }] }). Use it after an upgrade, behind a new reverse proxy, or when the widget doesn't appear.

pinwren statusCopy Anchor Link

Shows who an API token acts as, and every project with its open feedback count (open, in progress and in review):

pinwren status --url https://feedback.example.com --token pwt_…

Signed in as Ada Lovelace (owner)
  Marketing site    12 open
  Docs               3 open

It calls GET /api/v1/token and GET /api/v1/projects, so a token with the feedback:read scope is enough. --json prints { user, role, projects: [{ id, name, openCount }] }.

pinwren feedbackCopy Anchor Link

Search and read feedback from the terminal, with a token that has the feedback:read scope.

pinwren feedback list --url https://feedback.example.com --token pwt_… --status open --kind bug --limit 10
pinwren feedback get 0192f0c4-4f6e-7c1a-8d55-9a3e2b1c4d5e

list prints one line per item (number, id, status, priority, kind, title); report text is cut to one line and stripped of control characters. --status takes a status or active / all. --json prints the API's answer.

brief prints the agent-ready brief as Markdown — the same text as Fix with agent in the dashboard and the MCP tool get_agent_brief. It is built from the stored, masked diagnostics; the replay and screenshot are linked, never included. Pipe it straight into a coding agent:

pinwren feedback brief 0192f0c4-… | claude -p "Fix the issue described in this Pinwren brief."

pinwren reproCopy Anchor Link

Prints a draft Playwright test (TypeScript) for the report, or saves it with --out:

pinwren repro 0192f0c4-… --out tests/pinwren-142.spec.ts

The test opens the page, replays the interactions from the session replay when one was recorded, and asserts on the console errors, failing requests or pinned element in the report. It is generated without a model and is a starting point, not a verified test: the caveats are printed to stderr (and written in the file's header), so read, run and adjust it before you rely on it.

pinwren releaseCopy Anchor Link

Records the releases of a project, for a CI job to run after each deploy, with a token that has the releases:write scope. --project takes the project's id or slug (or set PINWREN_PROJECT):

pinwren release create v1.4.0 --project marketing-site --commit "$GIT_SHA" --url https://feedback.example.com
pinwren release list --project marketing-site

create is safe to run twice: the same version updates the release. When items were resolved as "fixed in the next release", it says how many are now fixed in this one. list prints each release with the items fixed in it and the regressions reported from it. See Releases and regressions.