pinbox reply

pinbox reply is how a pin stays a conversation. Use it to ask a clarifying question, to report what you found, or to say what you are about to change. It never resolves the pin — that is pinbox resolve.

Usage

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

Add a thread message to a pin. Replying never resolves.

Arguments:
  id           pin id (pin_xxxxxxxxxx)
  text         the message

Options:
  --as <role>  author role: human or agent (default: "human")
  --json       machine output
  -h, --help   display help for command

Arguments

string

required

Pin id (pin_xxxxxxxxxx). Ids are exact — prefixes do not match.

string

required

The message. Quote it, and make it non-empty.

Options

string

default:"human"

Author role: human or agent. Agents should pass --as agent so the thread reads correctly to whoever opens it next.

boolean

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

Examples

The new message id goes to stdout; the confirmation goes to stderr.

$ pinbox reply pin_6dzjtpax70 "does this also happen at 1024px?"
msg_czd5qb0s3r
replied to pin_6dzjtpax70 as human

$ pinbox reply pin_6dzjtpax70 "Yes — same overflow at 1024. One fix covers both." --as agent
msg_8k9qicaruf
replied to pin_6dzjtpax70 as agent

Both messages then appear under the pin in pinbox show, oldest first.

JSON

data is the created thread message.

$ pinbox reply pin_jxf6qu4hpg "checking the route table now" --as agent --json
{
  "ok": true,
  "data": {
    "id": "msg_2iz3pncriq",
    "pinId": "pin_jxf6qu4hpg",
    "role": "agent",
    "text": "checking the route table now",
    "at": "2026-08-06T21:21:01.558Z"
  }
}

When a pin is ambiguous, reply with a question instead of guessing. The person who dropped it is usually still in the app.

Errors

Exit	Code	When
2	`E_INVALID_INPUT`	empty text, a missing argument, or `--as` outside `human`/`agent`
3	`E_NOT_FOUND`	no pin has that id
5	`E_HUB_UNREACHABLE`	the hub is absent and could not be started

$ pinbox reply pin_kgoksic8rz ""
pinbox: reply text must not be empty
quote the message: pinbox reply <id> "your text"
$ echo $?
2

$ pinbox reply pin_kgoksic8rz "hi" --as bot
pinbox: invalid --as: "bot" (expected human or agent)
run `pinbox reply --help` for usage
$ echo $?
2

$ pinbox reply pin_0000000000 "hi"
pinbox: no pin with id pin_0000000000
run `pinbox list` to see valid ids (full ids only — prefixes don't match)
$ echo $?
3

Next: read the thread back with pinbox show, or close the pin with pinbox resolve.

Getting started

CLI

Concepts

Integrations

Self-hosting

Contributing

Usage

Arguments

Options

Examples

JSON

Errors

​Usage

​Arguments

​Options

​Examples

​JSON

​Errors

Usage

Arguments

Options

Examples

JSON

Errors