# 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

<AllPackageManagers type="dlx" pkg="maestria@latest" args="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 <AllPackageManagers type="dlx" pkg="maestria@latest" /> with no arguments - it defaults to `status`.

### Install for a platform

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

<AllPackageManagers type="dlx" pkg="maestria@latest" args="install" />

**Install for all detected platforms:**

<AllPackageManagers type="dlx" pkg="maestria@latest" args="install --all" />

**Install for a specific platform:**

<AllPackageManagers type="dlx" pkg="maestria@latest" args="install opencode" />
<AllPackageManagers type="dlx" pkg="maestria@latest" args="install pi" />
<AllPackageManagers type="dlx" pkg="maestria@latest" args="install kimi-code" />

### Update to the latest version

**Interactive update:**

<AllPackageManagers type="dlx" pkg="maestria@latest" args="update" />

**Update all:**

<AllPackageManagers type="dlx" pkg="maestria@latest" args="update --all" />

**Update a specific platform:**

<AllPackageManagers type="dlx" pkg="maestria@latest" args="update opencode" />

**Update to a specific version:**

<AllPackageManagers type="dlx" pkg="maestria@latest" args="update opencode --version 0.5.0" />

### Configure per-agent models

Give each maestria specialist its own model. Interactively:

<AllPackageManagers type="dlx" pkg="maestria@latest" args="configure opencode" />

Or non-interactively for CI:

<AllPackageManagers
  type="dlx"
  pkg="maestria@latest"
  args="configure pi --global --quiet --set builder=opencode-go/deepseek-v4-flash"
/>

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

<AllPackageManagers type="dlx" pkg="maestria@latest" args="configure opencode --set reviewer=" />

Per-agent models are supported on opencode, pi, and omp. See the [command reference](/cli/commands/#configure) for details.

## 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](https://opencode.ai) - `opencode` binary
  - [Pi](https://pi.ai) - `pi` binary
  - [Kimi Code](https://kimi.ai) - `kimi` binary
  - [Hermes Agent](https://hermes-agent.nousresearch.com) - `hermes` binary

## JSON Output

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

<AllPackageManagers type="dlx" pkg="maestria@latest" args="status --json" />

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

<AllPackageManagers type="dlx" pkg="maestria@latest" args="install --all --json" />

## Compact Output

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

<AllPackageManagers type="dlx" pkg="maestria@latest" args="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:

<AllPackageManagers type="dlx" pkg="maestria@latest" args="install --all --quiet" />

**Tip:** Combine `--quiet` with `--json` for clean CI output:{' '}
  <AllPackageManagers type="dlx" pkg="maestria@latest" args="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:**

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

**Invalid version format:**

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

**Conflicting flags:**

```bash
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`:

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

To force a fresh version check, delete the cache:

```bash
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](/cli/commands/) - full reference for all commands and flags