DOCS — PRODUCT · CLI REFERENCE

CLI Reference

openmed is both the default TUI launcher and the command-line surface for authentication, configuration, asynchronous inference batches, 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 batch ...	Validate, submit, resume, retrieve, or cancel asynchronous inference batches
openmed responses ...	Submit and resume Doubleword async flex or on-demand priority Responses
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-6.1-sol
openmed agent --model gpt-6.1-sol --reasoning-effort medium
openmed agent --model gpt-6.1-sol --reasoning-effort high

# Xiaomi MiMo token plan (key configured separately)
openmed agent --provider mimo
openmed agent --provider mimo --model mimo-v2.6-flash --reasoning-effort none

# Doubleword real-time agent (DeepSeek V4.1 Flash by default)
openmed agent --provider doubleword

# 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-6.1-sol; MiMo defaults to mimo-v2.5-pro; Doubleword uses the first configured model, otherwise deepseek-ai/DeepSeek-V4.1-Flash
--models	Print available TUI models and exit
--reasoning-effort	Model-aware reasoning effort; default: medium; GPT-6.1 Sol and GPT-6 Astra support low through max; GPT-6 Sol/Luna also support none; MiMo uses none for thinking off and other values for thinking on
--skill	Preload a skill by ID
--phi-mode	Session PHI label: full, deid, or strict
--agent	Agent mode: clinical, consumer, coordination, or default
--provider	Force a provider: openai, anthropic, openrouter, mimo, doubleword, or custom. Omit to select from the model and configured auth
--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.

Individual async and on-demand requests

openmed responses submit request.json --service-tier flex
openmed responses submit request.json --service-tier priority --wait --timeout 120
openmed responses list
openmed responses status <response-id>
openmed responses wait <response-id> --poll-interval 5 --timeout 300
openmed responses results <response-id>
openmed responses adopt <remote-response-id>

These commands use the Doubleword Responses API, separate from JSONL batches. request.json must contain model, input, and max_output_tokens; see Doubleword for a complete example. The key comes from DOUBLEWORD_API_KEY or provider secrets; the execution tier comes from --service-tier (default flex). --wait only waits locally. Neither flag is a persistent provider-secret setting or a TUI mode switch. Results include tool calls but do not execute them. For streaming agent tool loops use openmed agent --provider doubleword. Its reasoning behavior uses model defaults; the TUI effort setting does not override Doubleword reasoning.

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

Provider credentials — API keys, ~/.openmed/provider_secrets.json, and the OpenRouter/Doubleword model lists — are documented on the Providers page. The commands are:

openmed config provider-set openai     --api-key "sk-..."
openmed config provider-set anthropic  --api-key "sk-ant-..."
openmed config provider-set openrouter --api-key "sk-or-..." \
  --models "google/gemini-3.7-flash,qwen/qwen3.8-27b,z-ai/glm-5.2"
openmed config provider-set mimo      --api-key "tp-..."
openmed config provider-set doubleword --api-key "sk-..."
openmed config provider-show
openmed config openrouter-models --search gemini   # browse the OpenRouter catalog

Each also accepts --unset-api-key; provider-set openrouter and provider-set doubleword additionally accept --models and --unset-models. Environment variables OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, MIMO_API_KEY, and DOUBLEWORD_API_KEY are equivalent and take precedence over the file.

Doubleword offers 11 built-in generation models. A configured list replaces them in /model and --models, and its first entry becomes the interactive default. DOUBLEWORD_MODELS overrides the stored list. See the model IDs and provider-secret example.

MiMo needs only the key: its endpoint and all four native models are built in. provider-set mimo does not accept --base-url or --models. See complete MiMo provider secrets examples.

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

Asynchronous batch inference

The first batch adapter is Doubleword. Validation is offline; submission returns immediately with a durable local ID.

openmed batch validate requests.jsonl
openmed batch submit requests.jsonl
openmed batch status <job-id>
openmed batch results <job-id>  # downloads new partial output/error rows
openmed batch wait <job-id>
openmed batch cancel <job-id>
openmed batch list

Use --json for automation. submit --wait combines creation and polling; wait --timeout <seconds> stops the local waiter without cancelling the remote job. The complete JSONL contract, storage layout, provider-secret example, and privacy boundary are in Batch Inference.

Model selection

The TUI model switcher currently exposes:

Model	Notes
claude-fable-5-1	Claude Fable 5.1; demanding reasoning and long-running work
claude-opus-5-5	Claude Opus 5.5
claude-opus-5	Claude Opus 5
claude-sonnet-5	Claude Sonnet 5
claude-opus-4-8	Claude Opus 4.8
claude-sonnet-4-6	Anthropic provider default
claude-haiku-4-5-20251001	Claude Haiku 4.5
gpt-6.1-sol	Default; coding and agentic workflows; medium reasoning
gpt-6-astra	Next-generation flagship GPT-6 model
gpt-6-sol	GPT-6 model for complex coding and agentic workflows
gpt-6-luna	Fast, cost-efficient GPT-6 model
mimo-v2.5-pro	MiMo token-plan default; text input
mimo-v2.5	MiMo token plan; text and image input
mimo-v2.6-pro	MiMo token plan; text input
mimo-v2.6-flash	MiMo token plan; text input

With a MiMo key configured, the MiMo group offers all four models automatically. Bare MiMo model IDs select the token-plan route; a namespaced xiaomi/... ID selects OpenRouter.

With an OpenRouter key configured, the switcher adds an OpenRouter group listing your configured models (--models, OPENROUTER_MODELS, or the qwen/qwen3.8-27b default) with capability chips such as vision · 1M ctx · reasoning. Models that cannot call tools are marked incompatible and refused at startup.

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-6.1 Sol and GPT-6 Astra offer low, medium, high, xhigh, and max. GPT-6 Sol and Luna also offer none, which skips the reasoning-summary step. On GPT-6.1 Sol and GPT-6 Astra, --reasoning-effort none maps to low. The app defaults to GPT-6.1 Sol with medium reasoning and 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
• Models create drafts only. The TUI classifies each request as draft or finalized delivery with the small auxiliary-model path: explicit finalized requests are committed from the exact immutable snapshot in the same run; explicit draft requests and requests with no delivery wording stop at the draft. Natural follow-ups can approve an active draft without a run ID. The host still supplies a one-use exact-payload grant, and snapshots expire after 24 hours by default
• Final output directories must be new, empty, or an existing OpenMed-owned bundle for the same workflow; unsafe or arbitrary nonempty destinations are rejected before finalization
• clinical_inbox_triage and discharge_handoff also require real review_metadata at final write; the UI collects it when needed
• 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.