Openpets

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:

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:

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:

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 before creating, repairing, validating, or submitting a manifest. Use 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:

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 only when debugging the service contract or extending the client.