CLI reference

The oompf CLI drives the full workflow. Install it on your PATH with npm install -g @grosspoetrysystems/oompf, or run it per invocation with bunx @grosspoetrysystems/oompf@latest. The package name is scoped; the command is plain oompf. See Getting started for prerequisites and why a project-local install is the wrong shape for a PATH command.

It targets https://oompf.run by default; set OOMPF_BASE_URL (for example http://localhost:4321) to point at a local instance. Every command prints a stable error envelope on failure — a machine-readable code, a human message, and optional value-free details.

The CLI uses the canonical /api/v1 routes for indexed metadata and registration. upgrade also patches the owned source Gist through GitHub after confirmation. Response shapes are described by /openapi.json and the published JSON Schemas.

OOMPF is an index over OMP profiles; the profile format itself belongs to OMP (Oh My Pi). Field semantics and the runtime come from upstream OMP’s profile documentation, and this CLI is one client of that format.

oompf publish

Publish a native OMP profile to a public Gist and register its metadata.

oompf publish work

• Syntax: oompf publish [profile], where profile is a native OMP profile name.
• Agent runtime: --agent <omp|pi> selects the runtime binary (default omp). When omitted, the sole installed runtime is used automatically; OMP wins when both are installed.
• Output: the canonical profile URL, https://oompf.run/p/<id>, and publication: created | updated.
• Repeat publish: publishing the same profile again patches the Gist it was first published to, so /p/<id> stays stable while the revision and fingerprint change. The mapping lives in ~/.oompf/publications.json; --new publishes a separate Gist instead. A patched Gist can take a while to become readable, so the command confirms that the index holds the bytes it just wrote. If confirmation fails, the Gist may already be current while the OOMPF link still installs the previous pinned revision. Wait at least a minute, then retry the original publish command.
• Omitted input: When the name is omitted, OOMPF automatically uses the sole publishable profile. With multiple profiles it opens a selector only in an interactive terminal; --json, CI, and piped execution return ambiguous_profile instead of prompting.
• Local failure modes: invalid_profile, profile_not_found, missing_config, no_profile, ambiguous_profile, and selection_cancelled, plus structural validation and blocking-secret errors.
• Remote failure modes: GitHub authentication/creation failure, or registration failure; rate_limited when registration or confirmation is throttled; index_update_failed when a patched source cannot be confirmed; missing_gist or unowned_gist when the remembered Gist is gone or belongs to another account. Nothing is registered if local validation fails.

oompf inspect

Show a profile’s facts, OOMPF metadata, aliases, structural verdict, and provenance without installing anything.

oompf inspect https://oompf.run/p/<id>
oompf inspect prof_1b7c9e0a4d2f3a5b6c8d9e0f1a2b3c4d

• Syntax: oompf inspect <oompf-url-or-id>
• Output: the profile metadata record — models (friendly name + exact selector), providers, OMP aliases, behavior, actionable requirements, and provenance. JSON output includes the oompf metadata and aliases.
• Failure modes: not_found for an unknown id; a network error when the index is unreachable.

oompf search

Free-text search over the index.

oompf search "kimi low-cost"

• Syntax: oompf search <query>
• Output: compact summaries — name, models, providers, the author’s summary/kind/tags, publisher-declared ompVersion, structural verdict, and a canonical OOMPF URL. In JSON, kind is { controlled, value } or null; summary and ompVersion may be null, and absent tags are [].
• Failure modes: a network error when the index is unreachable. An empty query returns no results.

oompf add

Install a shared profile by its canonical OOMPF URL.

oompf add https://oompf.run/p/<id>

• Syntax: oompf add <oompf-url-or-id>
• Agent runtime: --agent <omp|pi> selects the runtime binary (default omp). When omitted, the sole installed runtime is used automatically; OMP wins when both are installed.
• Safe install: OOMPF resolves the id, fetches the canonical Gist, re-validates it structurally and for secrets, verifies the SHA-256 fingerprint, and only then installs a native OMP profile. It installs nothing on failure.
• Output: confirmation of the installed profile name.
• Failure modes: not_found, unreachable source, validation failure, or a fingerprint mismatch.

oompf upgrade

Review and optionally apply explicit model successors to an indexed profile. Preview is read-only; the command changes a source only after confirmation.

oompf upgrade https://oompf.run/p/<id>
oompf upgrade prof_1b7c9e0a4d2f3a5b6c8d9e0f1a2b3c4d --yes

• Syntax: oompf upgrade <oompf-url-or-id>.
• Preview: the default behavior fetches the source Gist’s current head, reports the catalog revision, and shows each explicit model successor plus unchanged selectors and reasons. Preview performs no writes; --json is suitable for automation.
• Confirmation: use --yes for a non-interactive confirmed update. The command verifies GitHub ownership, validates the transformed YAML, patches the existing public Gist in place, and re-registers the same source URL. The /p/<id> identity therefore stays stable while its revision and fingerprint change.
• Index-only recovery: if the current Gist has no model changes to apply but its hash differs from the index, --yes (or accepting the interactive refresh prompt) re-registers and confirms the current bytes without another Gist patch. Preview remains read-only, and an already-current index needs no registration. An index-only recovery leaves updatedRevision null because it does not create a source revision.
• Safety: the indexed pinned revision is provenance only; the current Gist head is the patch input. A head change during review aborts instead of overwriting the newer edit. Unknown models, missing successors, and incompatible slots remain unchanged.
• Failure modes: invalid_ref, unverifiable_artifact, unowned_gist, head_changed, invalid_artifact, blocking_secrets, GitHub patch failure, rate_limited, or index_update_failed. After a successful Gist patch, registration or confirmation can still fail: the canonical Gist is current, but installs through the indexed OOMPF URL may receive the previous revision. Wait at least a minute, then retry the original upgrade command. If no further model changes are needed, the retry repairs the index without patching the Gist again.

Registration and confirmation limits

Publish and confirmed upgrade use at most five registration requests per operation, including the initial registration and confirmation retries. The endpoint allows five requests per 60 seconds per client IP; earlier operations or other clients sharing that IP can still consume the budget.

rate_limited means registration or confirmation was throttled. index_update_failed means registration otherwise failed or confirmation exhausted without finding the expected hash. Neither means that an already successful Gist patch was rolled back. A successful retry confirms the indexed hash rather than treating an HTTP success response as proof of freshness.

Corresponding API routes

The complete omp command surface and runtime behavior are documented by OMP upstream; OOMPF documents only the commands above.