tcm-cli

tcm-cli screenshot

An autonomous agent for Traditional Chinese Medicine research and discovery.

Ask questions in natural language. tcm-cli plans the analysis, selects the right tools, executes them, validates results, and returns data-backed conclusions.

Why tcm?

Requirements

Installation

Quick install (script)

curl -fsSL https://raw.githubusercontent.com/tigerneil/tcm-cli/main/install.sh | bash

The script detects pipx, uv, or falls back to pip --user, then runs tcm setup.

pipx install tcm-cli

With pip

# Core install
pip install tcm-cli

# With chemistry support (RDKit)
pip install "tcm-cli[chemistry]"

# With ML support (PyTorch + Transformers)
pip install "tcm-cli[ml]"

# With analysis stack (scikit-learn, seaborn, scipy)
pip install "tcm-cli[analysis]"

# Everything
pip install "tcm-cli[all]"

Authentication

# Interactive setup wizard (Anthropic default)
 tcm setup

# Manage multiple providers (recommended)
 tcm keys                 # show status for all providers
 tcm keys set -p openai   # set OpenAI key (prompts securely)
 tcm keys set -p kimi     # set Moonshot Kimi key
 tcm keys set -p deepseek # set DeepSeek key
 tcm keys set -p google   # set Google (Gemini) key

# Or export directly (CI)
 export OPENAI_API_KEY="sk-..."
 export ANTHROPIC_API_KEY="..."
 export GOOGLE_API_KEY="..."

# Non-interactive (CI/scripting)
 tcm setup --api-key YOUR_ANTHROPIC_KEY

API keys are stored at ~/.tcm/config.json. See provider mapping and base URLs in docs/PROVIDERS.md.

Getting Started

Basic usage

# Start interactive session
tcm

# Single query
tcm "What herbs are used for Spleen Qi deficiency?"

# Use a specific model
 tcm --model gpt-4o "Analyze 四君子汤"
 tcm --model gemini-3.1-pro "Check interactions between 人参 and 藜芦"

# Set language per run (English | Chinese | Bilingual)
tcm --lang en "Check interactions between 人参 and 藜芦"
tcm --lang zh "分析 四君子汤 的组成与配伍"
tcm --lang bi "Network pharmacology for 补中益气汤"

# Validate setup
tcm doctor

Interactive commands

Inside tcm interactive mode:

Quick examples

Herb lookup

$ tcm "Tell me about 黄芪 (Astragalus) — properties, compounds, and clinical evidence"

Formula analysis

$ tcm "Analyze the composition of 四君子汤 using the 君臣佐使 framework"

Syndrome differentiation

$ tcm "Patient has fatigue, loose stools, poor appetite, pale tongue. What TCM syndrome?"

Network pharmacology

$ tcm "Build a network pharmacology analysis for 补中益气汤 against diabetes targets"

Safety check

$ tcm "Check interactions between 人参, 藜芦, and Warfarin"

Language modes

You can control the language of answers globally or per-run.

Behavior by mode:

Documentation

Key Features

30+ Domain Tools

Category Examples
Herbs Lookup, property classification, meridian search, compound listing
Formulas Classical formula search, 君臣佐使 analysis, modifications
Syndromes Pattern differentiation, symptom-to-syndrome mapping, treatment plans
Compounds Active compound search, ADMET prediction, target identification
Pharmacology Network pharmacology, pathway enrichment, herb-target networks
Interactions 十八反/十九畏 checks, herb-drug interactions, formula safety
Literature PubMed search, systematic review finder, CNKI integration
Meridians Channel lookup, Five Element associations, meridian-herb mapping
Safety Toxicity profiling, pregnancy safety, dosage validation
Modern Clinical trial search, ICD-10 mapping, evidence summaries
Data APIs TCMSP, UniProt, STRING, KEGG, ClinicalTrials.gov, Open Targets
Code Python sandbox for custom analysis (experimental)

List all tools and their status:

tcm tool list

Supported providers and models

Out of the box, tcm-cli can talk to these providers (pick any one):

Tip: Use the interactive picker /model in the REPL, or CLI commands below.

tcm model list                    # Show all models grouped by provider with context/pricing
tcm model set gpt-4o              # Switch to a model (provider auto-detected)
tcm model set kimi-k2.5           # Switch to Moonshot Kimi
tcm model set gemini-2.5-flash    # Switch to Gemini 2.5 Flash
tcm model set gemini-2.5-pro      # Switch to Gemini 2.5 Pro (most capable)
tcm model set gemini-3.1-pro-preview  # Switch to Gemini 3.1 Pro Preview (frontier)
tcm model google                  # List ALL available Gemini models live from the API
tcm model show                    # Show current model

See provider keys and base URLs: docs/PROVIDERS.md.

Local Datasets

Without local data, tcm works via database APIs and built-in knowledge. To boost accuracy and offline support, install local datasets:

tcm data pull herbs      # Install bundled herb monograph data (instant)
tcm data pull formulas   # Install bundled classical formula data (instant)
tcm data pull tcmsp      # TCMSP — herbs, compounds, targets (~50 MB)
tcm data pull tcmid      # TCMID — herb-compound-disease (~30 MB)
tcm data pull batman     # BATMAN-TCM bioinformatics data (~100 MB)
tcm data pull symmap     # SymMap symptom-mapping database (~20 MB)
tcm data status          # Show all dataset statuses

Install modes:

tcm data import tcmsp ~/Downloads/tcmsp.zip
tcm data import tcmsp ~/Downloads/tcmsp-extracted/   # or a directory

Use --force to re-download or reinstall any dataset:

tcm data pull herbs --force

Configuration

tcm config show             # Show all settings
tcm config set key value    # Set a value
tcm config get key          # Get a single value
tcm config validate         # Check for issues

Config is stored at ~/.tcm/config.json.

Common config keys

tcm config set llm.provider openai           # switch to OpenAI
tcm config set llm.model gpt-4o             # set model (provider auto-detected)
tcm config set llm.provider google          # switch to Google (Gemini)
tcm config set llm.model gemini-2.5-flash   # set Gemini 2.5 Flash as default
tcm config set ui.language bi               # en (default) | zh | bi

Agent profiles

tcm config set agent.profile research    # Default — balanced, allows hypotheses
tcm config set agent.profile clinical    # Strict evidence only, no hypotheses
tcm config set agent.profile education   # Relaxed, creative responses

Troubleshooting

Symptom Fix
tcm fails at startup tcm doctor
Authentication error tcm setup or tcm keys
Missing API key export OPENAI_API_KEY=... or tcm config set llm.openai_api_key ...
Google model 404 Run tcm model google to see valid model IDs, then tcm model set <id>
Google SSL/connect error Transient network issue, retry or switch to another model
Missing dependency pip install "tcm-cli[all]"
Tool module failed tcm tool list — check for load errors

Contributing

git clone https://github.com/tigerneil/tcm-cli.git
cd tcm-cli
pip install -e ".[dev]"
tcm setup
pytest tests/

License

MIT

This site is open source. Improve this page.