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 Runtime Integration

Section titled “Install a Runtime 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. 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.

Diagnose Skill Setup

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

Coordinate Project Setup

Section titled “Coordinate Project Setup”

Check ecosystem tools and reconcile skills for a project:

Terminal window
npx maestria@latest setup --ecosystem codegraph,opensrc --yes

Setup is read-only until the final confirmation. Ecosystem tools are detection plus manual steps only; the CLI never installs them automatically. Use --skills and --exclude-skills to select the create-pull-request and docs-update methodology skills. See the setup 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:

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

Next Steps

Section titled “Next Steps”