The command line

Install pets

No account needed. Each pet gets its own folder in ~/.omarchy-pets/pets; open the bar panel to pick it.

1. One pet, by the id on its page

   omarchy-pets install <id>

2. Every pet in a collection

   omarchy-pets install --collection <slug>

--force

Replaces a copy whose sheet differs from the one on this site. Without it that copy is left alone, and an identical copy reports "already installed".

--dir <path>

Installs into another directory instead.

Publish a pet

1. Sign this machine in once. It prints a code and opens this page to approve it.

   omarchy-pets login

2. Publish a pet from ~/.omarchy-pets/pets. It asks for the kind when pet.json has none and for your word that you may publish the artwork, then prints the pet's page and its install command.

   omarchy-pets upload <id>

A pet is a folder named after the id in its pet.json, holding pet.json and spritesheet.webp. The first run offers to copy your Codex pets from ~/.codex/pets; the originals stay. To publish straight from Codex's folder, add --dir ~/.codex/pets.

--kind <kind>

object, animal, person or creature, instead of the question.

--tags <a,b>

Up to eight tags, separated by commas.

--yes

Confirms you may publish the artwork, instead of the question.

--as <new-id>

Publishes under another id when the one in pet.json belongs to someone else. The folder keeps its name.

--dir <path>

Reads the pet from another directory.

What the site accepts: pet.json with an id of lowercase letters, digits and single hyphens, a displayName and a description; spritesheet.webp 1536 pixels wide and 1872 high for version 1 or 2288 high for version 2, at most 6 MiB. A 2288-high sheet needs "spriteVersionNumber": 2 in pet.json. The command checks all of this before it sends anything and names the fix.

One sheet, one pet: a sheet already published under any id is refused. Publishing your pet again with the same sheet says "already published" and sends nothing. An account can publish 20 times a day.

Update

1. A pet you published, with a new sheet: it becomes a new version of the same pet

   omarchy-pets upload <id> --update

2. A pet you installed: your copy is replaced by the current version

   omarchy-pets install <id> --force

3. The bar plugin: update it, then restart the shell; the new version runs only after the restart

   omarchy plugin update raiden-meixelysia.omarchy-pets

4. Restart the shell

   omarchy restart shell

To change only a published pet's name, description, kind or tags, use "Manage this pet" on its page; the sheet stays. To update the command line itself, run the install command at the top of this page again; it replaces ~/.local/bin/omarchy-pets.

Your pets and your account

1. The pets in your directory, with their sprite version and, when signed in, which are published

   omarchy-pets list

2. The pets you published

   omarchy-pets list --remote

3. The account this machine is signed in as

   omarchy-pets whoami

4. Sign this machine out: the token is revoked and the credentials file deleted

   omarchy-pets logout

omarchy-pets login --no-browser prints the approval address instead of opening a browser. The token is kept in ~/.config/omarchy-pets/credentials.json, readable only by you.

In scripts

1. One JSON object instead of prose; --json goes before the command

   omarchy-pets --json list --remote

The exit code is 0 when it worked, 1 for something to fix, which the message names, and 2 for a network or server failure. Without a terminal nothing is asked and nothing is copied from Codex, so give upload both --kind and --yes. omarchy-pets --version prints the version.