# Petdex

Browse, install, submit, and edit pixel-art pets with the Petdex CLI.

- Repository: https://github.com/crafter-station/petdex (4312 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-10
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add crafter-station/petdex --skill petdex -g -a claude-code -y`
Codex: `npx skills add crafter-station/petdex --skill petdex -g -a codex -y`
Cursor: `npx skills add crafter-station/petdex --skill petdex -g -a cursor -y`
Gemini CLI: `npx skills add crafter-station/petdex --skill petdex -g -a gemini-cli -y`

## Description

Browse, install, submit, and edit pixel-art pets with the Petdex CLI. Use when a user asks for a coding companion, wants to install a Petdex pet, or wants to publish or update artwork they own.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

```sh
bunx petdex --help
bunx petdex --version
```

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

## Browse and install

```sh
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.

```sh
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

```sh
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 rest: https://github.com/crafter-station/petdex/blob/HEAD/.claude/skills/petdex/SKILL.md