pinbox pin

$ pinbox pin --help
Usage: pinbox pin [options] <text>

Create a pin from the terminal. No browser is involved, so nothing about one is recorded: anchor the
pin to a source location with --file, or to a web surface with --url.

Arguments:
  text                  what needs to change, in your words

Options:
  --file <path[:line]>  anchor to a source location (recorded repo-relative)
  --url <url>           the web surface this pin is about
  --selector <sel>      CSS selector on that surface (needs --url)
  --json                machine output
  -h, --help            display help for command

$ pinbox pin "the checkout button is dead on iOS" --file src/app.tsx:12
pin_ywhqc5wr6t
pinned to src/app.tsx:12

$ pinbox pin "shorten the onboarding copy"
pin_kgoksic8rz
pinned

$ pinbox pin "docs page 404s" --url https://example.com/docs
pin_gxm28b6kvh
pinned to https://example.com/docs

$ pinbox pin "pricing page 404s" --url https://example.com/pricing --selector "a.pricing"
pin_7owz5vocwn
pinned to https://example.com/pricing

$ pinbox pin "the footer overlaps at 320px" --file src/app.tsx --json
{
  "ok": true,
  "data": {
    "text": "the footer overlaps at 320px",
    "kind": "note",
    "target": {
      "source": {
        "file": "src/app.tsx",
        "via": "none"
      }
    },
    "env": {
      "branch": "main",
      "commit": "40a41305d1d1f73aff9884493cfe72474b4c5cee"
    },
    "author": {
      "userId": "ada@example.com",
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    },
    "id": "pin_342q5tqwap",
    "schemaVersion": 1,
    "status": "open",
    "createdAt": "2026-08-06T21:21:00.623Z"
  }
}

id=$(pinbox pin "the footer overlaps at 320px" --json | jq -r .data.id)
pinbox show "$id" --json

$ pinbox pin "the footer overlaps on mobile" --file src/nope.tsx:42
pinbox: no such file: "src/nope.tsx"
--file takes a path that exists, optionally with :line
$ echo $?
2

$ pinbox pin "pricing page 404s" --selector "a.pricing"
pinbox: --selector needs --url (a selector without a page is not a target)
run `pinbox pin --help` for usage
$ echo $?
2

$ pinbox pin "docs page 404s" --url localhost:3000
pinbox: invalid --url: "localhost:3000" (expected an absolute URL)
run `pinbox pin --help` for usage
$ echo $?
2

$ pinbox pin ""
pinbox: pin text must not be empty
quote the text: pinbox pin "your text"
$ echo $?
2