DOCS — PRODUCT · HEADLESS WORKFLOWS

Run an agent workflow from the CLI¶

openmed agent --once runs one request through the same provider SDK and tool bridge used by the TUI, then exits. It can extract entities, validate codes, call HCC services, and create draft reports. Use it for scripts, CI checks, and scheduled retrospective work that needs tools as well as a model answer.

Start with one request¶

Configure a provider first. For example, use DOUBLEWORD_API_KEY or the existing Doubleword entry in ~/.openmed/provider_secrets.json. There is no separate headless credential.

openmed agent --provider doubleword \
  --model deepseek-ai/DeepSeek-V4.1-Flash \
  --once 'List the available deterministic workflows and explain which produces a coding audit draft.'

Omit --provider to resolve the model against configured authentication. With no explicit model, a default saved with openmed config model-set is used; otherwise an authenticated OpenAI/Codex default is preferred, then an available provider's recommended model. Explicit model/provider choices are not silently replaced. Configure a provider API key (or sign in with openmed login) beforehand; headless runs never open a sign-in dialog.

For longer prompts, redirect a file into stdin. This also avoids putting the prompt itself in a process argument:

openmed agent --provider doubleword --once - --json --timeout 600 \
  < prompt.txt > result.json 2> progress.log
status=$?

Normal stdout contains the final answer. --json instead emits one JSON object with schema_version, status, exit_code, provider, model, content, tool_calls, artifact_paths, approvals, errors, and provider-reported usage. Tool receipts include results and may contain source text or clinical data: keep them private. Progress and diagnostics go to stderr. Intermediate reasoning and pre-tool narration are not mixed into the final answer.

The command does not create or resume a TUI conversation. --session is rejected. An interrupted run cannot be resumed by ID; starting the command again performs new work and may repeat charges or side effects. Keep each run's outputs separate.

Permissions and privacy¶

Project/user runtime settings and OPENMED.md apply, as do agent profile tool restrictions and --skill. Enabled remote MCP tools use the normal registry. The CLI does not bypass protected paths or host file-privacy restrictions.

Default approval behavior uses the configured tool policy. Ordinary permitted tools run; an operation requiring an interactive approval is denied.
--auto-approve (or OPENMED_AUTO_APPROVE=1) explicitly grants ordinary tool prompts and records each grant. Deny rules still apply. It never grants workflow finalization or clinical-review consent.
--permission-mode plan permits only tools marked both read-only and safe for concurrent use. denyall blocks tools; auto uses the normal permission rules. An explicit CLI mode overrides the stored mode, while allow/deny lists remain.
File writes already allowed by the policy can happen without a prompt. For a restricted script, configure an explicit tool allowlist and deny rules in runtime settings.
--file-privacy on restricts access to the dedicated privacy tools and metadata inspection. auto activates that restriction for recognized file-privacy requests; the default is off. This does not scrub text supplied in a prompt.
Headless runs support --phi-mode full only. deid and strict are rejected before any request is sent; use the TUI for those modes. Use synthetic or appropriately de-identified inputs.

A draft is not a clinical approval. Workflow finalization and clinical-review consent require the interactive host, even if the model supplies a token or review_mode=true.

Exit codes¶

Code	Meaning
`0`	Agent returned a final answer with no recorded tool failure or denied approval
`1`	Provider/runtime failure or termination without a final answer
`2`	Invalid configuration/input or unsupported option combination
`3`	Required interactive approval or clinical review was unavailable
`4`	At least one tool failed or was blocked by policy, even if the model later produced an answer
`124`	Timeout
`130`	Interrupted with Ctrl+C / SIGINT

Inspect receipts on any nonzero exit. A later successful retry does not erase an earlier tool failure. Exit zero means successful execution, not clinical correctness; validate the artifacts for your use case.

--timeout defaults to 600 seconds and cancels the run. The command exits with code 124 without waiting for a tool that is still running, so a call already in flight can be cut off or finish on the remote side. Completed file writes and remote effects are not rolled back. Provider clients are closed on exit.

When to use batch instead¶

--once is a real-time agent/tool loop. Doubleword responses and batch commands submit inference requests and do not execute returned tool calls. For a large backlog that can wait up to 24 hours, prepare deterministic NLP/coding evidence first, then use batch inference for independent model reviews. Dependent tool/model stages need orchestration; changing provider secrets does not turn --once into a background batch job.