# 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

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

```bash
npx maestria install
```

**Install for all detected platforms:**

```bash
npx maestria install --all
```

**Install for a specific platform:**

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

### Update to the latest version

**Interactive update:**

```bash
npx maestria update
```

**Update all:**

```bash
npx maestria update --all
```

**Update a specific platform:**

```bash
npx maestria update opencode
```

**Update to a specific version:**

```bash
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](https://opencode.ai) - `opencode` binary
  - [Pi](https://pi.ai) - `pi` binary
  - [Kimi Code](https://kimi.ai) - `kimi` binary

## JSON Output

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

```bash
npx maestria status --json
```

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

```bash
npx maestria install --all --json
```

## Compact Output

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

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

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

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

**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