Skip to content

CLI Reference

openmed is both the default TUI launcher and the command-line surface for authentication, configuration, MCP management, profiles, and updates.

Top-level commands

Command What it does
openmed Launch the interactive TUI with the current defaults
openmed agent Launch the TUI with explicit model, reasoning, skill, or PHI settings
openmed --models List the TUI model catalog
openmed login Start the Codex OAuth browser flow
openmed codex ... Codex-specific auth commands
openmed oauth ... Auth status/logout aliases
openmed config ... Inspect or persist config values
openmed mcp ... Add, enable, disable, or diagnose remote MCP servers
openmed audit ... Configure and inspect opt-in private audit traces
openmed update Check for or install updates
openmed env Print environment/debug information

Launch the agent

# Default launch
openmed

# Pick a model and reasoning effort
openmed --model gpt-5.5
openmed agent --model gpt-5.5 --reasoning-effort low

# List available models
openmed --models

# Start in consumer mode
openmed agent --agent consumer --skill analyzing-health-data

# Start in care-coordination mode
openmed agent --agent coordination --skill care-coordination

# Preload a built-in or user skill
openmed agent --skill reviewing-prior-auth

# Start with all configured MCP servers enabled
openmed --mcp-enabled

Agent flags

Flag Current behavior
--model Model name passed into the active SDK. Default: gpt-5.5
--models Print available TUI models and exit
--reasoning-effort low, medium, high, or extra_high
--skill Preload a skill by ID
--phi-mode Session PHI label: full, deid, or strict
--agent Agent mode: clinical, consumer, coordination, or default
--mcp-enabled Enable all configured MCP servers before launch

default currently resolves to the clinical agent profile. The CLI, TUI, and runtime expose three built-in modes: clinical, consumer, and coordination.

Authentication

Recommended auth commands:

# OAuth auth
openmed login

# Status
openmed codex status
openmed oauth status

# Logout
openmed codex logout
openmed codex logout --all

Current storage behavior:

  • openmed login writes ~/.openmed/auth.json
  • openmed login --global is accepted for backward compatibility, but it is now a no-op flag
  • Auth detection uses ~/.openmed/auth.json
  • Project-local ./auth.json is deprecated and ignored

If you want the OpenAI SDK path instead of Codex OAuth, store an OpenAI provider key:

openmed config provider-set openai --api-key "sk-..."
openmed config provider-show

To use Anthropic models, store an Anthropic provider key and choose a Claude model:

openmed config provider-set anthropic --api-key "sk-ant-..."
openmed agent --provider anthropic --model claude-sonnet-4-6

Environment variables are also supported: OPENAI_API_KEY and ANTHROPIC_API_KEY.

~/.openmed/provider_secrets.json can also reference environment variables:

{
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Provider base URLs are intentionally not user-configurable during preview. OpenMed controls those endpoints internally.

If you need a preview build, request preview access.

Provider config is loaded once per process. If you edit the file manually, restart OpenMed.

Model selection

The TUI model switcher currently exposes:

Model Notes
claude-opus-4-7 Claude Opus 4.7
claude-sonnet-4-6 Anthropic provider default
claude-haiku-4-5-20251001 Claude Haiku 4.5
gpt-5.5 Default GPT-5.5 model
gpt-5.4 GPT-5.4 model
gpt-5.4-mini Smaller GPT-5.4 variant
gpt-5.3-codex Codex-oriented GPT-5.3
gpt-5.3-codex-spark Faster Spark variant

At runtime you can switch models with Ctrl+M or /model.

The picker flow is:

  1. Model
  2. Reasoning effort
  3. Reasoning summary on supported models

gpt-5.3-codex-spark skips the reasoning-summary step. gpt-5.5 applies low reasoning with thinking display off.

Native medical services

Many OpenMed capabilities are native tools from the agent's perspective, even when they call configured HTTP services behind the scenes.

  • extract_entities, extract_pii, deidentify_text, and the batch extraction helpers use the native extraction service plane
  • PubMed, ICD-10, CPT, SNOMED, LOINC, RxNorm, MedlinePlus, HCC, RAF, and terminology/crosswalk tools use the native coding and terminology service plane
  • Preview builds use OpenMed-hosted native services without extra local setup

These are native OpenMed tools. They are not MCP tools.

Audit traces

Audit is off by default. When enabled, OpenMed writes one private trace per agent run to the configured destination.

# Private HF dataset, recommended for versioned history
export OPENMED_AUDIT_HF_TOKEN=hf_...
openmed audit enable --destination hf_dataset --dataset "<user-or-org>/openmed-traces"

# Local-only audit traces
openmed audit enable --destination local

# Inspect status and traces
openmed audit status
openmed audit show --last 10
openmed audit export <run_id> --out trace.json

Useful audit commands:

Command What it does
openmed audit enable Create or configure the audit destination and write ~/.openmed/audit.json
openmed audit disable Disable audit writes without deleting config
openmed audit pause / resume Temporarily pause or resume audit writes
openmed audit verify Smoke-test the configured destination
openmed audit show --last N List recent traces
openmed audit show <run_id> Print one trace JSON
openmed audit export <run_id> Write one trace to a local JSON file
openmed audit local-list List local fallback traces
openmed audit local-sync Push local fallback traces to the configured HF dataset

Default audit mode stores full private transcript and tool payloads. Use openmed audit set-phi-payload preview, fingerprint, or none for smaller records. See Audit Trail.

Deterministic workflows

The repo currently ships 15 deterministic workflows. You normally invoke them through natural language in the TUI or inspect them with /workflows.

Workflow ID Purpose Required inputs
appeal_review Review denied appeals against evidence requirements note_paths, denial_codes, procedure_cpt
chart_summary Build evidence-linked chart summary cards and artifacts note_path
claims_explainer Explain FHIR EOB data in plain language eob_path
clinical_inbox_triage Triage patient message threads into urgent, routine, or admin routing with reply drafts thread_path
clinical_documentation Convert visit transcripts into structured clinical notes note_path
coding_audit Audit submitted ICD-10 codes for specificity and compliance submitted_codes_path, note_paths
consumer_summary Summarize normalized consumer record imports with timeline, trends, questions, narrative, and reconciliation notes records_path or manifest_path
discharge_handoff Build patient instructions, clinician summary, PCP handoff, and follow-up tasks from a discharge pack discharge_path
health_summary Parse Apple Health data, analyze trends, and emit FHIR output health_export_path
icd10_hcc_coding Build a coding package with validation, mappings, and claims context note_paths, submitted_codes_path
med_rec_discrepancy Detect medication reconciliation discrepancies note_path
prior_auth_review Review prior auth requests against codes and LCD/NCD criteria note_paths, procedure_cpt, diagnosis_icd10
structured_extraction_fhir_diff Extract entities, build a FHIR bundle, and diff it note_paths

Common workflow behavior:

  • All 13 support draft preview
  • Finalization requires draft_only=false and a valid approval_token
  • clinical_inbox_triage and discharge_handoff also require review_metadata on finalize
  • consumer_summary, clinical_inbox_triage, and discharge_handoff are local review/generation flows; there is no outbound send or external-system writeback path in these Wave 1 / Wave 2 lanes
  • Finalized runs write provenance data
  • Case runs can be listed and diffed through the workflow tool surface

Default output roots:

  • Artifacts: /tmp/openmed/artifacts/
  • Case runs: /tmp/openmed/cases/

Override them with OPENMED_WORKFLOW_ARTIFACTS_DIR and OPENMED_WORKFLOW_CASES_DIR.

Configuration and profiles

openmed config show
openmed config set timeout 600
openmed config profiles
openmed config profile-show dev
openmed config profile-use prod
openmed config profile-save myprofile
openmed config profile-delete myprofile

See Configuration for environment variables and Profiles for the built-in presets.

MCP management

openmed mcp list
openmed mcp add guidelines_hub https://example.com/mcp --name "Guidelines Hub"
openmed mcp enable guidelines_hub
openmed mcp enable --all
openmed mcp disable guidelines_hub
openmed mcp disable --all
openmed mcp set-url guidelines_hub https://new-url.example.com/mcp
openmed mcp doctor guidelines_hub
openmed mcp doctor --all

MCP is the extension surface for remote systems that OpenMed does not already ship natively.

Updates and diagnostics

openmed update
openmed update --check
openmed env

openmed update can either check for updates or install them, depending on flags and installation mode. openmed env is the quickest way to capture local environment details for debugging.