oompf

oompf publishes, inspects, searches, installs, and upgrades OMP (Oh My Pi) agent profiles through the OOMPF index at oompf.run.

A local profile becomes a public GitHub Gist, its metadata is registered in the index, and anyone can reinstall it as a native OMP profile:

oompf publish <profile-name>  → public Gist → indexed → https://oompf.run/p/<id>
oompf add <oompf-url>         → installs a verified native OMP profile
omp --profile <name>          → run it

The canonical profile artifact always stays at its public Gist; OOMPF persists and serves metadata only.

Requirements

• Node >= 22 or Bun. The CLI uses Promise.withResolvers, which requires Node 22+ (or any Bun release).
• GitHub CLI (gh), authenticated — required for publish, which creates a public Gist with your gh account. Verify with gh auth status; run gh auth login first if needed.
• OMP CLI (omp) on PATH — required for publish (resolves the local profile's config path) and add (resolves the install directory). OOMPF asks OMP where a profile lives rather than hardcoding a home path. omp is itself a Bun program.

Install

oompf is a terminal command, so install it globally:

npm install -g @grosspoetrysystems/oompf

Or run it without installing:

bunx @grosspoetrysystems/oompf@latest --help
npx @grosspoetrysystems/oompf@latest --help

The package name is scoped; the command is plain oompf, which is what the examples below use.

A project-local npm install is the wrong shape here: the binary lands in node_modules/.bin, which is not on your PATH, and npm refuses the install entirely inside a repository that uses workspace: specifiers. Use -g or bunx.

Working in a clone of the repository? Run it from source with bun apps/cli/src/index.ts <command>.

Commands

Every command prints human-readable output by default and structured JSON with --json. On failure, every command exits non-zero and prints a stable error envelope: a machine-readable code, a human message, and optional value-free details.

All commands target https://oompf.run by default. Set OOMPF_BASE_URL to point elsewhere, for example at a local instance:

OOMPF_BASE_URL=http://localhost:4321 oompf search anthropic

oompf publish [profile]

Resolve a local OMP profile (pass the name, or omit it when exactly one profile is unambiguous), validate and secret-scan its config.yml, publish it as a public one-file Gist, and register its metadata with the index.

oompf publish work

Output: the githubUrl, the canonical oompfUrl (https://oompf.run/p/<id>), a copyable addCommand, the artifact hash, whether this publication was created or updated, the structural verdict, and any warnings.

Publishing the same profile again patches the Gist it was first published to rather than creating another, so a link already shared keeps working and shows the new bytes. The profile-to-Gist mapping is a plain JSON file at ~/.oompf/publications.json; delete it and the next publish starts a new identity. Pass --new to publish a separate Gist deliberately.

A patched Gist takes a few seconds to become readable, so a repeat publish waits for the index to store the bytes it just wrote before reporting success. When it stays behind, the command says so instead of claiming the shared link is current; the Gist is already patched, so publishing again resolves it.

Failure modes:

• no_profile — no OMP profiles were found; pass an explicit name.
• ambiguous_profile — more than one profile exists; pass the one to publish.
• missing_config — the profile has no config.yml / config.yaml.
• invalid_artifact — the profile failed structural validation.
• blocking_secrets — high-confidence secrets were detected in the config; nothing is published. Remove them and retry.
• missing_gist / unowned_gist — the remembered Gist was deleted, made private, or now belongs to another account; publish refuses rather than forking a second identity.
• GitHub authentication or Gist-creation failure (e.g. gh not installed or not authenticated), or registration failure against the index (network_error, or the server's own code such as validation_failed).
• index_update_failed — the Gist was patched but the index is still serving the previous bytes. Publish again; the Gist needs no further change.

Nothing is registered if local validation fails.

oompf add <ref> [--name <name>]

Install a shared profile as a native OMP profile. The reference must be an OOMPF URL or profile id. Direct Gist URLs and ids are rejected because they have no indexed revision or fingerprint to verify.

oompf add https://oompf.run/p/prof_1b7c9e0a4d2f3a5b6c8d9e0f1a2b3c4d

The canonical YAML is fetched and re-validated before anything is written. The local name defaults to <owner>-<profile> and overrides with --name. The install directory is resolved by asking OMP itself. An existing config is refused outright — there is no overwrite and no --force.

Output: the installed name, the path written, the artifact hash, the command to run it, and any warnings.

Failure modes:

• unverifiable_artifact — the reference is not an indexed OOMPF profile, or the indexed profile has no pinned revision.
• invalid_artifact — the fetched artifact failed structural validation.
• invalid_name — the derived (or --name) profile name violates OMP's naming rules; pass an explicit valid --name.
• target_exists — a profile with that name already has a config; OOMPF refuses to overwrite it.
• network_error — the index or Gist source could not be reached.

oompf inspect <ref>

Show a shared profile's metadata without installing it.

oompf inspect https://oompf.run/p/prof_1b7c9e0a4d2f3a5b6c8d9e0f1a2b3c4d

An OOMPF reference is answered from the index; a Gist reference is fetched and validated live for inspection only. OOMPF output includes the verified install command; direct Gist output does not offer an install command. The output is metadata only — models, providers, aliases, the structural verdict, and provenance. The canonical artifact content is never emitted.

Failure modes: not_found for an unknown indexed id; network_error when the index is unreachable; Gist fetch errors when the source is missing, private, or unsupported.

oompf search [query]

Free-text search over the index. Omitting the query lists all indexed profiles.

oompf search anthropic

Output: the normalized query, the result count, and one compact metadata-only record per match (id, name, owner, models, providers, revision, structural verdict, source, and canonical URL).

Failure mode: network_error when the index is unreachable.

oompf upgrade <ref> [--yes]

Review, and optionally apply, model upgrades for a profile you published. The reference must be an OOMPF URL or profile id; the Gist must be owned by your authenticated gh account.

oompf upgrade https://oompf.run/p/prof_1b7c9e0a4d2f3a5b6c8d9e0f1a2b3c4d

The plan is computed from the Gist's current head rather than the indexed pinned revision, printed for review, and applied only after confirmation (--yes skips the prompt). Applying patches the same Gist in place and re-registers the unchanged source URL, so the /p/<id> reference stays stable while its revision and fingerprint change. Successors come from a code-reviewed catalog; an unclassified model is reported unchanged rather than guessed at.

Output: the catalogRevision, the currentRevision and updatedRevision, the changes applied per role, anything left unchanged with a reason, and the oompfUrl.

Failure modes:

• invalid_ref — the reference is not an OOMPF URL or profile id.
• unverifiable_artifact — the indexed profile has no source Gist.
• unowned_gist — the Gist belongs to another account, or gh is not authenticated.
• head_changed — the Gist moved during review; nothing is patched.
• invalid_artifact / blocking_secrets — the upgraded YAML failed validation or tripped the secret scan; nothing is patched.
• index_update_failed — the Gist was patched but the index is still serving the previous bytes. upgrade waits for it and reports rather than claiming success; run the command again, and it will not patch the Gist twice.

JSON output and errors

• --json on any command returns the same data the human output renders, machine-readable.
• Failures use a stable envelope with a machine-readable code — see the codes listed per command above. Network failures map to network_error; unexpected errors fall back to the generic code error. Server errors surface the server's own code (for example not_found, validation_failed, internal_error).

Safety

• Secrets are scanned before publish. High-confidence findings block the publish with blocking_secrets; nothing leaves your machine.
• Installs never overwrite. An existing target raises target_exists; there is no --force.
• Metadata only. OOMPF indexes metadata and validation results; the canonical artifact stays at its public Gist.

Links

• Documentation: https://oompf.run/docs/
• Repository: grosspoetrysystems/oompf
• Issues: https://github.com/grosspoetrysystems/oompf/issues