> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinbox.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# pinbox reply

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

`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`](/cli/commands/resolve).

## Usage

```console theme={null}
$ 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

<ParamField path="id" type="string" required>
  Pin id (`pin_xxxxxxxxxx`). Ids are exact — prefixes do not match.
</ParamField>

<ParamField path="text" type="string" required>
  The message. Quote it, and make it non-empty.
</ParamField>

## Options

<ParamField path="--as" type="string" default="human">
  Author role: `human` or `agent`. Agents should pass `--as agent` so the thread reads
  correctly to whoever opens it next.
</ParamField>

<ParamField path="--json" type="boolean">
  Machine output: the `{"ok":true,"data":…}` envelope.
</ParamField>

## Examples

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

```console theme={null}
$ pinbox reply pin_6dzjtpax70 "does this also happen at 1024px?"
msg_czd5qb0s3r
replied to pin_6dzjtpax70 as human
```

```console theme={null}
$ 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`](/cli/commands/show), oldest
first.

### JSON

`data` is the created thread message.

```console theme={null}
$ 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"
  }
}
```

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

## 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                        |

```console theme={null}
$ pinbox reply pin_kgoksic8rz ""
pinbox: reply text must not be empty
quote the message: pinbox reply <id> "your text"
$ echo $?
2
```

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

```console theme={null}
$ 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`](/cli/commands/show), or close the pin with
[`pinbox resolve`](/cli/commands/resolve).