codex-pet

CLI

codex-pet-cli is a tiny npm package that downloads pets from codex-pet.com and drops them into ~/.codex/pets/.

Install

npx codex-pet-cli add fox

That's it — start codex and the pet appears.

Or install globally

npm i -g codex-pet-cli
codex-pet-cli add fox

Commands

  • codex-pet-cli add <name>Install a pet from the gallery.
  • codex-pet-cli add <url>Install from a codex-pet.com URL (or any URL with --trust).
  • codex-pet-cli loginSign in via the codex-pet website using a device code.
  • codex-pet-cli logoutClear stored credentials.
  • codex-pet-cli whoamiShow the signed-in user.
  • codex-pet-cli submit <path>Submit a pet folder, .zip, or a parent of pet folders for review.
  • codex-pet-cli --versionPrint the installed version.
  • codex-pet-cli --helpShow usage.

Where do pets live?

~/.codex/pets/<name>/
  pet.json
  spritesheet.webp

Uninstall a pet

rm -rf ~/.codex/pets/fox

Submit a pet from the CLI

Already have a pet folder on disk? You can submit it without leaving the terminal.

  1. codex-pet-cli login — opens a browser for one-time authorization (device-code flow, no passwords stored locally).
  2. codex-pet-cli submit ~/.codex/pets/fox — uploads a single pet (folder must contain pet.json and spritesheet.{webp,png}, ≥ 256×256).
  3. Or point at a parent directory to submit many at once: codex-pet-cli submit ~/.codex/pets.

Submissions enter a moderation queue; they appear in the gallery once a maintainer approves them. You can also use the web submit form if you prefer a UI.

Credentials live in ~/.codex-pet/credentials.json with mode 0600. Run codex-pet-cli logout to remove them.

Manifest API

The CLI reads https://codex-pet.com/api/manifest — a public JSON list of all gallery pets. Build your own tooling against it.