# Command Reference

## Global Flags

These flags work on every command:

| Flag        | Description                                          |
| ----------- | ---------------------------------------------------- |
| `--json`    | Output results as JSON instead of formatted text     |
| `--quiet`   | Suppress spinner animations                          |
| `--compact` | Machine-friendly text output - one line per platform |

Running `maestria` with no arguments is equivalent to `maestria status`.

---

## `status`

Show what's installed and version information for all platforms.

```bash
maestria status [--json] [--quiet] [--compact]
```

Detects which coding agent CLIs are available on `$PATH`, checks whether maestria is installed for each, and reports the installed and latest versions. Platform detection runs in parallel.

### Flags

| Flag        | Description                                   |
| ----------- | --------------------------------------------- |
| `--json`    | Output as JSON (see schema below)             |
| `--quiet`   | Suppress non-essential output                 |
| `--compact` | Machine-friendly text - one line per platform |

### JSON schema

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

Each platform object:

| Field              | Type    | Description                                         |
| ------------------ | ------- | --------------------------------------------------- |
| `id`               | string  | Platform identifier (`opencode`, `pi`, `kimi-code`) |
| `label`            | string  | Human-readable name                                 |
| `available`        | boolean | CLI tool detected on `$PATH`                        |
| `installed`        | boolean | Maestria is installed for this platform             |
| `installedVersion` | string  | Version string from the installed package           |
| `latestVersion`    | string  | Latest version available on npm                     |

### Compact output

With `--compact`, status outputs one line per platform with no colors or decorative formatting:

```
opencode: available installed=0.2.1 latest=0.2.1
pi: not-available not-installed
kimi-code: available installed=0.1.0 latest=0.2.1
```

Ideal for AI agents and token-sensitive environments. Implies `--quiet` (no spinner animations).

### Example

```bash
npx maestria status
```

---

## `install`

Install maestria plugins for one or more coding agent platforms.

```bash
maestria install [platform] [--all] [--json] [--quiet] [--compact]
```

### Flags

| Flag          | Description                                                                                                            |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `platform`    | Positional arg - platform to install. Comma-separated for multiple (e.g., `opencode,pi`). Omit for interactive picker. |
| `--all`, `-a` | Install for all detected platforms                                                                                     |
| `--json`      | Output results as JSON                                                                                                 |
| `--quiet`     | Suppress spinner animations                                                                                            |
| `--compact`   | Machine-friendly text output - one line per result                                                                     |

### Behavior

| Invocation                         | What happens                                                            |
| ---------------------------------- | ----------------------------------------------------------------------- |
| `maestria install`                 | Detects platforms, shows an interactive multiselect picker (checkboxes) |
| `maestria install opencode`        | Installs for OpenCode only                                              |
| `maestria install opencode,pi`     | Installs for OpenCode and Pi simultaneously                             |
| `maestria install --all`           | Installs for every detected platform that lacks maestria                |
| `maestria install opencode --json` | Installs OpenCode, outputs JSON result                                  |

### Platform identifiers

| ID          | Platform  | npm package           |
| ----------- | --------- | --------------------- |
| `opencode`  | OpenCode  | `@maestria/opencode`  |
| `pi`        | Pi        | `@maestria/pi`        |
| `kimi-code` | Kimi Code | `@maestria/kimi-code` |

### Error handling

**Input validation** - the CLI catches invalid arguments before any platform work begins:

| Scenario                    | Error message                                                         |
| --------------------------- | --------------------------------------------------------------------- |
| Unknown platform ID         | `Unknown platform 'cursor'. Valid platforms: opencode, pi, kimi-code` |
| Invalid version format      | `Invalid version '2.0'. Use semver format (e.g., 0.5.0) or 'latest'.` |
| `--all` with a platform arg | `Cannot use --all with a specific platform. Choose one.`              |

**Runtime errors** - if a platform command fails (e.g., network error, missing binary), the CLI catches it and reports the failure per-platform rather than aborting the entire batch:

```
✔ OpenCode: Installed
✗ Pi: Command failed: pi install npm:@maestria/pi
```

### Example

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

---

## `update`

Update maestria plugins to the latest (or specified) version.

```bash
maestria update [platform] [--version <semver>] [--all] [--json] [--quiet] [--compact]
```

### Flags

| Flag              | Description                                                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| `platform`        | Positional arg - platform to update. Comma-separated for multiple (e.g., `opencode,pi`). Omit for interactive picker. |
| `--version`, `-V` | Specific version to install (e.g., `0.5.0`). Defaults to latest.                                                      |
| `--all`, `-a`     | Update all installed platforms                                                                                        |
| `--json`          | Output results as JSON                                                                                                |
| `--quiet`         | Suppress spinner animations                                                                                           |
| `--compact`       | Machine-friendly text output - one line per result                                                                    |

### Behavior

Same logic as `install` but targets platforms where maestria is already installed. Before-and-after version numbers are shown when available:

```
✔ OpenCode: Updated: v0.5.0 → v0.6.0
✔ Pi: Already up to date (v0.4.1)
```

Use `--version` to pin a specific version instead of the latest:

```bash
maestria update opencode --version 0.5.0
```

| Invocation                                 | What happens                                                                                                                           |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `maestria update`                          | Detects installed platforms, shows interactive grouped multiselect picker with "All platforms" toggle header and `a` key to toggle all |
| `maestria update opencode`                 | Updates OpenCode to the latest version                                                                                                 |
| `maestria update opencode,pi`              | Updates OpenCode and Pi simultaneously                                                                                                 |
| `maestria update opencode --version 0.5.0` | Updates OpenCode to v0.5.0 specifically                                                                                                |
| `maestria update --all`                    | Updates all installed platforms to latest                                                                                              |
| `maestria update --all --version 0.5.0`    | Updates all installed platforms to v0.5.0                                                                                              |

### Version caching

The CLI caches `npm view <package> version` results for 1 hour in `~/.cache/maestria/versions.json`:

```json
{
  "@maestria/opencode": { "version": "0.6.2", "cachedAt": 1719600000000 }
}
```

To force a fresh version check before running a command:

```bash
rm ~/.cache/maestria/versions.json
npx maestria status
```

The cache is automatically invalidated after a successful update, so `maestria status` always shows the correct latest version after an upgrade.

### Example

```bash
npx maestria update --all
```
**Tip:** Use `maestria status` before `maestria update --all` to see which platforms have updates
  available.
**Tip:** Run `maestria <command> --help` for in-terminal examples and exit code documentation,
  including a TIP FOR AI AGENTS section with usage guidance for automated environments.

### 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 and exit with code `1`
showing a clear error message instead of attempting an interactive prompt.