Skip to content
maestria

Getting Started

The maestria CLI runs on Node.js 22.12 or later. You do not need to install it: invoke it with npx or another package runner.

Quick Start

Section titled “Quick Start”

Check Your Platforms

Section titled “Check Your Platforms”
Terminal window
npx maestria@latest status

This checks which supported coding-agent CLIs are on your PATH and whether maestria is installed for each one. With no command, maestria defaults to status.

Install a Host Integration

Section titled “Install a Host Integration”

Install all detected platforms:

Terminal window
npx maestria@latest install --all

Or select one platform:

Terminal window
npx maestria@latest install opencode

Replace opencode with the platform ID you want. The command reference lists every supported ID.

Stage a Portable Agent Plugin

Section titled “Stage a Portable Agent Plugin”

Use the plugin namespace when the client supports Agent Plugins v1:

Terminal window
npx maestria@latest plugin install

The CLI validates the package, stages it, and prints its directory for the client’s own plugin installer or local-plugin setting. Portable discovery supplies the six skills (handoff, iteration-limits, create-pull-request, docs-update, diagnose, plan); full methodology uses the selected host’s native resources. The client controls activation, permissions, trust, and session behavior.

For a local package:

Terminal window
npx maestria@latest plugin validate /path/to/plugin
Terminal window
npx maestria@latest plugin install /path/to/plugin --destination ./staged-plugin

Update an Integration

Section titled “Update an Integration”

Update all installed integrations:

Terminal window
npx maestria@latest update --all

To update one platform or pin a version:

Terminal window
npx maestria@latest update opencode
Terminal window
npx maestria@latest update opencode --version <version>

Configure Specialist Models

Section titled “Configure Specialist Models”

Assign a model to a specialist when the platform supports per-agent configuration:

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

See the configure reference for supported platforms and reset syntax.

Skill Setup

Section titled “Skill Setup”

Check methodology skill state without changing anything:

Terminal window
npx maestria@latest doctor

This reports the skill record path, per-platform plugin state, recorded selections, and observed skills with next steps. See the doctor reference.

Prerequisites

Section titled “Prerequisites”
  • Node.js 22.12 or later
  • npm on PATH when plugin install fetches a package from npm
  • The target platform installed before maestria can detect or install its integration
  • An Agent Plugins v1 client for the portable package path

The CLI detects runtime platforms by their executable. Kimi Code is also detected from its plugin registry or config.toml, and Cursor from ~/.cursor only when neither cursor-agent nor agent is on PATH; a bare agent binary counts as Cursor only when its --version output names Cursor.

Platform Executable
OpenCode opencode
Pi pi
Oh My Pi omp
Kimi Code kimi
Hermes Agent hermes
Claude Code claude
Codex CLI codex
Cursor agent or cursor-agent

Next Steps

Section titled “Next Steps”