CLI & shell scripts + OpenPets

What this integration does

The OpenPets CLI lets terminal commands talk to your running OpenPets desktop app. Use it when you want a pet reaction from a shell script, an npm script, a local build command, a git hook, or a custom automation tool.

Command	What it does	Good for
`npx -y @open-pets/cli@latest status`	Checks whether the desktop app is reachable.	Setup checks and troubleshooting.
`npx -y @open-pets/cli@latest pets`	Lists installed pets and marks the default pet.	Finding pet ids before routing setup.
`npx -y @open-pets/cli@latest react <reaction>`	Changes the pet reaction without showing text.	Silent success, error, testing, waiting, or working states.
`npx -y @open-pets/cli@latest say <message>`	Shows one short visible speech bubble.	Meaningful local automation updates.

The CLI is distributed as the npm package @open-pets/cli. The desktop app does not install a shell command; use npx for one-off commands, npm exec for explicit package execution, or an optional global npm install if you want a permanent openpets command.

Requirements

The OpenPets desktop app must be running.
Node.js and npm must be available for npx, npm exec, or optional global npm installs.
The CLI talks to the desktop app over OpenPets local IPC; it does not send commands through a cloud service.

Quick start with npx

Use npx when you want the command without installing anything globally. The examples below always fetch the latest published OpenPets CLI.

Check desktop statusbash

npx -y @open-pets/cli@latest status

List installed petsbash

npx -y @open-pets/cli@latest pets

Send a reactionbash

npx -y @open-pets/cli@latest react success

Show a short messagebash

npx -y @open-pets/cli@latest say "Build finished" --reaction celebrating

If your npm environment has stale npx cache metadata, the equivalent npm exec form is:

npm exec formbash

npm exec --yes --package=@open-pets/cli@latest -- openpets --help

Optional global install

If you want to type openpets directly in your terminal, install the CLI globally. This is separate from downloading the desktop app.

Install oncebash

npm install -g @open-pets/cli

Use directlybash

openpets status
openpets react testing
openpets say "Tests are running" --reaction testing

Shell script examples

Keep messages short and human-facing. Use reactions for noisy steps and speech only for meaningful moments.

npm test notificationbash

npm test \
  && npx -y @open-pets/cli@latest say "Tests passed" --reaction success \
  || npx -y @open-pets/cli@latest say "Tests failed" --reaction error

Build scriptbash

npx -y @open-pets/cli@latest react running
pnpm build
npx -y @open-pets/cli@latest react success

package.json scriptjson

{
  "scripts": {
    "test:pet": "npm test && npx -y @open-pets/cli@latest say 'Tests passed' --reaction success"
  }
}

Available reactions

The CLI accepts the same reaction names as the OpenPets local client and MCP tools:

Reaction namestext

idle
thinking
working
editing
running
testing
waiting
waving
success
error
celebrating

Message safety

Pet speech is visible on your desktop. Treat it like a tiny public status channel, not a log sink.

Good	Avoid
`Build finished.`	Full command output or stack traces.
`Tests are running.`	File paths, URLs, or private repo details.
`Waiting for review.`	Secrets, tokens, prompts, or user messages.

Use the CLI as an explicit automation boundary

The CLI is for manual and script-driven status: status checks the desktop, pets finds targets, and react and say update the pet. Choose npx, npm exec, or a global install according to how often the command runs. Reaction names and speech are validated strictly, and the desktop app must be running. This is deliberate automation rather than lifecycle hooks; use the or for ambient agent events.

Troubleshooting

`npx -y @open-pets/cli@latest status` says the app is unavailable

Open the OpenPets desktop app first.
Restart the desktop app if it was updated while running.
Run npx -y @open-pets/cli@latest status again.

The desktop app did not install a shell command

Downloading the desktop app does not install a shell command. Use npx -y @open-pets/cli@latest ..., use npm exec, or install @open-pets/cli globally with npm if you want a permanent command.

A reaction name is rejected

Use one of the reaction names listed above. The CLI validates reaction names before sending them to the desktop app.