# codexpethub

The official CLI for [CodexPetHub](https://codexpethub.com) — install custom pets for OpenAI Codex with a single, verified command.

```sh
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

```sh
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

```sh
# 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.