Petdex CLI · v0.1

Docs

The Petdex CLI lets you install, browse, and submit Codex pets from your terminal. Authentication is OAuth 2.0 + PKCE through Clerk. Tokens persist in your OS keychain. Same auth works across npx and global installs.

npmjs.com/petdex Repo

Quick start

Install a curated pet into your Codex setup with one command. No account required to install. Sign in only when you submit.

The CLI fetches the pet pack and drops it into ~/.codex/pets/boba/. To activate it inside Codex go to Settings → Appearance → Pets and click Select. Use /pet inside Codex to wake or tuck it away.

Don't have a pet idea yet? Hatch your own with the Codex Hatch Pet skill, then come back to petdex submit.

Install

The CLI runs on Node 18+ (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

The flow is OAuth 2.0 + PKCE: the CLI opens your browser, you sign in with Clerk on accounts.petdex.crafter.run, 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

Six commands cover the full lifecycle, from discovery to publishing. 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.crafter.run/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'll never get a "slug taken" rebote.

`petdex login / logout / whoami`

See the Authenticate section above.

Distribute your pets

Once you've hatched a pet inside Codex, sharing it takes one command. Here's the full lifecycle:

Create. In Codex Desktop, install the Hatch Pet skill and run /pet. Codex generates the spritesheet and pet.json into ~/.codex/pets/<slug>/. Full tutorial at /create.
Sign in. npx petdex login if you haven't.
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'll 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.

Pets are user-submitted fan art. Petdex doesn't claim rights to underlying IP. If you're a rights holder requesting a takedown, see /legal/takedown.

Validation rules

The server enforces these rules; the CLI checks locally too.

pet.json and spritesheet.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 CLI / 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 Codex" 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 login if needed, then petdex submit ~/.codex/pets, surfaces the bulk summary.
Say "how do I make my own?". Agent walks you through Codex Desktop → 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 with. 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 (e.g. one that auto-tags new pets or curates a daily digest), you can use the Petdex skill as a reference. Read it directly:

.claude/skills/petdex/SKILL.md

Configuration

The CLI ships with sensible defaults pointing at production. You only need to override env vars if you're testing against a non-production deployment.

PETDEX_URL: base URL, default https://petdex.crafter.run
CLERK_ISSUER: OAuth issuer, default https://clerk.petdex.crafter.run
CLERK_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.