Measured: --offline allows loopback and blocks before network I/O — the consequence (what you CAN point at) is undocumented #882

Report-only, per CONTRIBUTING's issue trust policy — I am not asking for execution authority, just filing a measurement and a docs suggestion.

What I measured

oh-my-cli built from main on Windows, against a local listener that logs the path it is asked for. Four runs:

The C message deserves quoting, because it is unusually good:

Offline mode is active; the provider route to api.openai.com was blocked before any network I/O. Point OPENAI_BASE_URL at a loopback endpoint (a local OpenAI-compatible server), or disable offline mode (remove --offline / unset OMC_OFFLINE).

It names the host, states the stage (before I/O, not a failed request), and gives both exits. That is better than most refusals I read.

Honest limit: my listener returns a minimal chat-completion body, which your parser rejected with empty_response after bounded retries. That is my stub being lazy, not a defect on your side — the routing question I was testing was answered by the request arriving at all.

The suggestion

--offline restricting to loopback is a deliberate and useful posture, and it has a consequence that is not written down anywhere I could find: in offline mode the only thing you can point at is something running on the box — a local model server, or a proxy replaying previously recorded responses. The second case makes a past session re-runnable with no provider and no key, which turns an offline run into a repeatable test rather than just a blocked one.

A short docs/OFFLINE.md (or a section in FIRST-RUN.md) covering:

• what --offline / OMC_OFFLINE refuses and at which stage
• that loopback is the allowed class, with the error text as the worked example
• the two things people put on loopback — a local model server, or a record/replay proxy

would save readers from discovering the rule by tripping it. Issue #576 implemented the behaviour; the docs never caught up.

Happy to draft that page as a report-only PR if the governance model allows it — I noticed all twelve recently merged PRs are Bot-authored, so I did not open one speculatively.

Disclosure

I work on OrcaReplay, which is a record/replay proxy and therefore one of the things that would sit on that loopback address. I am not asking for a link or a mention anywhere in this repo — the docs gap stands whether the loopback endpoint is llama.cpp, LM Studio, vLLM or a recorder, and I would rather the page named the category than any product.