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`, `pi`, `kimi-code`)
`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

npx 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	npm package
`opencode`	OpenCode	`@maestria/opencode`
`pi`	Pi	`@maestria/pi`
`kimi-code`	Kimi Code	`@maestria/kimi-code`

Error handling

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

Scenario	Error message
Unknown platform ID	`Unknown platform 'cursor'. Valid platforms: opencode, pi, kimi-code`
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

npx 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
npx maestria status

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

Example

npx maestria update --all

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.