Petdex

Use the published petdex CLI for the catalog. Node.js 20 or later is required.

Read the current command help before using unfamiliar flags:

bunx petdex --help
bunx petdex --version

If Bun is unavailable, use npx -y petdex for the same commands.

Browse and install

bunx petdex list
bunx petdex install boba
bunx petdex install boba mochi

Choose a slug from the catalog. Installation writes the pet to both ~/.petdex/pets/<slug>/ and ~/.codex/pets/<slug>/. Report the installed slugs and any command failure.

Submit artwork

Publish only artwork the user has asked to submit, with the license they selected. If the license is missing, ask rather than choosing the rights for them.

bunx petdex login
bunx petdex whoami
bunx petdex submit ./my-pet --license cc-by

Login opens a browser and stores credentials locally. A headless session needs an existing login; never ask the user to paste tokens.

The example uses CC BY. Supported license IDs are cc0, cc-by, cc-by-sa, cc-by-nc, and all-rights-reserved. Each pet folder needs pet.json and spritesheet.webp or spritesheet.png. The sheet must use the supported 8-by-9 or 8-by-11 atlas layout. A ZIP or a parent directory containing multiple pets is also accepted.

Let duplicate detection run normally. Use --force only when the user wants duplicate submissions. Report the submission result; submission is not approval or publication in the gallery.

Edit a pet the user owns

bunx petdex edit boba --desc "A tiny otter sipping bubble tea"
bunx petdex edit boba --sprite ./spritesheet.webp

Send only the requested changes. The CLI also accepts --displayName, --meta, and --zip.

Desktop controls

The floating companion is Petdex Desktop, available at https://petdex.dev/download. Its Settings window selects the pet and installs agent hooks. The catalog CLI does not start the desktop app or manage those hooks. Retired commands such as init, up, doctor, select, and hooks install are not the setup flow.

For authentication trouble, run whoami and follow the CLI error. For unsupported commands or flags, use --help. Do not treat a nonzero exit as success.