Docs

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 ~/.openclawd/buddies/boba/. To activate it inside Codex go to Settings → Appearance → Pets and click Select. Use /pet inside Codex to wake or tuck it away.

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 blockchain-buddies-cli. Even if npx clears its package cache, your session survives.

Sign in once, then any command that needs auth (e.g. submit) works seamlessly.

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

Six commands cover the full lifecycle, from discovery to publishing. All commands accept --help.

blockchain-buddies list

Print every approved pet with credit. Useful for discovery before installing.

blockchain-buddies install <slug>

Drop a pet into ~/.openclawd/buddies/<slug>/. Equivalent to curl -sSf https://buddies.solanaclawd.com/install/<slug> | sh.

blockchain-buddies submit <path>

Publish your pet(s) to the gallery. The CLI accepts three shapes:

• Single folder: blockchain-buddies submit ~/.openclawd/buddies/boba
• Single zip: blockchain-buddies submit ~/Downloads/boba.zip
• Bulk: blockchain-buddies submit ~/.openclawd/buddies: 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.

blockchain-buddies login / logout / whoami

See the Authenticate section above.

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

1. Create. In Codex Desktop, install the Hatch Pet skill and run /pet. Codex generates the spritesheet and pet.json into ~/.openclawd/buddies/<slug>/. Full tutorial at /create.
2. Sign in. npx @openclawdsolana/blockchain-buddies login if you haven't.
3. Submit. npx @openclawdsolana/blockchain-buddies submit ~/.openclawd/buddies/<slug>. Or bulk all at once with the parent dir.
4. 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).
5. Anyone can install your pet. Once approved, share npx @openclawdsolana/blockchain-buddies install <your-slug> with anyone . They get your pet in their ~/.openclawd/buddies/ instantly.

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.

OpenClawd Buddies 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 Codex" in any agent tool. It runs blockchain-buddies list, suggests Boba/Boxcat, installs your pick, and reminds you to activate via Settings → Appearance → Pets.
• Say "share all my pets". Agent runs blockchain-buddies login if needed, then blockchain-buddies submit ~/.openclawd/buddies, surfaces the bulk summary.
• Say "how do I make my own?". Agent walks you through Codex Desktop → Hatch Pet skill → /pet → blockchain-buddies 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 OpenClawd Buddies skill as a reference. Read it directly:

.claude/skills/petdex/SKILL.md

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.

• BLOCKCHAIN_BUDDIES_URL: base URL, default https://buddies.solanaclawd.com
• BLOCKCHAIN_BUDDIES_CLERK_ISSUER: OAuth issuer, default set this to your Clerk OAuth issuer
• BLOCKCHAIN_BUDDIES_CLERK_CLIENT_ID: public Clerk OAuth client id

• PRs welcome at clawdsolana/OpenClawd
• Bug reports and feature requests: open an issue
• Sponsor on GitHub Sponsors if OpenClawd Buddies saves you time.