pinbox pin

pinbox pin writes a pin straight from your shell. Reach for it when you want to try pinbox before wiring up the toolbar, or when the thing that needs changing is in the code rather than on a page. Because there is no browser, a terminal pin records nothing about one — no viewport, no screenshot, no element rectangle. It carries only what is true: your text, whatever place you named, your git identity, and the branch and commit the hub stamps on every pin.

Usage

$ 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)
  --model-anchor <json> a revision-qualified 3D model/part anchor
  --author-json <json>  asserted identity supplied by a trusted backend
  --comment             a note for people, not a task: no agent is woken for it
  --json                machine output
  -h, --help            display help for command

Arguments

string

required

What needs to change, in your words. Quote it — it is one argument, not several.

Options

path[:line]

Anchor to a source location (recorded repo-relative). The path must exist. It is stored relative to the repo root, so the anchor still resolves on another machine. :line is optional.

url

The web surface this pin is about. Must be an absolute http or https URL.

string

CSS selector on that surface. Requires --url — a selector with no page is not a target.

boolean

A note for people, not a task. The pin is stored with kind: "comment"; the hub never routes it to an agent session, and the agent skill tells agents to read such pins as context and never act on or resolve them. The toolbar’s Note option creates the same kind. Filter them with pinbox list --kind comment.

boolean

Machine output: the {"ok":true,"data":…} envelope.

3D targets

Use --model-anchor <json> to attach the pin to a part-local 3D point. A trusted backend can supply its verified user with --author-json <json>. See 3D model pins for the schema, security boundary, and viewer integration.

Examples

The new pin id goes to stdout. The confirmation goes to stderr, so 2>/dev/null leaves you with just the id.

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

With no anchor at all — a note about the product, not about a place:

$ pinbox pin "shorten the onboarding copy"
pin_kgoksic8rz
pinned

About a page you never opened:

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

With a selector on that page. The confirmation names the page, and the selector is stored on the pin:

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

JSON

data is the created pin. Note what is absent: no env.viewport, no target.rect. Absent, not zeroed.

$ 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"
  }
}

To capture the id in a script, parse the envelope rather than the human line — a pipe switches the command to JSON mode anyway:

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

Errors

Exit	Code	When
2	`E_INVALID_INPUT`	`text` is missing or empty, `--file` points at nothing, `--url` is not absolute, or `--selector` has no `--url`
5	`E_HUB_UNREACHABLE`	the hub is absent and could not be started

A --file that points at nothing is rejected before the pin is created. An agent sent to a path that does not exist is worse off than one with no anchor at all.

$ 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

Next: read it back with pinbox show, find it again with pinbox list, or close it out with pinbox resolve.

Getting started

CLI

Concepts

Integrations

Self-hosting

Contributing

Usage

Arguments

Options

3D targets

Examples

JSON

Errors

​Usage

​Arguments

​Options

​3D targets

​Examples

​JSON

​Errors

Usage

Arguments

Options

3D targets

Examples

JSON

Errors