codexpethub

The official CLI for CodexPetHub — install custom pets for OpenAI Codex with a single, verified command.

npx codexpethub install null-puff

The CLI fetches the pet's install manifest from codexpethub.com, verifies every file against the published sha256, and writes the result into your Codex pets folder.

Install location

Pets are installed under your Codex home directory:

| Platform | Default install root | | --- | --- | | macOS / Linux | $CODEX_HOME if set, otherwise ~/.codex | | Windows | %CODEX_HOME% if set, otherwise %USERPROFILE%\.codex |

A pet named null-puff lands at ~/.codex/pets/null-puff/ and contains:

~/.codex/pets/null-puff/
├── pet.json          # Pet metadata + atlas geometry
└── spritesheet.webp  # Animated sprites

Override the location with --codex-home <path>.

Usage

codexpethub install <slug> [options]

Options

| Flag | Description | | --- | --- | | --codex-home <path> | Override the install root (default: $CODEX_HOME or ~/.codex). | | --overwrite | Replace an existing install for this slug. Without it, the CLI refuses to clobber. | | --registry-url <url> | Use a custom registry. Allow-listed: https://codexpethub.com, https://assets.codexpethub.com. | | -h, --help | Show usage and exit. |

Examples

# Install the latest published version of null-puff
npx codexpethub install null-puff

# Reinstall on top of an existing folder
npx codexpethub install boba --overwrite

# Install into a sandbox dir (useful for CI / testing)
npx codexpethub install boba --codex-home /tmp/test-codex

Verification

Every install:

1. Fetches <registry-url>/api/v1/pets/<slug>/install-manifest.json.
2. Validates schema_version === "codexpethub.install.v1".
3. Confirms every download URL is on the host allow-list.
4. Streams files to a temp directory, computing sha256 on the fly.
5. Aborts (and cleans up) if any hash, size cap, or file format check fails.
6. Atomically moves the verified files into the install dir.

Exit codes:

| Code | Reason | | --- | --- | | 0 | Success or --help. | | 1 | sha256 mismatch. | | 2 | File exceeded the size cap. | | 3 | Manifest URL or download URL outside the allow-list. | | 4 | Install folder exists and --overwrite was not passed. | | 5 | Network error fetching the manifest or a file. | | 64 | Usage error (unknown flag, missing subcommand, etc.). |

After install

1. Open Codex → Settings → Appearance → Pets.
2. Click Refresh custom pets.
3. Send /pet in a chat to wake the new pet.

Source

The CLI source lives at https://github.com/CodexPetHub/CodexPetHub/tree/main/packages/cli. It has zero runtime dependencies — only Node.js builtins.

License

MIT © CodexPetHub.