Skip to content
maestria

Command Reference

Global Flags

Section titled “Global Flags”

These flags apply across the CLI:

Flag Description
--json Output results as JSON instead of formatted text on every command
--quiet Suppress spinner animations on runtime platform commands

Spinners render only for human-readable output on a terminal: --json, --compact, and redirected or piped stdout leave them out, so maestria status --json | jq reads clean JSON.

--compact (machine-friendly text) is supported on status, install, update, uninstall, and configure. check and doctor support --json and --quiet only; plugin validate and plugin install support --json only. Every command’s --help shows exit codes; examples appear on every command except uninstall.

maestria with no arguments runs maestria status. maestria --version (or -v) prints the CLI version.

status

Section titled “status”

Show installed and available versions for all platforms.

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

Detects coding agent CLIs on $PATH, reports whether maestria is installed for each, and lists installed and latest versions. Detection runs in parallel.

Flags

Section titled “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

Section titled “JSON schema”
{
  "platforms": [
    {
      "id": "opencode",
      "label": "OpenCode",
      "available": true,
      "installed": true,
      "installedVersion": "0.6.0",
      "latestVersion": "0.6.2"
    }
  ]
}

Version values are illustrative; the command reports locally found and registry versions.

Each platform object:

Field Type Description
id string Platform identifier (opencode, omp, pi, kimi-code, hermes, cursor, claude-code, codex)
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

Section titled “Compact output”

With --compact, status outputs one undecorated line per platform:

opencode: available installed=0.8.0 latest=0.8.0
pi: not-available not-installed
kimi-code: available installed=0.6.11 latest=0.7.0
claude-code: available installed=0.7.0 latest=0.7.0
codex: available installed=0.7.0 latest=0.7.0

Implies --quiet (no spinner animations).

Example

Section titled “Example”
Terminal window
npx maestria status

install

Section titled “install”

Install maestria for one or more coding agent platforms.

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

Flags

Section titled “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

Section titled “Behavior”
Invocation What happens
maestria install Detects platforms, shows an interactive multiselect picker
maestria install opencode Installs for OpenCode only
maestria install opencode,pi Installs for OpenCode and Pi in one run, one platform at a time
maestria install --all Installs for every detected platform that lacks maestria
maestria install opencode --json Installs OpenCode, outputs JSON result

Every maestria package bundles the create-pull-request, docs-update, diagnose, and plan skills, so install adds no separate skills. The --skills, --exclude-skills, and --maestria-skills flags were removed; passing one fails before any change.

Platform identifiers

Section titled “Platform identifiers”
ID Platform Distribution
opencode OpenCode V2 @maestria/opencode (npm) via opencode plugin
pi Pi @maestria/pi (npm)
kimi-code Kimi Code @maestria/agent-plugins (npm)
hermes Hermes Git-based via hermes plugins install
cursor Cursor @maestria/agent-plugins (npm)
omp Oh My Pi @maestria/agent-plugins (npm, native data resources)
claude-code Claude Code npm package staged into a local Claude Code marketplace
codex Codex CLI npm package staged into a local Codex marketplace

Platform-specific installation behavior

Section titled “Platform-specific installation behavior”

Claude Code and Codex CLI use host-native marketplace managers; the CLI first stages the published npm package in the maestria cache directory ($XDG_CACHE_HOME/maestria/ when set, otherwise ~/.cache/maestria/). Claude Code configuration remains host-owned; Codex also receives complete native agent TOMLs under $CODEX_HOME/agents/ and a marked global policy and routing block in $CODEX_HOME/AGENTS.override.md when that file is in use, otherwise $CODEX_HOME/AGENTS.md ($CODEX_HOME defaults to ~/.codex). Marketplace-only Codex installation supplies the six skills.

Error handling

Section titled “Error handling”

Input validation - unknown platform IDs fail before any platform work:

Scenario Error message
Unknown platform ID Unknown platform 'foo'. Valid platforms: opencode, omp, pi, kimi-code, hermes, cursor, claude-code, codex

Runtime errors - a failing platform command (network error, missing binary) is reported per-platform instead of aborting the batch:

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

Example

Section titled “Example”
Terminal window
npx maestria install --all

plugin

Section titled “plugin”

Validate and stage portable Agent Plugins v1 directory packages, separate from the runtime platform registry: the result is a package for a compatible client’s own installer or directory loader.

Terminal window
maestria plugin validate <path> [--json]
maestria plugin install [source] [--destination <path>] [--json]

Commands

Section titled “Commands”
Invocation What happens
maestria plugin validate ./my-plugin Validates plugin.json, skills, and package path containment without writing files
maestria plugin validate ./my-plugin --json Emits the validation report as JSON
maestria plugin install Fetches @maestria/agent-plugins, validates it, and stages it under ~/.cache/maestria/agent-plugins/
maestria plugin install ./my-plugin Validates and stages a local package
maestria plugin install ./my-plugin --destination ./staged-plugin Stages a validated package at an explicit directory

The staged directory contains the root plugin.json and fixed skills/ layout. The command does not activate the package: installation scope, permissions, trust, and session behavior remain client-owned.

Sources and destinations

Section titled “Sources and destinations”

source accepts either a local Agent Plugin directory or an npm package specifier. It defaults to @maestria/agent-plugins:

Terminal window
npx maestria plugin install
Terminal window
npx maestria plugin install @maestria/[email protected]
Terminal window
npx maestria plugin install ./my-plugin

Without --destination, the package is staged under:

~/.cache/maestria/agent-plugins/<name>/<version>/

On systems that set XDG_CACHE_HOME, the path starts at $XDG_CACHE_HOME/maestria/ instead. <version> is URL-encoded, or unversioned when the manifest has no version.

Use --destination to choose another directory; the CLI refuses to overwrite an existing one.

Validation report

Section titled “Validation report”

plugin validate --json returns valid, name, version when present, root, skillNames, validationScope (portable-manifest-skills), errors, and warnings. plugin install --json returns the same validation fields plus destination and the original source.

The validator checks the closed plugin.json manifest, Agent Skills frontmatter and layout, and filesystem containment. maestria ships no MCP server, so a package that declares mcp.json is rejected. It does not execute package code or grant permissions.

update

Section titled “update”

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

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

Flags

Section titled “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

--version accepts semver (e.g., 0.5.0) or latest. An invalid value fails with Invalid version '2.0'. Use semver format (e.g., 0.5.0) or 'latest'.

Behavior

Section titled “Behavior”

Same logic as install, but for already installed platforms. Before-and-after version numbers are shown when available, including for a platform that is already current:

✓ OpenCode: 0.5.0 → 0.6.0
✓ Pi: 0.4.1 → 0.4.1

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

Terminal window
npx maestria update opencode --version 0.5.0

Exact version pinning is not available for claude-code, codex, or hermes; each returns a validation error if --version is passed. Claude Code and Codex update from the latest staged npm package, and Hermes updates from its Git-based plugin installation.

After each successful plugin update, update removes the create-pull-request and docs-update copies that earlier CLI versions installed through the skills CLI, using the CLI’s ownership record (skills.json in $MAESTRIA_CONFIG_DIR when set, otherwise $XDG_CONFIG_HOME/maestria/ or ~/.config/maestria/), and drops that record entry. Copies the record does not list, such as ones you installed yourself, are left alone. A copy whose installed path another agent still uses is kept and reported. When every installed plugin is already current, update still runs this cleanup for platforms that have a record entry and reports the plugin step as a no-op.

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 in one run, one platform at a time
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 pin-capable platforms to v0.5.0; Claude Code, Codex CLI, and Hermes return a version-pinning validation result

Version caching

Section titled “Version caching”

The CLI queries npm for the live latest version first. When npm is unreachable, it falls back to the last known version recorded in versions.json under the maestria cache directory ($XDG_CACHE_HOME/maestria/ when set, otherwise ~/.cache/maestria/):

{
  "@maestria/opencode": { "version": "0.6.2" }
}

The cache stores one version per package with no time-to-live; it is an offline fallback, not a freshness window. To clear it:

Terminal window
rm "${XDG_CACHE_HOME:-$HOME/.cache}/maestria/versions.json"

A successful update removes that package’s cached entry; the next check fetches live from npm.

Example

Section titled “Example”
Terminal window
npx maestria update --all

Exit Codes

Section titled “Exit Codes”
Code Meaning
0 Success
1 Validation or command error
3 Outdated (check: an installed plugin is behind the latest version)
130 User cancelled (interactive mode only)

The install and update commands detect non-interactive terminals and exit with code 1 with a clear error instead of prompting.

uninstall

Section titled “uninstall”

Remove maestria plugins from coding agent platforms.

Terminal window
maestria uninstall [platform] [--all] [--json] [--quiet] [--compact]

Flags

Section titled “Flags”
Flag Description
platform Positional arg - platform to uninstall. Omit for interactive picker.
--all, -a Uninstall all installed platforms
--json Output results as JSON
--quiet Suppress spinner animations
--compact Machine-friendly text output - one line per result

Behavior

Section titled “Behavior”
Invocation What happens
maestria uninstall Detects installed platforms, shows an interactive picker
maestria uninstall pi Uninstalls Pi only
maestria uninstall --all Uninstalls every platform where maestria is installed
maestria uninstall pi --json Uninstalls Pi, outputs JSON result

Like install and update, uninstall exits with code 1 in non-interactive terminals with no platform and no --all, showing a clear error instead of prompting. JSON output is an array of per-platform results with id, label, ok, and message fields. When the host uninstaller fails and maestria is not installed there, the platform reports Not installed and succeeds.

Uninstall also removes the skill copies earlier CLI versions installed for that platform, with the same ownership and shared-path rules as update. A platform with no skill record keeps any copy in place and reports a manual removal command; unknown skill IDs keep their history.

Pi uninstall leaves the shared @gotgenes/pi-subagents peer dependency in place unless it is removed separately.

OpenCode uninstall runs opencode plugin remove for each maestria entry in the global config and drops any maestria entry left in a V1 plugin array; project-level entries are left for you to remove. OpenCode install and update require OpenCode 2.0.28 or later, and replace a maestria entry in the V1 plugin array with one in plugins; on OpenCode V1 they fail and point to @maestria/[email protected]. A version change adds the new entry before removing old ones and keeps plugin options. An unpinned update of the lone @maestria/opencode entry runs opencode plugin update in place and waits up to a minute while OpenCode loads the directory’s plugins.

Example

Section titled “Example”
Terminal window
npx maestria uninstall pi

check

Section titled “check”

Check a maestria plugin’s installation status on one platform, or on every detected platform with --all.

Terminal window
maestria check <platform> [--json] [--quiet]
maestria check --all [--json] [--quiet]

<platform> is one of opencode, omp, pi, kimi-code, hermes, cursor, claude-code, codex. Pass a platform or --all; the command errors when neither is given or when both are combined: Cannot use --all with a specific platform. Choose one.

Flags

Section titled “Flags”
Flag Description
platform Positional arg - platform to check. Required unless --all is set.
--all, -a Check every detected platform
--json Output as JSON. Default: false - human-readable text is the default.
--quiet Suppress error messages on stderr. Does not suppress the result on stdout

Like doctor and plugin, check has no --compact flag; --quiet suppresses stderr error messages, not the stdout result.

Behavior

Section titled “Behavior”

check validates the platform, checks whether its CLI is on $PATH, then checks whether maestria is installed for it. Messages name the package the platform installs, shown below as <package>: @maestria/opencode for opencode, @maestria/pi for pi, and @maestria/agent-plugins for every other platform.

State Exit code Output
Unknown platform 1 Error message on stderr (suppressed with --quiet)
CLI tool not available 1 available: false, pluginInstalled: false, message: "CLI tool for <label> is not available on this machine"
CLI available, plugin not installed 1 available: true, pluginInstalled: false, message: "<package> is not installed for <label>", installedVersion
Installed and current 0 available: true, pluginInstalled: true, installedVersion, latestVersion
Installed and outdated 3 Same fields plus outdated: true when --json is set; text output prints the available update

With --all, the exit code is 1 when no detected platform is available, or when any available platform is not installed, 3 when all available detected platforms are installed and at least one is outdated, and 0 otherwise. A single-platform JSON result includes the platform field, and latestVersion only when it could be determined. With --all --json, each result is a status object with an id field instead of platform; latestVersion is always present and may be empty. JSON is written to stdout only with --json; otherwise the default text output is used.

Example

Section titled “Example”
Terminal window
npx maestria check opencode

configure

Section titled “configure”

Choose the model each maestria specialist uses, per platform.

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

platform is optional - one of opencode, codex, cursor, pi. Omit it for an interactive platform picker. The 4 specialists (adventurer, architect, builder, reviewer) can each use a different model. OMP discovers native root task profiles whose default model is inherited from the parent. This CLI does not manage OMP per-agent model settings.

For Codex, the command writes native custom-agent TOML files under $CODEX_HOME/agents/ (global, default ~/.codex/agents/) or .codex/agents/ (project). Existing files are edited surgically; new files use Codex’s name, description, developer_instructions, model, and read-only sandbox_mode fields where appropriate. For Cursor, global configuration edits the installed plugin’s native agent files and project configuration creates .cursor/agents/ overlays.

Interactive (TTY)

Section titled “Interactive (TTY)”
Terminal window
npx maestria configure opencode

Shows a group-multiselect of the 4 specialists, then a per-agent model picker pre-selected to the current model, with an Inherit (session model) option. The model list comes live from the platform (opencode models, Codex’s codex debug models, Cursor’s agent models/--list-models, or pi --list-models).

Non-interactive (CI)

Section titled “Non-interactive (CI)”
Terminal window
npx maestria configure opencode --global --quiet --set adventurer=<model-id>,reviewer=<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
  • Explicit model IDs come from the platform’s live list and are validated 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:

Terminal window
npx maestria configure <platform> --global --set architect=<model-id>

Flags

Section titled “Flags”
Flag Description
--global Configure the user-level config (see the table below)
--project Configure the project-level config (see the table below)
--set Set models non-interactively, e.g. architect=<model-id>
--json Output the resulting config as JSON
--quiet Suppress spinner output (recommended for CI)
--compact Minimal machine-friendly text output

JSON schema

Section titled “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

Section titled “Where the config is written”
Platform Global Project
opencode First existing opencode.jsonc or opencode.json in ~/.config/opencode/ (or $XDG_CONFIG_HOME/opencode/); defaults to opencode.jsonc First existing of .opencode/opencode.jsonc, .opencode/opencode.json, opencode.jsonc, opencode.json; defaults to .opencode/opencode.jsonc
codex $CODEX_HOME/agents/maestria-<name>.toml .codex/agents/maestria-<name>.toml
cursor ~/.cursor/plugins/local/maestria/agents/<name>.md .cursor/agents/<name>.md
pi ~/.pi/agent/agents/<name>.md .pi/agents/<name>.md

opencode writes the OpenCode V2 agents.<name>.model key, preserving comments and other keys, and removes a V1 agent.<name>.model for the same agent; pi sets the model: line in the agent’s frontmatter. For pi, a missing project agent file is created from the global one, and a missing global one from the agent bundled in the installed @maestria/pi package, which Pi otherwise deploys on its first session.

doctor

Section titled “doctor”

Report skill copies left over from earlier CLI versions, without changing anything (read-only).

Terminal window
maestria doctor [--json] [--quiet]

Flags

Section titled “Flags”
Flag Description
--json Output the diagnostics as JSON
--quiet Suppress spinner output (recommended for CI)

doctor has no --compact flag.

Behavior

Section titled “Behavior”

maestria packages bundle create-pull-request and docs-update, so doctor looks for separate copies of them. It reports the skill record path and whether it is present, then per platform: plugin state, the record entry, and the observed copies with their install paths. A copy the record lists is a legacy CLI install, and maestria update <platform> removes it. A copy the record does not list duplicates the bundled skill; doctor prints the skills CLI removal command and leaves the decision to you. A corrupt record fails loud with exit code 1 before any observation. A failed skills-list degrades into a per-platform note instead of aborting the run. A completed report exits with 0; use --json for machine-readable output.

Example

Section titled “Example”
Terminal window
npx maestria doctor