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

--compact (machine-friendly text) is supported on status, install, update, uninstall, configure, and setup. 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.

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, prime-agent, 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.2.1 latest=0.2.1
pi: not-available not-installed
kimi-code: available installed=0.1.0 latest=0.2.1
claude-code: available installed=0.2.1 latest=0.2.1
codex: available installed=0.2.0 latest=0.2.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] [--skills <csv>] [--exclude-skills <csv>] [--yes] [--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
--skills Methodology skills to activate (CSV, or none for no skills). Default: create-pull-request,docs-update. Known: create-pull-request, docs-update.
--exclude-skills Methodology skills to skip (CSV). Never touches independently installed copies.
--yes, -y Confirm skill selection non-interactively (required for non-TTY when it changes)
--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
maestria install opencode --skills docs-update Installs OpenCode with only the docs-update methodology skill
maestria install opencode --exclude-skills docs-update --yes Installs non-interactively, leaving an independently installed docs-update copy alone

Skill flags are validated before any change. An unmanaged skill already present for the target agent fails the run with --exclude-skills <skill> guidance; nothing is changed.

Platform identifiers

Section titled “Platform identifiers”
ID Platform Distribution
opencode OpenCode @maestria/opencode (npm)
pi Pi @maestria/pi (npm)
prime-agent Prime Agent @maestria/prime-agent (npm, native package manager)
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)
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 stages the published npm package under ~/.cache/maestria/ first. Claude Code configuration remains host-owned; Codex also receives maestria-managed native agent TOMLs under $CODEX_HOME/agents/.

Prime Agent uses its native package manager. maestria delegates installation, updates, and removal to prime-agent package install/update/remove npm:@maestria/prime-agent, reads registration state with prime-agent package list, and does not edit Prime configuration files directly.

Prime has two additional constraints:

  • Global scope only. maestria never scans, counts, or modifies project registrations. Each Prime command runs in a fresh temporary directory that exposes only user settings; the directory is removed afterward.
  • Latest version only. Prime’s package manager accepts no version specifier and skips pinned registrations during updates. maestria detects a pinned user-scope registration and reports an error instead of silently skipping it.

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, prime-agent, 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, optional MCP configuration, 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-plugin, 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-plugin:

Terminal window
npx maestria plugin install
Terminal window
npx maestria plugin install @maestria/agent-plugin@0.1.2
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.

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, 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, optional mcp.json, and filesystem containment. 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] [--skills <csv>] [--exclude-skills <csv>] [--yes] [--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
--skills Methodology skills to activate (CSV, or none for no skills). Default: recorded selection, else create-pull-request for legacy installs without a record. Known: create-pull-request, docs-update.
--exclude-skills Methodology skills to skip (CSV). Never touches independently installed copies.
--yes, -y Confirm skill selection non-interactively (required for non-TTY when it changes)
--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:

✔ 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:

Terminal window
npx maestria update opencode --version 0.5.0

Exact version pinning is not available for claude-code, codex, prime-agent, or hermes. The first three update from the latest staged npm package and return a validation error if --version is passed. Hermes ignores the version, warns, and updates from its git-based plugin installation.

When every installed plugin is already current, update still reconciles methodology skills and reports the plugin step as a no-op per platform. Legacy installs without a skill record infer only create-pull-request, never docs-update.

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 Prime Agent 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 ~/.cache/maestria/versions.json:

{
  "@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 ~/.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.

Uninstall removes only maestria-recorded methodology skills, and only when no other observed consumer shares the same installed path. A platform with no skill record keeps its companion in place with 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.

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, prime-agent, 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

Unlike every other command, 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 the @maestria/<platform> plugin is installed.

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: "@maestria/<platform> 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, omp. Omit it for an interactive platform picker. The 7 specialists (adventurer, architect, builder, diagnose, planner, reviewer, writer) can each use a different model.

For Codex, the command writes native custom-agent TOML files under ~/.codex/agents/ (global) 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 7 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, pi --list-models, or omp models --json).

Non-interactive (CI)

Section titled “Non-interactive (CI)”
Terminal window
npx 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
  • 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 planner=<model-id>

Flags

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

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 ~/.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.

doctor

Section titled “doctor”

Diagnose methodology skill setup without changing anything (read-only).

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

Flags

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

doctor has no --compact flag.

Behavior

Section titled “Behavior”

Reports the skill record path and whether it is present, then per platform: plugin state, recorded skill selection, observed skills with install paths, plus notes and next steps. A corrupt record fails loud before any observation. A failed skills-list degrades into a per-platform note instead of aborting the run. Exit code is always 0; use --json for machine-readable output.

Example

Section titled “Example”
Terminal window
npx maestria doctor

setup

Section titled “setup”

Coordinate optional project setup across ecosystem tools and skills. Read-only until the final confirmation: nothing runs before confirm.

Terminal window
maestria setup [--ecosystem <csv>] [--xtarterize-skills] [--skill-source <owner/repo:scope>] [--skills <csv>] [--maestria-skills <csv>] [--exclude-skills <csv>] [--cwd <dir>] [--yes] [--json] [--quiet] [--compact]

Flags

Section titled “Flags”
Flag Description
--ecosystem Ecosystem tools to check (CSV, or omit for interactive selection). Known: codegraph, agent-browser, opensrc. Detection only; never installs automatically.
--xtarterize-skills Apply project skills via xtarterize (agent/skills-install) for the target cwd
--skill-source Skill source to install via the skills CLI (repeatable or CSV). Format: <owner/repo:scope> with scope project or global. Skip by omitting.
--skills maestria methodology skills to activate (CSV, or none for no skills). Default: recorded selection, else create-pull-request, docs-update.
--maestria-skills Alias for --skills. --skills wins when both are set.
--exclude-skills maestria methodology skills to skip (CSV). Never touches independently installed copies.
--cwd Project directory the setup targets. Defaults to the current directory.
--yes, -y Confirm all setup actions non-interactively (required for non-TTY)
--json Output the per-action report as JSON
--quiet Suppress spinner and non-essential output
--compact Minimal machine-friendly text output

Behavior

Section titled “Behavior”

setup plans three independent groups and runs only the confirmed ones: ecosystem tool checks (detection plus manual steps, never automatic installs), xtarterize project skills for --cwd, and skill sources plus the maestria methodology selection. Project scope follows --cwd (or the current directory); re-run with the same args to resume. Skill flags are validated before any change, same as install.

Example

Section titled “Example”
Terminal window
npx maestria setup --ecosystem codegraph,opensrc --yes