@helloaigent-dev/cli

@helloaigent-dev/cli

Hello Aigent publisher CLI — a thin, dependency-free wrapper over the Hello Aigent publisher API (POST /v0/feeds, GET /v0/feeds, GET .../discovery.json, POST /v0/publish, GET .../health). Create a feed and publish signed updates from a terminal — or from your agent — with no UI required.

The producer-side counterpart to @helloaigent-dev/subscriber (which lets an agent subscribe/fetch/act) and @helloaigent-dev/publisher (the same operations as an MCP server, for agents that prefer tool calls over a CLI).

Install

npm i -g @helloaigent-dev/cli

If a global install isn't an option in your environment, every command below has a plain curl equivalent — see the docs linked from each command.

Commands

helloaigent feed create   --title <t> --publisher <name> --site <url> --description <d>
                          [--topics a,b,c] [--id <slug>]   (needs a workspace API key or admin token)
helloaigent feed list                                       (needs a workspace API key or admin token)
helloaigent feed discovery <feed-id> [--out <file>]         (public)
helloaigent publish       --feed <id> --type <offer|announcement|restock|content>
                          --title <t> --summary <s> (--body <md> | --body-file <path>)
                          [--data <json>] [--action <json> ...]   (needs a publish token, or a
                          workspace API key for a feed you own)
helloaigent health <feed-id>                                (public) discovery reachable,
                          key present, schema sanity — exits 1 if degraded
helloaigent help                                             (also: no args, or --help)

• feed create — mint a feed + Ed25519 keypair + publisher token. The publisher token is shown once in the response — save it immediately.
• feed list — with a workspace API key, lists only your workspace's feeds; with the admin token, lists every feed.
• feed discovery <feed-id> — fetch the generated hello-aigent.json discovery document for a feed. Public, no auth needed. --out <file> writes it to disk instead of stdout (useful for mirroring it to your own site's /.well-known/hello-aigent.json).
• publish — build and publish a signed update to a feed. --data takes a JSON object string; repeat --action for each callable action (each one a JSON object: { name, endpoint, input_schema }). Provide the markdown body with either --body <text> or --body-file <path>.
• health <feed-id> — checks discovery reachability, signing-key presence, and schema sanity for a feed. Public, no auth needed. Exits with status 1 if the feed is degraded, so it's safe to use in a CI or deploy-verification step.

Auth

Every command reads config from flags or environment variables (flags win):

Flag	Env var	Used by	Default
--api <url>	HELLOAIGENT_API	all commands	https://api.helloaigent.dev
--api-key <key>	HELLOAIGENT_API_KEY	feed create, feed list, publish (fallback)	—
--admin-token <tok>	HELLOAIGENT_ADMIN_TOKEN	feed create, feed list	—
--token <tok>	HELLOAIGENT_TOKEN	publish	—

feed discovery and health are public reads and need no token.

Workspace API key vs. admin token: --api-key / HELLOAIGENT_API_KEY is a hak_... workspace API key, minted from the Hello Aigent console (Settings → API keys) once you've signed up. It scopes feed create/feed list/publish to your own workspace and is what a self-serve account actually gets — it cannot create, list, or revoke API keys (that requires signing in to the console itself). --admin-token / HELLOAIGENT_ADMIN_TOKEN is a separate, unrestricted, ops-only credential not handed out to self-serve accounts. Where both feed create/feed list accept either, the workspace API key is preferred when both are set; publish prefers --token (a feed's own publisher token) first, then falls back to --api-key.

Example

export HELLOAIGENT_API_KEY=hak_...   # from the console's API keys screen

helloaigent feed create --title "Acme Roast Drops" --publisher "Acme Coffee" \
  --site https://acme.example --description "Restocks & offers" --topics restocks,offers
# ✅ feed created: acme-roast-drops
#   publisher token (shown once — save it now):
#     publisher_...
#   signing public key: ed25519:...
#   discovery URL:      https://api.helloaigent.dev/v0/feeds/acme-roast-drops/discovery.json
#   publish URL:        https://api.helloaigent.dev/v0/publish

export HELLOAIGENT_TOKEN=publisher_...   # the token from the step above

helloaigent publish --feed acme-roast-drops --type restock \
  --title "Yirgacheffe back in stock" --summary "Agent-exclusive early access" \
  --body "# Back in stock" --data '{"sku":"ETH-YIRG"}'
# ✅ published to acme-roast-drops: msg_...
#   signature: ed25519:...

helloaigent health acme-roast-drops
# ✅ acme-roast-drops: ok
#   ✓ feed_active
#   ✓ discovery_reachable
#   ✓ signing_public_key_present
#   ✓ schema_sanity

License

MIT