suppyhq-cli

Official CLI for SuppyHQ. Drive your inbox from the terminal — or let an AI agent (Claude Code, Cursor, Codex, OpenCode) do it for you.

curl -fsSL https://suppyhq.com/install-cli | bash
suppyhq auth login
suppyhq setup claude

What it does

Agent contract

Structured output for humans and machines:

suppyhq inbox --json       # {ok, data, summary, breadcrumbs}
suppyhq inbox --agent      # raw data only (for scripts)
suppyhq commands --json    # full command catalog
suppyhq help --agent       # structured help for any command

Errors carry code, retryable, and hint with typed exit codes (auth=3, forbidden=4, rate_limit=5, …). GET requests retry on 429/5xx; writes never auto-retry.

MCP

Register with any MCP client as a stdio server:

claude mcp add suppyhq -- suppyhq mcp
suppyhq mcp --read-only
suppyhq mcp --domains=conversations,customers

Three domain tools: suppyhq_conversations, suppyhq_customers, suppyhq_identity. Each dispatches {"action":"...", "params":{...}}. Use action: "describe" for schemas.

Install

Quick install (Linux / macOS)

curl -fsSL https://suppyhq.com/install-cli | bash
# Force a specific agent during install:
SUPPYHQ_SETUP_AGENT=claude curl -fsSL https://suppyhq.com/install-cli | bash

The installer downloads the binary, runs suppyhq setup agents (skill + best-effort agent connection), and prints PATH hints. Managed skills (.managed-by-suppyhq-cli) refresh automatically on suppyhq upgrade and the first run of each new version.

Manual

Grab the latest release.

Install the plugin

One install per agent. Each one gives you the skill (how to work an inbox) and the suppyhq MCP server (the tools it calls). Restart the agent session after.

Claude Code

suppyhq setup claude

Or from the marketplace, without the CLI doing it for you:

/plugin marketplace add karloscodes/suppyhq-cli
/plugin install suppyhq

Cursor

suppyhq setup cursor

Cursor reads skills per project, so run this from the repo you want it in. To install it as a plugin instead, point Cursor at this repo from Dashboard > Plugins > Add Marketplace > Import from Repo.

Codex

suppyhq setup codex

opencode

suppyhq install-skill --target=opencode

opencode loads Agent Skills directly, so the skill is the whole install. Register the MCP server in your opencode config as a stdio server running suppyhq mcp.

Everything you have

suppyhq setup agents     # skill + every agent found on this machine
suppyhq doctor           # check CLI, auth, skill, and plugin health

How the plugin is put together

This repo is an Agent Plugins 1.0.0 package. plugin.json and mcp.json sit at the root next to skills/, so a client that reads the standard gets the skill and the MCP server in one step.

Clients that prefer their own manifest find one: .claude-plugin/plugin.json, .cursor-plugin/plugin.json, .codex-plugin/plugin.json. All of them point at the same skills/ directory, which the binary also embeds, so the skill exists exactly once here.

Tests keep it honest. The manifests must agree on name and version, only one SKILL.md may exist, and every command and flag the skill mentions has to exist in commandCatalog(). Deliberate exceptions live in .skill-drift-allowlist.

Configuration

Examples

suppyhq inbox --json | jq '.data[] | select(.status=="open")'
suppyhq thread 42 --agent | jq '.messages[-1]'
echo "<p>Yes — out by Friday.</p>" | suppyhq reply 42 --draft
suppyhq doctor

Development

go test ./...
go build -o suppyhq .

License

MIT — see LICENSE.