Human? Visit human.md/sapien.html for the human-readable version.
================================================================================
human.md — the human API for agents
================================================================================
Agents are connected to everything except the humans they work for.
`human` gives any agent a one-line way to reach a real person on Telegram
(Slack coming next) and block until they answer.
INSTALL
-------
npm install -g @novu/human
SETUP (once, by the human)
---------------------------
npx @novu/human setup # interactive channel picker
npx @novu/human setup telegram
npx @novu/human setup slack
USAGE (forever after, by any agent on the machine)
----------------------------------------------------
human inbox ask "Which environment should I deploy to?"
human inbox approve "Delete 342 stale records from prod?"
human inbox choose "Pick a release strategy" --option canary --option blue-green
human inbox tell "Nightly build finished — 0 failures."
human contact list # who --to can address
human contact list --json
THE INBOX (people can write to your agent first)
-------------------------------------------------
human inbox list --filter unread # threads waiting for you
human inbox show conv_123 # read one (does not mark it read)
human inbox tell "On it." --thread conv_123 # reply in the thread
human inbox resolve conv_123 # finished
HOW IT WORKS
------------
- `setup` provisions a keyless Novu environment (no account needed), a
hidden relay agent, and links a channel — Telegram via QR, Slack via
app install. Add more with `human channel add `. Linked
channels live on the server; `human channel default slack` sets
the local preference when you don't pass `--via`.
- Telegram is a private bot only you control. On a terminal, `setup
telegram` asks whether to paste the BotFather token here or finish on
https://www.agentinbox.md/connect (QR or browser). Without a terminal it
prints that page and waits (up to 15 min) until you tap Start. Re-run
`human setup telegram` to resume at the missing step.
--telegram-bot-token skips the choice.
- Slack is the same shape: paste an App Configuration Token (xoxe.xoxp-…)
in the terminal, or open https://www.agentinbox.md/connect?channel=slack
and click Add to Slack. --slack-config-token skips the choice. Exit 11
means the human didn't finish; re-run the same command.
- Agents stay channel-blind: routing is the human's preference.
`--via telegram|slack|email` exists as a rare per-call override.
- Each command delivers a one-off message (with action buttons where
relevant) and BLOCKS until the human answers, the --ttl expires, or
--timeout elapses.
- Answers flow back through button clicks or plain replies; the CLI
resolves and your agent continues.
- `contact list` lists every subscriber `--to` can address so an agent
can check who exists before coordinating. It's a directory, not a
reachability check.
EXIT CODES (stable contract for agents)
----------------------------------------
0 answered / approved / chosen / delivered
10 denied
11 timed out waiting — still pending, resume with `human interaction wait `
12 expired or canceled
1 error
FLAGS
-----
--from attribution shown to the human ("Requested by deploy-bot")
--ttl how long the request stays answerable (default 24h, max 72h)
--timeout max time this invocation blocks; on timeout it prints
the id so `human interaction wait ` can resume
--async don't block; print the interaction id immediately
--json full interaction object for programmatic parsing
--to address a linked human, or comma-separated humans
(find them with `human contact list`; link others
first with `human contact invite`)
--via deliver on a specific linked channel instead of default
INVITE (link another human)
---------------------------
human contact invite alice --via slack --name "Alice Chen"
human contact invite bob --via telegram --async
human contact invite carol --via email --email carol@acme.com --name "Carol Diaz"
Prints a connect URL for that person (same OAuth / Telegram deep-link
as setup). Does not change your local subscriberId. After they connect,
address them with --to. Pass --name so they show up by name in contacts.
CONTACTS (who agents can reach)
-------------------------------
human contact list
human contact list --json
human contact list --limit 20 --after
Lists every subscriber in the environment — the directory `--to`
addresses. The operator's row is marked (you) / self: true. A directory,
not a reachability check: if delivery fails with "no linked endpoint",
invite them on that channel. Pages are 50 by default (max 100); when
next is set, continue with --after.
AUTH
----
`setup` stores credentials in ~/.novu/human.json. Alternatively set
NOVU_SECRET_KEY (and optionally NOVU_API_URL) for an existing Novu
environment.
LINKS
-----
npm https://www.npmjs.com/package/@novu/human
source https://github.com/novuhq/novu/tree/main/packages/human
human https://human.md/sapien.html
================================================================================
MIT License — built by Novu (https://novu.co)
================================================================================