{
  "markdown": "# @supstack/cli\n\nEvidence-based supplement intelligence in your terminal — and an MCP server for AI agents.\n\nA thin client over the public [SupStack API](https://supstack.me/api). Read-only,\nno account required. One capability registry powers both the CLI and the MCP server.\n\n> **Status: Phase 2 (accounts) in progress.** All read commands below work, plus\n> an MCP server and `login`/`whoami`. Install with `npm install -g @supstack/cli`.\n\n## Install\n\n```bash\n# Homebrew (macOS / Linux)\nbrew install drbaher/supstack/supstack\n\n# or npm\nnpm install -g @supstack/cli\n\n# or run without installing\nnpx -y @supstack/cli define adaptogen\n```\n\nThen enable shell completion: `supstack completion install`.\n\nFrom source (in this directory): `npm install && npm run build && node dist/index.js define adaptogen`.\n\n## Usage\n\n```bash\nsupstack research magnesium --protocol       # full evidence summary for one supplement\nsupstack search --goal deep-sleep -n 5       # search by name or filter\nsupstack compare magnesium glycine           # 2–3 head-to-head\nsupstack studies \"sleep\" --type rct          # research library\nsupstack interactions caffeine l-theanine --pathway   # interaction check (deep pair analysis)\nsupstack interactions magnesium potassium --medication lisinopril   # supplement × drug check\nsupstack stack add magnesium --dose 400mg --timing bedtime   # local stack (+ dose/timing/brand)\nsupstack stack sync                          # sync local ⇄ your account (login required)\nsupstack goals --category sleep              # list goal ids (for rate/recommend)\nsupstack rate --goals deep-sleep,sharpen-focus   # grade your stack A–F by goal coverage\nsupstack experiments start magnesium deep-sleep  # run an N-of-1 experiment (requires login)\nsupstack export --format md                  # export your stack\nsupstack define bioavailability              # glossary lookup\nsupstack <command> --json                    # machine-readable output on any command\nsupstack --help\n```\n\n### Account (Phase 2)\n\n```bash\nsupstack login          # sign in via device-code flow (opens the browser to confirm)\nsupstack whoami         # show the signed-in account\nsupstack logout         # sign out and revoke this device's token\n```\n\n`login` shows a one-time code, opens `https://supstack.me/activate`, and finishes\nonce you approve in the browser. The token lives in `~/.supstack/config.json`\n(`0600`). Reads work fully anonymously — an account unlocks personalized features.\n\nOnce logged in, sync your stack with your account:\n\n```bash\nsupstack stack pull     # local ← your account\nsupstack stack push     # local → your account (keeps dosage/timing/brand for kept items)\nsupstack stack sync     # additive merge of both; preserves existing cloud metadata\n\nsupstack profile                              # view your health profile\nsupstack profile set --age 35 --sex male --weight 80 --weight-unit kg\nsupstack recommend                            # personalized picks from your goals + stack\nsupstack experiments list                     # your N-of-1 experiments + verdicts\nsupstack track log                            # log today's stack as taken\nsupstack track adherence                      # your adherence rate, streak, per-supplement\n```\n\n### As an MCP server\n\n```bash\nsupstack mcp   # stdio MCP server exposing all capabilities as tools\n```\n\nThis gives an agent the full SupStack toolset. **Read-only** (no account needed):\n`supstack_research`, `supstack_search`, `supstack_compare`, `supstack_studies`,\n`supstack_interactions`, `supstack_stack`, `supstack_rate_stack`, `supstack_export`,\n`supstack_define`.\n\n**Account-scoped** tools are also exposed — `supstack_recommend`,\n`supstack_profile_get` / `supstack_profile_set`, `supstack_experiments_list` /\n`supstack_experiments_get`, `supstack_track_log`, `supstack_track_adherence`\n(plus cloud `supstack_stack` pull/push/sync). These require the user to be signed\nin (`supstack login`, or a `SUPSTACK_TOKEN`); without a token they return a clear\n\"not logged in\" error rather than failing. Mutating tools (`profile_set`,\n`track_log`) are flagged `readOnlyHint: false` for the agent.\n\n**Claude Code** (one command):\n\n```bash\nclaude mcp add supstack -- supstack mcp\n```\n\n**Claude Desktop** — add to `claude_desktop_config.json`\n(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"supstack\": {\n      \"command\": \"supstack\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n> Or run it without a global install via `\"command\": \"npx\", \"args\": [\"-y\", \"@supstack/cli\", \"mcp\"]`.\n> To use a local checkout, point at the built entrypoint —\n> `\"command\": \"node\", \"args\": [\"/absolute/path/to/supstack-cli/dist/index.js\", \"mcp\"]` (run `npm run build` first).\n\n## Configuration\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `SUPSTACK_API_URL` | `https://supstack.me/api/v1` | API base URL (override for local dev) |\n| `SUPSTACK_API_KEY` | — | Optional API key (anonymous works at 60/min/IP) |\n| `SUPSTACK_CACHE_TTL` | `3600` | Response cache TTL in seconds |\n| `SUPSTACK_NO_CACHE` | — | Set to disable the response cache |\n| `SUPSTACK_TIMEOUT` | `20` | Per-request timeout in seconds (or use `--timeout`) |\n| `SUPSTACK_HOME` | `~/.supstack` | Directory for config, stack, and cache |\n| `SUPSTACK_TOKEN` | — | Override the stored account token (from `supstack login`) |\n| `SUPSTACK_NO_ANON_TOKEN` | — | Disable auto-minting of the anonymous instant-token |\n| `SUPSTACK_NO_UPDATE_CHECK` | — | Disable the \"update available\" notice (also honours `NO_UPDATE_NOTIFIER`) |\n| `NO_COLOR` | — | Disable ANSI colour |\n| `FORCE_COLOR` | — | Force ANSI colour on (even when piped) |\n\nGlobal flags available on any command: `--json`, `--no-cache`, `--timeout <seconds>`, `--color` / `--no-color`, `-q, --quiet`.\n\n`supstack auth set-key <key>` persists a key to `~/.supstack/config.json` (written `0600`).\n\n### Response cache\n\nRead-only API responses are cached under `~/.supstack/cache/` (1-hour TTL by\ndefault) to keep repeat lookups well under the 60/min rate limit. Bypass it per\ncommand with `--no-cache`, or manage it with `supstack cache clear` /\n`supstack cache path`. The cache is bounded (oldest entries pruned past a cap).\n\n### Shell completion\n\nOne-step install for your current shell (writes the script and wires your rc file\nidempotently; `uninstall` reverses it):\n\n```bash\nsupstack completion install      # detects bash | zsh | fish from $SHELL\n```\n\n…or generate the script yourself:\n\n```bash\nsupstack completion bash >> ~/.bashrc\nsupstack completion zsh  > \"${fpath[1]}/_supstack\"\nsupstack completion fish > ~/.config/fish/completions/supstack.fish\n```\n\nCompletions are **dynamic** — the script forwards what you've typed to\n`supstack __complete`, which offers the right thing for the position:\n\n- top-level commands and sub-actions (`stack <TAB>` → `add remove list pull push sync`)\n- **supplement slugs** where a slug is expected (`research <TAB>`, `compare a <TAB>`, `stack add <TAB>`, `track log <TAB>`)\n- **goal ids** after `search --goal <TAB>`\n\nSlug/goal lists are fetched once from the API and cached under\n`~/.supstack/completion/` (24-hour TTL). Pre-warm or refresh them with:\n\n```bash\nsupstack completion refresh\n```\n\n### Exit codes\n\nCommands exit with a semantic code so scripts and MCP wrappers can branch on the\nkind of failure:\n\n| Code | Meaning |\n|------|---------|\n| `0` | Success |\n| `1` | Generic error (incl. 5xx) |\n| `2` | Auth required/rejected (not logged in, 401, 403) |\n| `3` | Not found (404) |\n| `4` | Rate limited (429) |\n| `5` | Network failure / timeout |\n| `6` | Invalid input (bad/missing args or flags, unknown command, schema validation, 400/422) |\n\n## Develop\n\n```bash\nnpm test            # unit tests (mocked fetch)\nnpm run type-check  # tsc --noEmit\nnpm run build       # tsup → dist/\n```\n\nSee [`CLAUDE.md`](./CLAUDE.md) for the capability pattern and how to add a command.\n\n## License\n\nMIT\n",
  "bytes": 7920,
  "sha": "bb95e0cd16dabec228c42b56bc78d47ab0bd6cd2ee0938c3467f39c78cbc7dda",
  "repo_slug": "drbaher/supstack-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_drbaher_supstack_a4f86fa1/readme"
}