Codex Pet Package, CLI & API Documentation

If this is your first pet install, start with the download and install guide, then return here for the complete CLI, package, and API reference.

The CLI requires Node.js 20 or newer. You can run it once with npx, or install the package globally if you use it often.

node --version
npx codexpetdb list
npx codexpetdb install a-tom

petdb list prints the current public pet slugs. Use one of those exact slugs with install; the example above uses a pet that was public when this page was reviewed.

After a successful install, the pet is stored at $CODEX_HOME/pets/<pet-slug>. With the default CODEX_HOME, the example is at ~/.codex/pets/a-tom/ and contains pet.json plus one spritesheet.

No account is required. The CLI reads service discovery and the public Pet Catalog, downloads the approved ZIP from the trusted asset origin, and checks its content type, byte length, SHA-256 digest, ZIP structure, and manifest ID before replacing the destination. Browse the pet gallery when you want to preview a pet before installing it.

For a persistent command:

npm install --global codexpetdb
petdb version
petdb install a-tom

The petdb and codexpetdb binary names are equivalent.

A downloadable package is named <pet-slug>.zip and contains exactly two files at its root:

<pet-slug>.zip
├── pet.json
└── spritesheet.webp

The spritesheet may instead be spritesheet.png. Its filename must exactly match pet.json.spritesheetPath. poster.webp is generated for web display and is not part of the downloadable package.

A minimal manifest includes the pet identity, user-facing metadata, and spritesheet path:

{
  "id": "my-pet",
  "displayName": "My Pet",
  "description": "A calm companion for focused work.",
  "spritesheetPath": "spritesheet.webp",
  "formatVersion": 2
}

If formatVersion, rows, states, or neutralDirections are present, they must agree with the detected image format. Use the Hatch Pet guide to create the spritesheet and manifest before returning here to validate and submit them.

The CLI validates files locally before upload, and the server independently validates the uploaded objects before accepting a revision.

For a directory, keep pet.json and the spritesheet together. A submitted ZIP must keep both files at its archive root.

npx codexpetdb login
npx codexpetdb submit ./my-pet

The CLI also accepts a single ZIP or a parent directory whose direct child directories are separate pet packages. In a non-interactive environment, pass --yes. A successful submission prints the new pending revision ID and a success/failure summary.

Submitting does not publish a pet immediately:

1. The CLI creates an upload session and uploads the validated manifest, spritesheet, and generated poster.
2. Finalizing the upload creates an immutable pending revision.
3. Pending files remain private while automated or human review runs.
4. Approval makes that revision the public active revision. A pending edit does not change the currently published revision.

To change a pet you own, create another revision instead of overwriting the active files:

npx codexpetdb edit my-pet --description "A quieter companion."
npx codexpetdb edit my-pet --zip ./my-pet.zip

Use the submission page if you prefer a browser workflow. The page performs client-side checks for fast feedback, but the server remains the final validation boundary.

Start with the discovery document rather than hard-coding service origins:

curl -fsS 'https://codexpetdb.com/.well-known/codexpetdb.json'

It identifies the current public API base URL, asset origin, catalogs, docs, and supported CLI. The static catalogs are the most direct machine-readable sources for current approved pets and collections:

curl -fsS 'https://cdn.codexpetdb.com/catalogs/v1/pets.json'
curl -fsS 'https://cdn.codexpetdb.com/catalogs/v1/collections.json'

Use the JSON API when you need filtering, sorting, pagination, or detail responses:

curl -fsS \
  'https://codexpetdb.com/api/v1/pub/pets?kind=creature&sort=hot&limit=10'

List responses include items, request metadata, and pageInfo. When pageInfo.hasNextPage is true, send pageInfo.nextCursor unchanged as the next request's cursor. Invalid requests, rate limits, and service failures use application/problem+json in the RFC 9457 Problem Details shape.

--debug never prints the bearer token and limits response output to 16 KiB. Successful HTTP requests and failures without an HTTP response do not produce a debug record.

This page is maintained from the same product contracts used by the Web app and the public CLI. For current machine-readable facts, use:

• CodexPetDB service discovery
• Live Pet Catalog
• Live Collection Catalog
• Public CLI source and full command reference
• CLI issue tracker

The CLI is publicly maintained for community review. The CodexPetDB Web application and database are private, so this documentation does not describe them as open source. Report CLI bugs in the CLI issue tracker; use support@codexpetdb.com for site or account help.