Command Reference

Global Flags

These flags work on every command:

Flag	Description
--json	Output results as JSON instead of formatted text
--quiet	Suppress spinner animations
--compact	Machine-friendly text output - one line per platform

Running maestria with no arguments is equivalent to maestria status.

---

status

Show what’s installed and version information for all platforms.

maestria status [--json] [--quiet] [--compact]

Detects which coding agent CLIs are available on $PATH, checks whether maestria is installed for each, and reports the installed and latest versions. Platform detection runs in parallel.

Flags

Flag	Description
--json	Output as JSON (see schema below)
--quiet	Suppress non-essential output
--compact	Machine-friendly text - one line per platform

JSON schema

{
  "platforms": [
    {
      "id": "opencode",
      "label": "OpenCode",
      "available": true,
      "installed": true,
      "installedVersion": "0.6.0",
      "latestVersion": "0.6.2"
    }
  ]
}

Each platform object:

Field	Type	Description
id	string	Platform identifier (opencode, omp, pi, kimi-code, hermes, cursor)
label	string	Human-readable name
available	boolean	CLI tool detected on $PATH
installed	boolean	Maestria is installed for this platform
installedVersion	string	Version string from the installed package
latestVersion	string	Latest version available on npm

Compact output

With --compact, status outputs one line per platform with no colors or decorative formatting:

opencode: available installed=0.2.1 latest=0.2.1
pi: not-available not-installed
kimi-code: available installed=0.1.0 latest=0.2.1

Ideal for AI agents and token-sensitive environments. Implies --quiet (no spinner animations).

Example

npm

npx maestria status

pnpm

pnpx maestria status

yarn

yarn dlx maestria status

---

install

Install maestria plugins for one or more coding agent platforms.

maestria install [platform] [--all] [--json] [--quiet] [--compact]

Flags

Flag	Description
platform	Positional arg - platform to install. Comma-separated for multiple (e.g., opencode,pi). Omit for interactive picker.
--all, -a	Install for all detected platforms
--json	Output results as JSON
--quiet	Suppress spinner animations
--compact	Machine-friendly text output - one line per result

Behavior

Invocation	What happens
maestria install	Detects platforms, shows an interactive multiselect picker (checkboxes)
maestria install opencode	Installs for OpenCode only
maestria install opencode,pi	Installs for OpenCode and Pi simultaneously
maestria install --all	Installs for every detected platform that lacks maestria
maestria install opencode --json	Installs OpenCode, outputs JSON result

Platform identifiers

ID	Platform	Distribution
opencode	OpenCode	@maestria/opencode (npm)
pi	Pi	@maestria/pi (npm)
kimi-code	Kimi Code	@maestria/kimi-code (npm)
hermes	Hermes	Git-based via hermes plugins install
cursor	Cursor	@maestria/cursor (npm)
omp	Oh My Pi	@maestria/omp (npm)

Error handling

Input validation - the CLI catches invalid arguments before any platform work begins:

Scenario	Error message
Unknown platform ID	Unknown platform 'foo'. Valid platforms: opencode, omp, pi, kimi-code, hermes, cursor
Invalid version format	Invalid version '2.0'. Use semver format (e.g., 0.5.0) or 'latest'.
--all with a platform arg	Cannot use --all with a specific platform. Choose one.

Runtime errors - if a platform command fails (e.g., network error, missing binary), the CLI catches it and reports the failure per-platform rather than aborting the entire batch:

✔ OpenCode: Installed
✗ Pi: Command failed: pi install npm:@maestria/pi

Example

npm

npx maestria install --all

pnpm

pnpx maestria install --all

yarn

yarn dlx maestria install --all

---

update

Update maestria plugins to the latest (or specified) version.

maestria update [platform] [--version <semver>] [--all] [--json] [--quiet] [--compact]

Flags

Flag	Description
platform	Positional arg - platform to update. Comma-separated for multiple (e.g., opencode,pi). Omit for interactive picker.
--version, -V	Specific version to install (e.g., 0.5.0). Defaults to latest.
--all, -a	Update all installed platforms
--json	Output results as JSON
--quiet	Suppress spinner animations
--compact	Machine-friendly text output - one line per result

Behavior

Same logic as install but targets platforms where maestria is already installed. Before-and-after version numbers are shown when available:

✔ OpenCode: Updated: v0.5.0 → v0.6.0
✔ Pi: Already up to date (v0.4.1)

Use --version to pin a specific version instead of the latest:

maestria update opencode --version 0.5.0

Invocation	What happens
maestria update	Detects installed platforms, shows interactive grouped multiselect picker with “All platforms” toggle header and a key to toggle all
maestria update opencode	Updates OpenCode to the latest version
maestria update opencode,pi	Updates OpenCode and Pi simultaneously
maestria update opencode --version 0.5.0	Updates OpenCode to v0.5.0 specifically
maestria update --all	Updates all installed platforms to latest
maestria update --all --version 0.5.0	Updates all installed platforms to v0.5.0

Version caching

The CLI caches npm view <package> version results for 1 hour in ~/.cache/maestria/versions.json:

{
  "@maestria/opencode": { "version": "0.6.2", "cachedAt": 1719600000000 }
}

To force a fresh version check before running a command:

rm ~/.cache/maestria/versions.json

npm

npx maestria status

pnpm

pnpx maestria status

yarn

yarn dlx maestria status

The cache is automatically invalidated after a successful update, so maestria status always shows the correct latest version after an upgrade.

Example

npm

npx maestria update --all

pnpm

pnpx maestria update --all

yarn

yarn dlx maestria update --all

Tip

Use maestria status before maestria update --all to see which platforms have updates available.

Tip

Run maestria <command> --help for in-terminal examples and exit code documentation, including a TIP FOR AI AGENTS section with usage guidance for automated environments.

Exit Codes

Code	Meaning
0	Success
1	Validation or command error
130	User cancelled (interactive mode only)

The install and update commands detect non-interactive terminals and exit with code 1 showing a clear error message instead of attempting an interactive prompt.

---

configure

Choose which model each maestria specialist agent uses, per platform.

maestria configure <platform> [--global|--project] [--set <agent>=<model>[,...]] [--json] [--quiet] [--compact]

Supported platforms: opencode, pi, omp. The 7 specialists (adventurer, architect, builder, diagnose, planner, reviewer, writer) can each use a different model. Agents without a configured model inherit the session model.

Interactive (TTY)

npm

npx maestria configure opencode

pnpm

pnpx maestria configure opencode

yarn

yarn dlx maestria configure opencode

Shows a group-multiselect of the 7 specialists, then a per-agent model picker with the current model pre-selected and an Inherit (session model) option. The model list is fetched live from the platform (opencode models, pi --list-models, omp models --json).

Non-interactive (CI)

npm

npx maestria configure opencode --global --quiet --set adventurer=<model-id>,writer=<model-id>

pnpm

pnpx maestria configure opencode --global --quiet --set adventurer=<model-id>,writer=<model-id>

yarn

yarn dlx maestria configure opencode --global --quiet --set adventurer=<model-id>,writer=<model-id>

• --set <agent>=<model>[,...] - comma-separated pairs; an empty value (reviewer=) resets the agent to inherit the session model
• --global / --project - config level, mutually exclusive; --set and other non-interactive usage require exactly one of these flags
• Choose each explicit model ID from the platform’s normal, live model list. Models are validated against that list before writing.
• --set changes only the agents you name. Unmentioned agents keep their existing assignments.

For a partial assignment, set a model for any role you want to change:

maestria configure <platform> --global --set planner=<model-id>

Unmentioned agents remain unchanged. Configuration currently supports OpenCode, Pi, and OMP.

Flags

Flag	Description
--global	Configure the user-level config (~/.config/opencode/, ~/.pi/agent/, ~/.omp/agent/)
--project	Configure the project-level config (.opencode/, .pi/agents/, .omp/agents/)
--set	Set models non-interactively, e.g. planner=<model-id>
--json	Output the resulting config as JSON
--quiet	Suppress spinner output (recommended for CI)
--compact	Minimal machine-friendly text output

JSON schema

{
  "platform": "opencode",
  "label": "OpenCode",
  "level": "global",
  "models": {
    "adventurer": "<model-id>",
    "builder": "<model-id>",
    "reviewer": ""
  }
}

An empty string means the agent inherits the session model.

Where the config is written

Platform	Global	Project
opencode	~/.config/opencode/opencode.jsonc	.opencode/opencode.jsonc
pi	~/.pi/agent/agents/<name>.md	.pi/agents/<name>.md
omp	~/.omp/agent/agents/<name>.md	.omp/agents/<name>.md

opencode writes the agent.<name>.model key (preserving comments and the variant key); pi and omp set the model: line in the agent’s frontmatter. For pi/omp, a missing project agent file is created from the global one.

Tip

Restart the coding agent (or reload its config) for changes to take effect.