Petdex CLI · v0.1
Docs
The Petdex CLI lets you install, browse, and submit pets from your terminal. Authentication uses OAuth 2.0 + PKCE through Clerk, and tokens persist in your OS keychain.
Quick start
Follow this checklist to get a pet installed, visible in your agent, and connected to the desktop app. No account required to install. Sign in only when you submit.
- 1
Install a known pet
Start with Boba so you have a real pet folder to select.
You should see
~/.codex/pets/boba/withpet.jsonand a spritesheet. - 2
Initialize desktop and hooks
Get the desktop app. It connects your coding agents from its Settings window, no terminal needed.
The pet floats above your workspace and reacts to every tool call.
- 3
Select the pet in the app
Open the ChatGPT desktop app, go to Settings → Appearance → Pets, choose Boba, and click Select.
Use
/petinside the app to wake the pet or tuck it away. - 4
Verify the setup
Run diagnostics if the pet does not appear, or type
/petdex statusinside a supported agent after hooks are installed.The doctor reports any missing binary, hook, token, or pet folder with a concrete fix.
petdex submit.Install
The CLI runs on Node 20+ (or Bun). Pick the workflow that fits you. Both are equivalent in capability and persistence.
Casual / one-off
Use npx. No setup, package is cached after first run.
Power user
Install globally for instant invocation and easier muscle memory.
Auth persistence is identical in both. Tokens live in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) under the service name petdex-cli. Even if npx clears its package cache, your session survives.
Authenticate
Sign in once, then any command that needs auth, such as submit, works seamlessly.
The flow is OAuth 2.0 + PKCE: the CLI opens your browser, you sign in with Clerk on accounts.petdex.dev, and the browser redirects to a one-shot localhost listener with the authorization code. The CLI exchanges it for a token set and stores it in the keychain. No secrets touch disk.
Other auth commands:
Commands
The CLI covers the full lifecycle: discover, install, hatch, publish, plus the desktop app and agent hooks. All commands accept --help.
petdex list
Print every approved pet with credit. Useful for discovery before installing.
petdex install <slug>
Drop a pet into ~/.codex/pets/<slug>/. Equivalent to curl -sSf https://petdex.dev/install/<slug> | sh.
petdex submit <path>
Publish your pet(s) to the gallery. The CLI accepts three shapes:
- Single folder:
petdex submit ~/.codex/pets/boba - Single zip:
petdex submit ~/Downloads/boba.zip - Bulk:
petdex submit ~/.codex/pets: every direct subfolder is treated as its own pet
Bulk mode shows a progress spinner per pet and a final summary of failures. Slugs auto-deduplicate so you will not hit a slug-taken bounce.
petdex collection list|create|edit|delete [options]
Manage personal collections of approved pets from the CLI. Sign in first, and add --json to any collection command for machine-readable output.
- List:
petdex collection list - Create:
petdex collection create --title "My pets" --pets boba,mochi. Use--all-approvedonly when you have 24 or fewer approved pets. - Edit:
petdex collection edit id-or-slug --desc "...". Update flags are optional and omitted fields stay unchanged. - Delete:
petdex collection delete id-or-slug --yes.
Each account can have up to 10 personal collections. The 24-pet limit bounds growth: a collection already over it can still be shrunk or renamed, but not enlarged, and an empty member list is refused when the collection still holds members, because it would remove them all. --pets takes comma-separated slugs, --cover must name a selected pet and --cover "" clears it, and --external-url must be a safe HTTPS link.
petdex login / logout / whoami
See the Authenticate section above.
Desktop app
Petdex Desktop is a floating mascot that lives on top of your workspace and reacts to your coding agent tool calls. macOS, Linux and Windows. See /download for the visual tour.
7777. Anything that can curl + read the per-session token at ~/.petdex/runtime/update-token can drive the pet. The token rotates every app boot and lives at mode 0600, so only your user can read it. Browsers and remote sites cannot:T="$(cat "$HOME/.petdex/runtime/update-token")"
curl -X POST http://127.0.0.1:7777/state \
-H "Content-Type: application/json" \
-H "X-Petdex-Update-Token: $T" \
--data-raw '{"state":"waving"}'Living with the pet
The pet floats above every window and never steals focus. Clicks pass straight through the activity bubble to whatever is behind it, so a message appearing over your editor cannot swallow a keystroke. The sprite itself stays draggable: pick it up and drop it wherever it belongs on your screen.
Shortcuts
Hover the pet and press Cmd + , to open Settings, or Cmd + W to send it away. Both also live in the Pet menu while the app is focused.
What is in Settings
- Pets. Search your installed pets, preview each one, and switch the active pet without restarting. Every custom pet you drop in the pets folder shows up here.
- Agents. Shows which coding agents are on this machine and whether their hooks are wired. Install or disconnect any of them in one click; the app writes the hook files itself, no terminal involved.
- Appearance. Scale the sprite, and turn the activity bubble on or off if you would rather have the pet stay quiet.
ChatGPT pets
ChatGPT exports pets as a 1536x2288 spritesheet, which is exactly the atlas Petdex already reads: same nine state rows, same frame counts. A pet made there works here with no conversion.
- Bringing one in. Download the spritesheet from ChatGPT, then drop the PNG on /submit. Petdex measures the grid, generates the pet.json the export does not include, and shows an animated preview before you name it.
- Taking one out. Every pet page has an Open in Codex button that installs it into the ChatGPT desktop app. Importing straight from a ChatGPT share link is not possible: those URLs are locked to the browser session that created them.
Distribute your pets
Once you have hatched a pet, sharing it takes one command. Here's the full lifecycle:
- Create. In the ChatGPT desktop app, install the Hatch Pet skill and run
/pet. It generates the spritesheet and pet.json into~/.codex/pets/<slug>/. Full tutorial at /create. - Sign in.
npx petdex loginif you have not. - Submit.
npx petdex submit ~/.codex/pets/<slug>. Or bulk all at once with the parent dir. - Wait for review. Submissions land as “pending” in the admin queue. You will receive a Resend email when approved or rejected (if rejected, the reason is included).
- Anyone can install your pet. Once approved, share
npx petdex install <your-slug>with anyone. They get your pet in their~/.codex/pets/instantly.
Validation rules
The server enforces these rules; the CLI checks locally too.
pet.jsonandspritesheet.webp(or.png) must be at the root of the folder/zip.- Spritesheet ≥ 256×256. Recommended 1536×1872 (8×9 frame grid).
- Rate limit: 10 submissions / 24h per user. Admins bypass.
- Slugs auto-deduplicate (
boba→boba-2→boba-3→ …). You always get a successful submission. - Identity (userId, email, credit) comes from the verified OAuth token. Never trusted from request body.
Failure modes
| Symptom | Cause | Fix |
|---|---|---|
| Not signed in | No tokens or session expired | petdex login |
| presign 401 | Bearer rejected by Clerk userinfo | petdex logout then petdex login |
| presign 429 | 10/24h rate limit hit | Wait 24h or open a submit-fallback issue |
| register 400 invalid_spritesheet | Sprite < 256×256 | Regenerate at 1536×1872 |
| register 400 missing_field | Folder missing pet.json or spritesheet | Inspect folder contents |
| R2 PUT 403 | Presigned URL expired (60s TTL) | Retry: CLI auto-presigns fresh URLs |
Agent-first usage (Skill)
Petdex ships a Claude Code / Codex / Cursor compatible skill at .claude/skills/petdex/SKILL.md. Compatible agents load it automatically and learn when and how to call the CLI on your behalf.
What this enables
- Say “install something cozy for my agent” in any agent tool. It runs
petdex list, suggests Boba/Boxcat, installs your pick, and reminds you to activate via Settings → Appearance → Pets. - Say “share all my pets”. Agent runs
petdex loginif needed, thenpetdex submit ~/.codex/pets, surfaces the bulk summary. - Say “how do I make my own?”. Agent walks you through the ChatGPT desktop app → Hatch Pet skill →
/pet→petdex submit.
How to enable it
If you use Claude Code, save the skill globally so every project has it:
Other agent tools can load the same SKILL.md from the repo. The file is plain markdown. No agent-specific syntax beyond allowed-tools.
Build your own skill on top
The CLI is the executable surface; the skill is the cognitive one. If you build a derivative skill (for example, one that auto-tags new pets or curates a daily digest), you can use the Petdex skill as a reference. Read it directly:
Configuration
The CLI ships with sensible defaults pointing at production. You only need to override env vars if you are testing against a non-production deployment.
PETDEX_URL: base URL, defaulthttps://petdex.devCLERK_ISSUER: OAuth issuer, defaulthttps://clerk.petdex.devCLERK_OAUTH_CLIENT_ID: public client id (baked into the CLI binary)
Contribute
- PRs welcome at crafter-station/petdex
- Bug reports and feature requests: open an issue
- Sponsor on GitHub Sponsors if Petdex saves you time.