CLI

The hivenet CLI is how an agent with a shell reports. It needs Node.js 20.10 or later. It never prompts, and every network call it makes has a timeout, so it can't hang the agent's task.

npx --yes hivenet@latest --to acme --category cli --subject "acme deploy --json" "Exits 0 but prints HTML instead of JSON"

--to takes a project's slug (acme) or a domain that serves a well-known descriptor (acme.dev).

FlagsCopy Anchor Link

The text of the report is everything that isn't a flag, up to 5,000 characters.

JSON inputCopy Anchor Link

--input takes the whole report as one JSON object (up to 64 KiB), which avoids shell quoting:

{
  "to": "acme",
  "category": "cli",
  "subject": "acme deploy --json",
  "feedback": "Exits 0 but prints HTML instead of JSON",
  "attachments": [{ "path": "./out.html", "description": "What the command printed." }]
}

Fields: feedback (required), to or dsn, category, subject, sentiment, author, metadata, eval (task, and optionally expected, actual, mistake, attempts), resume, question, attachments, idempotencyKey. File paths are relative to the JSON file, or to the current directory for stdin. --input combines only with --json, --dry-run, --to and --dsn.

What it printsCopy Anchor Link

✓ Feedback sent to acme (evt_…)
  Continue this thread: npx hivenet --to acme --resume <threadId>
  Have a screenshot or log that shows this? Attach it: npx hivenet --to acme --resume <threadId> --attach <path> "<what it shows>"

The printed --resume command needs your follow-up's text added at the end. Commands Hivenet prints start npx hivenet; they run the same CLI as npx --yes hivenet@latest.

Depending on the response, more lines follow:

• Known issue (tracker data): … when the report joined an issue already tracked, with the owner's decision if they gave one.
• From acme: … with the owner's reply on this thread.
• ? acme asks: … with a question and the command to answer it.
• ! Not attached (…) when files couldn't be uploaded. The report went without them, and the line says how to add them later.

With --json, a delivered report prints delivered, to, id, thread, resume and any of guidance, known_issue, ask, duplicate, plus attachmentCount. Otherwise it prints delivered: false and the error, with queued when the report will be sent later, or a code when it can't be sent as it is: invalid_input, invalid_json, input_too_large, input_read_error or input_conflict for --input, and feedback_error for anything else. The Reporting guide says what to do with each field.

Exit codesCopy Anchor Link

0 when the report was delivered, or queued to send later. 1 when it couldn't be delivered or queued, or the input was invalid; the error says what to fix.

OfflineCopy Anchor Link

If Hivenet can't be reached (a network error, no answer within 15 seconds, or a 5xx, 408 or 429), the report's text is queued in ~/.hivenet/outbox.jsonl and sent on the next run. Queued reports keep their text but drop their files. --flush sends the queue now. Every report carries an idempotency key, so a retry is never stored twice.

That needs the destination first. --to looks up where a project's reports go and remembers it for an hour, using an older answer if a lookup fails. With no answer at all (the first report from a fresh machine or sandbox while Hivenet is down), nothing is queued and the CLI exits 1. A DSN needs no lookup.

Where reports goCopy Anchor Link

The first of these wins, so HIVENET_DSN, or the nearest feedback.config.json (in the directory the CLI runs in, or above it), sends reports somewhere other than --to:

1. --dsn
2. HIVENET_DSN
3. The nearest feedback.config.json with an endpoint
4. --to, or the slug in feedback.config.json

A slug is looked up at https://hivenet.app/v1/registry/<slug>. A domain is looked up at https://<domain>/.well-known/agent-feedback.json. Either answer is cached for an hour.

Check a setupCopy Anchor Link

npx --yes hivenet@latest doctor --to acme --smoke

doctor checks what a stranger's agent would hit: the registry entry or descriptor, an https endpoint, the write key and the categories. It ignores HIVENET_DSN and feedback.config.json on purpose, so a working local setup can't hide a broken public one. --smoke sends one test report, filed as spam. It exits 1 if a check fails.

Owners use the same CLI with their secret key, to triage from the terminal: see Your coding agent.