Getting Started

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

Quick Start

Check what’s installed

npx maestria 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 npx maestria with no arguments - it defaults to status.

Install for a platform

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

npx maestria install

Install for all detected platforms:

npx maestria install --all

Install for a specific platform:

npx maestria install opencode
pnpx maestria@latest install pi
npx maestria install kimi-code

Update to the latest version

Interactive update:

npx maestria update

Update all:

npx maestria update --all

Update a specific platform:

npx maestria update opencode

Update to a specific version:

npx maestria update opencode --version 0.5.0

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:
  • OpenCode - opencode binary
  • Pi - pi binary
  • Kimi Code - kimi binary

JSON Output

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

npx maestria status --json

{
  "platforms": [
    {
      "id": "opencode",
      "label": "OpenCode",
      "available": true,
      "installed": true,
      "installedVersion": "0.6.0",
      "latestVersion": "0.6.2"
    }
  ]
}

npx maestria install --all --json

Compact Output

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

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

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

npx maestria install --all --quiet

Tip

Combine --quiet with --json for clean CI output: npx maestria status --json --quiet

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

The CLI catches invalid input early with clear error messages:

Unknown platform:

npx maestria update unknown-platform
# > Unknown platform 'unknown-platform'. Valid platforms: opencode, pi, kimi-code

Invalid version format:

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

Conflicting flags:

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

Version Caching

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

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

To force a fresh version check, delete the cache:

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

• Command Reference - full reference for all commands and flags