CLI & MCP Server

@supstack/cli is an open-source command-line client and MCP server over the public SupStack API. Read-only, no account required. Open source (MIT). Thin client over the public SupStack API.

View source on GitHub →@supstack/cli on npm →

Install

brew install drbaher/supstack/supstack

…or via npm:

npm install -g @supstack/cli

…or run without installing:

npx -y @supstack/cli research magnesium

Then enable tab-completion: supstack completion install

Commands

Add --json to any command for machine-readable output. Every command maps to an MCP tool of the same capability.

supstack research <slug>supstack_research

Full evidence summary for one supplement — description, evidence score, dosage, and safety profile (warnings + drug interactions).

--protocol: Include the dosing protocol
--synergies: Include supplement synergies

supstack research magnesium --protocol

supstack research ashwagandha --json

supstack search [query]supstack_search

Search supplements by name (fuzzy), or filter the library by goal, category, type, minimum evidence, or safety rating.

-g, --goal <goal>: Filter by goal id (e.g. deep-sleep)
-c, --category <category>: Filter by category
-t, --type <type>: Filter by supplement type
-e, --evidence <level>: Minimum evidence: emerging | moderate | strong | very-strong
-s, --safety <rating>: Filter by safety: high | moderate | caution
-n, --limit <n>: Max results (default 10)

supstack search magnesium

supstack search --goal deep-sleep --evidence strong -n 5

supstack compare <a> <b> [c]supstack_compare

Compare 2–3 supplements head-to-head by evidence score, safety rating, and total studies, with per-category winners.

supstack compare magnesium glycine

supstack compare creatine beta-alanine citrulline

supstack studies [query]supstack_studies

Search the peer-reviewed research library by free-text query, study type, and supplement.

-t, --type <type>: Study type (e.g. rct, meta-analysis, systematic-review)
-s, --supplement <slug>: Filter by supplement slug
--sort <field>: Sort: newest | relevance | year (default newest)
-n, --limit <n>: Max results (default 10)

supstack studies sleep --type rct

supstack studies --supplement creatine --sort year

supstack interactions <supplements...>supstack_interactions

Check interactions across supplements. With --medication, checks each supplement against a drug (clinical severity). With --pathway on a pair, runs the biochemical engine (shared enzyme/receptor targets, mechanisms, synergy/conflict score).

--pathway: Deep biochemical pathway analysis (exactly 2 supplements)
-m, --medication <drug>: Check each supplement against a medication (e.g. lisinopril)

supstack interactions magnesium ashwagandha

supstack interactions caffeine l-theanine --pathway

supstack interactions magnesium potassium --medication lisinopril

supstack stack <add|remove|list> [slug]supstack_stack

Manage a local supplement stack stored in ~/.supstack/ (with optional per-supplement dose/timing/brand). Logged-in users can also sync it with their account (stack pull | push | sync — see Account commands).

--dose <dose>: Dosage for `add` (e.g. 400mg)
--timing <timing>: Timing for `add` (e.g. bedtime)
--brand <brand>: Brand for `add`

supstack stack add magnesium --dose 400mg --timing bedtime

supstack stack list

supstack rate [supplements...]supstack_rate_stack

Grade a stack A–F (and 0–100) by how well it covers your goals, with a per-goal coverage breakdown and the gaps. Supplements default to your local stack; goals come from --goals, else your account goals when signed in, else they are inferred from the stack.

-g, --goals <list>: Comma-separated goal ids (else account goals, else inferred)
--cloud: Rate your synced cloud stack instead of the local one (requires login)

supstack rate --goals deep-sleep,sharpen-focus

supstack rate magnesium l-theanine

supstack exportsupstack_export

Export your local stack as a Markdown or JSON document, with each supplement’s details fetched from the API.

-f, --format <format>: Output format: md | json (default md)

supstack export --format md

supstack export --format json

supstack goals [query]supstack_goals

List health goal ids (names, grouped by category) — the ids that `rate` and `recommend` expect. Filter by a free-text query or --category.

-c, --category <id>: Filter by category id (e.g. sleep, mental)

supstack goals --category sleep

supstack goals strength

supstack define <term>supstack_define

Look up a scientific or supplement glossary term and its aliases.

supstack define bioavailability

supstack define adaptogen

Account commands

Require supstack login — they act on your signed-in account. Reads stay fully anonymous; an account unlocks personalization.

supstack login

supstack logout

Sign out and revoke this device's token.

supstack whoami

Show the signed-in account.

supstack stack pull | push | sync

Sync your local stack with your account: pull (cloud→local), push (local→cloud), sync (additive merge, preserves dosage/timing/brand).

supstack profile [set | clear]

View or update your health profile (age, sex, weight, conditions, medications, goals, lifestyle).

supstack recommend

Personalized supplement recommendations from your saved goals + cloud stack.

supstack experiments list | show <id>

View your N-of-1 experiments and their verdicts and check-ins.

supstack experiments protocol | start | check-in | abandon

Run the N-of-1 loop: preview a protocol, start an experiment (baseline answers via --answer id=value), submit check-ins and get the verdict, or abandon an in-progress one.

supstack track log [supplement] | adherence

Log doses (whole stack if omitted) and view your adherence rate, streak, and per-supplement breakdown.

MCP server

supstack mcp runs a Model Context Protocol server over stdio, exposing every capability above as a tool. The CLI and the MCP tools are generated from one registry, so they never drift.

Claude Code

claude mcp add supstack -- npx -y @supstack/cli mcp

Claude Desktop — `claude_desktop_config.json`

{
  "mcpServers": {
    "supstack": {
      "command": "npx",
      "args": ["-y", "@supstack/cli", "mcp"]
    }
  }
}

Tools (21)

supstack_research	Full evidence summary for one supplement — description, evidence score, dosage, and safety profile (warnings + drug interactions).
supstack_search	Search supplements by name (fuzzy), or filter the library by goal, category, type, minimum evidence, or safety rating.
supstack_compare	Compare 2–3 supplements head-to-head by evidence score, safety rating, and total studies, with per-category winners.
supstack_studies	Search the peer-reviewed research library by free-text query, study type, and supplement.
supstack_interactions	Check interactions across supplements. With --medication, checks each supplement against a drug (clinical severity). With --pathway on a pair, runs the biochemical engine (shared enzyme/receptor targets, mechanisms, synergy/conflict score).
supstack_stack	Manage a local supplement stack stored in ~/.supstack/ (with optional per-supplement dose/timing/brand). Logged-in users can also sync it with their account (stack pull \| push \| sync — see Account commands).
supstack_rate_stack	Grade a stack A–F (and 0–100) by how well it covers your goals, with a per-goal coverage breakdown and the gaps. Supplements default to your local stack; goals come from --goals, else your account goals when signed in, else they are inferred from the stack.
supstack_export	Export your local stack as a Markdown or JSON document, with each supplement’s details fetched from the API.
supstack_goals	List health goal ids (names, grouped by category) — the ids that `rate` and `recommend` expect. Filter by a free-text query or --category.
supstack_define	Look up a scientific or supplement glossary term and its aliases.
supstack_recommend	Personalized recommendations from the user’s saved goals + cloud stack. Requires login.
supstack_profile_get	Read the user’s health profile. Requires login.
supstack_profile_set	Update the user’s health profile (mutating). Requires login.
supstack_experiments_list	List the user’s N-of-1 experiments. Requires login.
supstack_experiments_get	Get one experiment in full (protocol, verdict, check-ins). Requires login.
supstack_experiment_protocol	Preview an N-of-1 protocol’s baseline + check-in questions. Requires login.
supstack_experiment_start	Start an N-of-1 experiment with baseline answers (mutating). Requires login.
supstack_experiment_check_in	Submit an experiment check-in; computes the verdict on the final one (mutating). Requires login.
supstack_experiment_abandon	Stop an in-progress experiment — sets it to abandoned (mutating). Requires login.
supstack_track_log	Log a supplement dose (mutating). Requires login.
supstack_track_adherence	Adherence rate, streak, and per-supplement breakdown. Requires login.

Configuration

Env var	Default	Purpose
SUPSTACK_API_URL	https://supstack.me/api/v1	API base URL (override for local dev)
SUPSTACK_API_KEY	—	Optional API key (anonymous works at 60/min/IP)
SUPSTACK_CACHE_TTL	3600	Response cache TTL in seconds
SUPSTACK_NO_CACHE	—	Set to disable the local response cache
SUPSTACK_TIMEOUT	20	Per-request timeout in seconds (or use --timeout)
SUPSTACK_HOME	~/.supstack	Directory for config, stack, and cache
SUPSTACK_TOKEN	—	Override the stored account token (from supstack login)
SUPSTACK_NO_ANON_TOKEN	—	Disable auto-minting of the anonymous instant-token
SUPSTACK_NO_UPDATE_CHECK	—	Disable the "update available" notice (also honours NO_UPDATE_NOTIFIER)
SUPSTACK_COMPLETE_TIMEOUT	2500	Per-request budget (ms) for a TAB-time completion fetch
NO_COLOR	—	Disable ANSI colour

Shell completion

Dynamic completion for bash, zsh, and fish — completes commands, sub-actions, supplement slugs, and goal ids. Generate the script for your shell, then warm the value cache once.

supstack completion bash >> ~/.bashrc

supstack completion refresh

Exit codes

Commands exit with a semantic code so scripts and MCP wrappers can branch on the kind of failure.

Code	Meaning
0	Success
1	Generic error (including 5xx)
2	Auth required or rejected (not logged in, 401, 403)
3	Not found (404)
4	Rate limited (429)
5	Network failure / timeout
6	Invalid input (bad/missing args or flags, unknown command, 400/422)

SupStack provides evidence-based information for general wellness and education. It is not medical advice and is not intended to diagnose, treat, cure, or prevent any disease. Consult a qualified healthcare provider before changing your supplement regimen.