openpets

---
name: "openpets"
description: "Browse the public Open Pets catalog, fetch metadata, submit and publish a Codex pet, and safely install a pet's manifest and sprite sheet. Use when a user asks to list, discover, search for, inspect, download, fetch, submit, share, upload, publish, add, or install Open Pets or Codex pets."
license: "MIT"
---

# Open Pets

Use the bundled `scripts/openpets.py` client for catalog operations. It uses only the Python
standard library.

## Service URL

Always use `https://www.openpets.space`. Do not ask the user for the site URL. The client uses this
production origin by default; use `--base-url` only for explicit local development or testing.

## List pets

Fetch one catalog page:

```sh
python3 scripts/openpets.py list --page 1 --page-size 12
```

Add `--json` when structured output is more useful. Follow `hasNextPage` and increment `--page`
only when the user asks for more or all results. Do not fetch every page unnecessarily.

## Fetch one pet

Use the lowercase slug returned by `list`:

```sh
python3 scripts/openpets.py fetch example-pet
```

Use `--json` to preserve the complete API representation. Report the creator, description, tags,
sprite version, and availability of installation files.

## Install a pet

Install into the default Codex pet directory:

```sh
python3 scripts/openpets.py install example-pet
```

The default destination is `~/.codex/pets/<slug>`. The installer:

- fetches current metadata from the server;
- downloads `pet.json` and the referenced sprite sheet;
- validates the manifest, relative sprite path, response size, and image signature;
- stages files before replacing the destination;
- refuses to overwrite an existing pet unless `--force` is provided.

Use `--pets-dir <directory>` only when the user requests a different install root. Ask before
`--force` unless the user already requested replacement or upgrade. Never use `sudo`.

After installation, report the exact installed directory and remind the user to restart or reload
Codex if the pet is not immediately visible.

## Submit a pet

Collect and validate:

- creator name;
- private contact email;
- optional comma-separated tags;
- local `pet.json`;
- the sprite sheet referenced by `spritesheetPath`.

Read [references/pet-config.md](references/pet-config.md) before creating, repairing, validating, or
submitting a manifest. Use [references/pet.schema.json](references/pet.schema.json) as the
machine-readable schema. A submission must pass both manifest validation and version-specific atlas
checks before it is sent.

Before sending, show the user the destination site, creator name, contact email, tags, and exact
file paths. Obtain confirmation because this uploads files and private contact information to an
external service.

Submit directly through the public API:

```sh
python3 scripts/openpets.py submit \
  --creator-name "Example Creator" \
  --contact-email "creator@example.com" \
  --tags "cat,cozy,pixel" \
  --manifest ./pet.json \
  --spritesheet ./spritesheet.webp
```

For the MVP, every valid submission is published immediately. Report the submission ID, final
`publishedSlug`, public pet page, and status. The final slug can differ when the requested slug
already exists. Do not retry automatically after an ambiguous network failure because the first
request may have succeeded.

## Errors

Treat nonzero exit status as failure. Preserve the concise error message in the response. Common
cases:

- `400`: invalid page or slug;
- `404`: no published pet with that slug;
- `503`: catalog temporarily unavailable;
- `413`/`422`: submission files or metadata failed validation;
- missing asset URLs: the pet is visible but not installable yet;
- existing destination: require an explicit replacement request.

Read [references/api.md](references/api.md) only when debugging the service contract or extending
the client.