Skip to content

README.md

Latest commit

 

History

History
192 lines (145 loc) · 9.51 KB

README.md

File metadata and controls

192 lines (145 loc) · 9.51 KB
Raw

petdex

The Petdex CLI: browse, install, and submit animated pets for your coding agents from your terminal.

The pets themselves are shown by Petdex Desktop, which connects your agents from its own Settings window. This CLI is the catalog client.

Install

# One-shot via npx (no global install)
npx petdex --help

# Or install globally
npm install -g petdex

Requires Node.js 20+ (also runs on Bun).

Quick start

petdex login                       # opens browser, OAuth + PKCE via Clerk
petdex list                        # browse approved pets
petdex install boba                 # drops boba into ~/.petdex/pets/boba/
petdex submit ~/.petdex/pets/boba   # share a single pet
petdex submit ~/.petdex/pets        # bulk submit every subfolder
petdex whoami                      # confirm signed-in identity
petdex logout                      # clear stored credentials
petdex collection list             # list your collections
petdex collection create --title "My pets" --pets boba,mochi

After installing a pet, pick the active mascot in Petdex Desktop: hover the pet and press Cmd+, to open Settings.

Desktop app

The floating mascot ships as the Petdex desktop app, not through this CLI. The app installs agent hooks from its Settings window (one click per agent) and updates itself. Download it at https://petdex.dev/download.

The init, up, down, toggle, desktop, update, doctor, and hooks commands were removed in v1.0.0; running them prints a pointer to the app.

Commands

Command Description
petdex login Authenticate via Clerk OAuth + PKCE (browser callback). Tokens stored in OS keychain.
petdex logout Clear local credentials.
petdex whoami Print the signed-in user's identity.
petdex list List approved pets in the gallery.
petdex install <slug> Install a pet into ~/.petdex/pets/<slug>/ and ~/.codex/pets/<slug>/.
petdex submit <path> Submit a pet folder, zip, or parent of pets (bulk).
petdex edit <slug> Edit a pet you own (--desc, --displayName, --sprite, --meta, --zip).
petdex collection list List your collections (--json for machine output).
petdex collection create Create a personal collection (--title, --desc, --pets, --cover, --external-url, --all-approved).
petdex collection edit <id-or-slug> Partially update a personal collection. The reference can be the collection id or slug.
petdex collection delete <id-or-slug> Delete a personal collection; requires --yes.
petdex telemetry [on|off|status] Manage anonymous usage telemetry.
petdex --version Print the CLI version.

Collection management

Collections group approved pets on your profile. All collection commands require petdex login first, and all support --json for machine-readable output.

petdex collection list --json
petdex collection create --title "My pets" --pets boba,mochi --cover boba
petdex collection list                       # copy the slug from here
petdex collection edit <slug> --desc "A small desk crew" --external-url https://example.com
petdex collection edit <slug> --all-approved
petdex collection delete <slug> --yes

collection edit and collection delete take either the collection id or its slug. New collections get a generated slug (collection-<32 hex chars>); there is no flag to set one, so read it from petdex collection list first.

--pets takes a comma-separated list of pet slugs. collection edit accepts any subset of the update flags, so omitted fields are preserved. --all-approved selects every approved pet owned by you; on create, use it only when that set has 24 or fewer pets. If you pass both --all-approved and --pets, --all-approved wins and the explicit list is ignored. Each account can have up to 10 personal collections, and --cover must name a pet in the collection — with an explicit --pets, that means the cover has to appear in the list. Pass --cover "" to clear the cover; with no --pets the collection keeps its members and shows none as the cover. --external-url accepts safe HTTPS links only. The 24-pet limit bounds growth: a collection that already exceeds it — one created before the limit existed — can still be renamed or shrunk, but not grown. An empty member list is refused, because it would remove every member; delete the collection instead.

How submit works

The CLI accepts three input shapes:

petdex submit ~/.petdex/pets/boba      # single folder (must contain pet.json + spritesheet.{webp,png})
petdex submit ~/Downloads/boba.zip     # single zip with the same root layout
petdex submit ~/.petdex/pets           # parent folder: every subfolder containing pet.json is submitted

Per submission the CLI:

  1. Builds a clean zip in memory from pet.json + spritesheet.{webp,png}.
  2. Calls POST /api/cli/submit with a Clerk OAuth bearer to get presigned R2 PUT URLs (60s TTL).
  3. PUTs the three files to Cloudflare R2 directly. No body passes through Petdex servers.
  4. Calls POST /api/cli/submit/register to record the submission as pending. Identity comes from the verified token, never from the body.

A spinner shows progress per pet; a summary lists failures with reasons. Slugs auto-deduplicate (boba → boba-2 → boba-3 → …) so submissions never rebote on collisions.

Validation rules

  • pet.json and spritesheet.webp (or .png) must exist at the root.
  • Spritesheet must be an 8x9 grid (1536x1872) or a v2 8x11 grid (1536x2288), or a clean scale of either. ChatGPT pet exports are already the v2 shape.
  • Rate limit: 10 submissions / 24h per user. Admins bypass.

Configuration

Override the defaults with environment variables when pointing at a non-production deployment:

PETDEX_URL=https://your-host.example.com \
CLERK_ISSUER=https://clerk.your-host.example.com \
CLERK_OAUTH_CLIENT_ID=public_client_id \
petdex login

Authentication details

  • OAuth 2.0 Authorization Code with PKCE (S256). Public client, no secrets stored on your machine.
  • Localhost callback on a random port (http://127.0.0.1:0/callback).
  • Tokens stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service). Falls back to a chmod 600 file if a keychain is unavailable.
  • Access tokens auto-refresh using the stored refresh token; you stay signed in until you petdex logout.

The flow uses the @clerk/cli-auth reference implementation, vendored into this package.

How to make a pet

This CLI distributes pets. It does not generate them.

In the ChatGPT desktop app. Type /pet and describe what you want, then submit the folder it writes: petdex submit ~/.codex/pets/<slug>.

From a ChatGPT pet export. ChatGPT exports a 1536x2288 spritesheet, which is the same atlas Petdex reads: nine state rows, matching frame counts. Download the PNG and drop it on https://petdex.dev/submit. The grid is measured for you and the pet.json the export omits is generated before you name it.

The full step-by-step (with tips on what makes a great pet) lives at https://petdex.dev/create.

Failure modes

Symptom Cause Fix
Not signed in No tokens or session expired petdex login
presign 401 Bearer rejected by Clerk userinfo petdex logout && petdex login
presign 429 20 CLI presign requests/hour exceeded Wait for the retry window and retry the command
register 429 10 persisted submissions/24h exceeded Wait 24h before submitting again
register 400 invalid_spritesheet Not an 8x9 or 8x11 grid Re-export at 1536x1872 or 1536x2288
register 400 missing_field Folder missing pet.json or spritesheet.{webp,png} Inspect folder contents, re-export the pet if needed
R2 PUT 403 Presigned URL expired (60s TTL) Retry the failed submission. CLI auto-presigns fresh URLs

Common install issues

The CLI is a single bundled JS file with no native dependencies. install path is just fetch a JSON manifest, write two files to ~/.petdex/pets/<slug>/. Most "stuck" reports trace to one of these:

Symptom Cause Fix
Hangs at Need to install the following packages: petdex@x npx's own confirmation prompt, not a hang. Press y or auto-confirm npx -y petdex install <slug>
npm ERR! engine Unsupported engine Node < 20 Upgrade Node to 20+ (nvm install 20 is the easiest path)
manifest fetch 5xx / network timeout Slow connection or corporate/national firewall blocking petdex.dev Set a proxy: HTTPS_PROXY=http://your.proxy:port npx petdex install <slug>
EACCES: permission denied … ~/.petdex/pets/ Pets dir owned by another user sudo chown -R "$USER" ~/.petdex or remove the dir and retry
Windows: 'sh' is not recognized CLI version older than 0.1.1 piped through curl … | sh Upgrade: npm i -g petdex@latest or npx petdex@latest install <slug>

The CLI bundles @clack/prompts, picocolors, and jszip into the shipped JS. There is no separate dependency-install step on your machine. If something appears to be stuck on "installing dependencies", it's almost always npm's own progress bar for the petdex package itself, not a sub-dependency tree.

License

MIT, same as the Petdex repo.