petbox-wire weekly downloads statistics

petbox-wire

Wire any project to PetBox for Claude Code, opencode and Factory Droid — one command, no repo clone:

npx petbox-wire <dir> <project> --key <KEY>

Full documentation: https://petbox.3po.su/doc/wire.

Requirements

Node >= 23.6 — the kit is plain TypeScript run through Node's native type-stripping (no build, zero runtime dependencies). Older Node exits with a clear version error.

Commands

Command	What it does
petbox-wire <dir> <project>	Full wire: validate the key → persist it → copy the kit → register the directory → write per-project MCP configs and skills → install the global hooks → self-smoke. Idempotent.
petbox-wire update	Refresh only the stable kit under ~/.petbox/wire/ (exact mirror + orphan cleanup, content hash before → after). No keys, no registry, no hook reinstall, no MCP/skills, no sticky-flag reset. Does not compile agent files.
petbox-wire apply [--offline]	Compile the per-harness agent role files from the portable agent definition (built from files: base < user < project) + your local role→model binding.
petbox-wire layers [dir...]	Show the definition cascade: which layers exist, what each did to the roster, and which layer supplied every field. Read-only.
petbox-wire status [--offline]	Print fact, not a verdict: per role × harness, the materialized artifact path, its bound model and where that model came from, plus a layers/roster/canon/skills summary. Read-only, never gates; --offline skips network lookups (the definition never needed one). Always exits 0 unless status itself crashes.
petbox-wire doctor [--offline]	Gate (exit code is significant): resolves the agent definition from the file cascade (base < user < project) and checks it against every known harness, printing OK or each violation, plus the layers and their per-field provenance. A broken layer is a hard failure here, same as in apply. Also reports skill-file drift against the kit templates, the session-banner budget margin, and a tail of ~/.petbox/wire.log. Network checks are skipped with an explicit reason when the server is unreachable; --offline skips them itself up front (skill-file drift and banner-budget checks) — the definition resolve and the truthfulness gate still run, because neither touches a network.
petbox-wire roles	Print the active profile and its role→model bindings (~/.petbox/roles.json), each with the provider serving it and whether the kit or you set it. Offline; an empty store exits 0 — no model is ever invented.
petbox-wire roles export	Write a bootstrap copy of roles.json to stdout (no secrets). Pipe it to a file on a new machine.
petbox-wire profile use <name>	Set activeProfile in ~/.petbox/roles.json. Compiles nothing — re-run apply.
petbox-wire model set <role> <model> [--agent <id>] [--profile <name>] [--allow-unknown-model]	The only sanctioned way to write a role→model binding to ~/.petbox/roles.json. Compiles nothing — prints next: petbox-wire apply.
petbox-wire model unset <role> [--agent <id>] [--profile <name>]	Remove a role→model binding for the given agent/profile from ~/.petbox/roles.json. Compiles nothing — re-run apply afterwards.

update, apply, status, doctor, roles, profile and model take no <dir> <project>.

Flags (full wire)

Flag	Effect
--key <KEY>	The project's API key. Mint it on the project's Connect agent page in the UI — key minting is out of scope for this tool. Omitted → taken from the env var, then from ~/.petbox/keys.json.
--env <VAR>	Override the env-var name holding the key.
--workspace <WS>	Workspace stamped into the generated SKILL.md. Omitted → the workspace the server reports for your key; if neither is available the wire stops with a usage error (exit 2).
--cleanup-legacy	Remove a project's old per-project hook/plugin copies.
--telemetry	Wire Claude Code OTLP export into the project (off by default; Claude Code only).
--telemetry-log <name>	Target named log for telemetry (default cc-telemetry; created if missing).
--help, -h	Usage banner, exit 0.

The API key is validated against the server before anything is persisted, so a bad key never lands in your stores.

The env-var name

The key is held in PETBOX_<PROJECT>_API_KEY — the project key upper-cased, runs of non-alphanumeric characters collapsed to _, leading/trailing _ trimmed, PETBOX_ prefixed (kpvotes → PETBOX_KPVOTES_API_KEY). Same name the UI's Connect page shows you. --env overrides it, and a re-run reuses whatever name is already recorded for that directory — so a machine wired before this scheme keeps its older variable. ~/.petbox/keys.json is the ground truth for the name your machine actually has.

What it installs…