Skip to content
Maestria

Getting Started

maestria runs anywhere Node.js 22+ is available. No install required - use npx to run it directly from npm.

Quick Start

Section titled “Quick Start”

Check what’s installed

Section titled “Check what’s installed”
Terminal window
npx maestria@latest status

This detects which coding agent platforms are available on your machine and shows the install status for each:

  Maestria Status
  ─────────────────────────────────────
  OpenCode
    Available:  ✓
    Installed:  ✓ v0.6.0
    Latest:     0.6.2
  Pi
    Available:  ✓
    Installed:  - not installed
    Latest:     0.4.1
  Kimi Code
    Available:  ✗
    Installed:  - not installed
    Latest:     unknown

Run

Terminal window
npx maestria@latest
with no arguments - it defaults to status.

Install for a platform

Section titled “Install for a platform”

Interactive install (pick from a list of detected platforms):

Terminal window
npx maestria@latest install

Install for all detected platforms:

Terminal window
npx maestria@latest install --all

Install for a specific platform:

Terminal window
npx maestria@latest install opencode
Terminal window
npx maestria@latest install pi
Terminal window
npx maestria@latest install kimi-code

Update to the latest version

Section titled “Update to the latest version”

Interactive update:

Terminal window
npx maestria@latest update

Update all:

Terminal window
npx maestria@latest update --all

Update a specific platform:

Terminal window
npx maestria@latest update opencode

Update to a specific version:

Terminal window
npx maestria@latest update opencode --version 0.5.0

Configure per-agent models

Section titled “Configure per-agent models”

Give each maestria specialist its own model. Interactively:

Terminal window
npx maestria@latest configure opencode

Or non-interactively for CI:

Terminal window
npx maestria@latest configure pi --global --quiet --set builder=opencode-go/deepseek-v4-flash

Use an empty value to reset an agent to inherit the session model:

Terminal window
npx maestria@latest configure opencode --set reviewer=

Per-agent models are supported on opencode, pi, and omp. See the command reference for details.

Prerequisites

Section titled “Prerequisites”
  • Node.js 22+ - required for the bundled .mjs distribution
  • Platform CLI tool - the CLI detects platforms by checking for their binary on $PATH. The platform must be installed before maestria can be installed for it:

JSON Output

Section titled “JSON Output”

All commands accept --json for machine-readable output. Useful for CI scripts, dashboards, or IDE integrations:

Terminal window
npx maestria@latest status --json
 
{
  "platforms": [
    {
      "id": "opencode",
      "label": "OpenCode",
      "available": true,
      "installed": true,
      "installedVersion": "0.6.0",
      "latestVersion": "0.6.2"
    }
  ]
}
Terminal window
npx maestria@latest install --all --json

Compact Output

Section titled “Compact Output”

Use --compact for minimal machine-friendly text output suitable for AI agents and token-sensitive environments:

Terminal window
npx maestria@latest status --compact
 
opencode: available installed=0.2.1 latest=0.2.1
pi: not-available not-installed

Compact output works on install and update too, showing one line per platform result:

opencode: installed 0.2.1

The compact flag implies --quiet (no spinner animations).

Quiet Mode

Section titled “Quiet Mode”

Use --quiet to suppress spinner animations. Commands still print final output:

Terminal window
npx maestria@latest install --all --quiet

Exit Codes

Section titled “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 (e.g., CI pipelines) and exit with code 1 showing a clear error message instead of attempting an interactive prompt.

Run any command with --help to see in-terminal examples, exit code documentation, and a TIP FOR AI AGENTS section with usage guidance for automated pipelines.

Input Validation

Section titled “Input Validation”

The CLI catches invalid input early with clear error messages:

Unknown platform:

Terminal window
npx maestria update unknown-platform
# > Unknown platform 'unknown-platform'. Valid platforms: opencode, omp, pi, kimi-code, hermes, cursor

Invalid version format:

Terminal window
npx maestria update opencode --version 2.0
# > Invalid version '2.0'. Use semver format (e.g., 0.5.0) or 'latest'.

Conflicting flags:

Terminal window
npx maestria install opencode --all
# > Cannot use --all with a specific platform. Choose one.

Version Caching

Section titled “Version Caching”

The CLI caches version lookups from npm for 1 hour in ~/.cache/maestria/versions.json:

Terminal window
cat ~/.cache/maestria/versions.json
# {"@maestria/opencode":{"version":"0.6.2","cachedAt":1719600000000}}

To force a fresh version check, delete the cache:

Terminal window
rm ~/.cache/maestria/versions.json

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

Next Steps

Section titled “Next Steps”