# 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.
```bash
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
```json
{
"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
---
## `install`
Install maestria plugins for one or more coding agent platforms.
```bash
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
---
## `update`
Update maestria plugins to the latest (or specified) version.
```bash
maestria update [platform] [--version ] [--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:
```bash
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 version` results for 1 hour in `~/.cache/maestria/versions.json`:
```json
{
"@maestria/opencode": { "version": "0.6.2", "cachedAt": 1719600000000 }
}
```
To force a fresh version check before running a command:
```bash
rm ~/.cache/maestria/versions.json
```
The cache is automatically invalidated after a successful update, so `maestria status` always shows the correct latest version after an upgrade.
### Example
**Tip:** Use `maestria status` before `maestria update --all` to see which platforms have updates
available.
**Tip:** Run `maestria --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.
```bash
maestria configure [--global|--project] [--set =[,...]] [--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)
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)
- `--set =[,...]` - 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:
```bash
maestria configure --global --set planner=
```
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=` |
| `--json` | Output the resulting config as JSON |
| `--quiet` | Suppress spinner output (recommended for CI) |
| `--compact` | Minimal machine-friendly text output |
### JSON schema
```json
{
"platform": "opencode",
"label": "OpenCode",
"level": "global",
"models": {
"adventurer": "",
"builder": "",
"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/.md` | `.pi/agents/.md` |
| omp | `~/.omp/agent/agents/.md` | `.omp/agents/.md` |
opencode writes the `agent..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.