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 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 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 agent --model gpt-5.4 --reasoning-effort medium

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

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

# Start in planning mode
openmed agent --agent plan

# 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.4
--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, plan, or default
--mcp-enabled	Enable all configured MCP servers before launch

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

Authentication

Recommended auth commands:

# Project-local auth (default)
openmed login

# Global auth
openmed login --global

# Status
openmed codex status
openmed oauth status

# Logout
openmed codex logout
openmed codex logout --all

Current storage behavior:

• openmed login writes ./auth.json
• openmed login --global writes ~/.openmed/auth.json
• Auth detection prefers ./auth.json, then ~/.openmed/auth.json, then legacy fallbacks, then OPENAI_API_KEY

If you want the OpenAI SDK path instead of Codex OAuth, export an API key directly:

export OPENAI_API_KEY=sk-...

Model selection

The TUI model switcher currently exposes:

Model	Notes
gpt-5.4	Default
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
gpt-5.2-codex	Codex-oriented GPT-5.2
gpt-5.2	Base GPT-5.2
gpt-5.1-codex-max	Larger-context Codex variant
gpt-5.1-codex	GPT-5.1 Codex
gpt-5-codex-mini	Small Codex model

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.

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 OPENMED_INFERENCE_URL
• Those requests can also use OPENMED_INFERENCE_API_KEY, OPENMED_INFERENCE_HF_TOKEN, or HF_TOKEN
• PubMed, ICD-10, CPT, SNOMED, LOINC, RxNorm, MedlinePlus, HCC, RAF, and terminology/crosswalk tools use OPENMED_MED_CODES_API_URL
• Repo defaults point at hosted endpoints, but you can override them to internal, sandbox, or on-prem deployments

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

Deterministic workflows

The repo currently ships 13 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.