# Maestro CLI

> The developer-side daemon for the Maestro AI orchestration platform.

`maestro` is a single binary that connects your machine to a Maestro
Studio workspace, watches your local git repos, and dispatches tasks to
AI coding agents — Claude Code, Codex, Gemini, Aider, or a manual
provider — while keeping every plan, comment, branch and pull request
in sync with the studio you point it at.

Public site & docs: **<https://maestro.makerman.co>**

---

## What it does

- **Auto-detect projects.** `cd` into any git checkout and run
  `maestro connect` — the CLI resolves the project from the git remote
  and registers a session with your studio.
- **Multi-project, multi-identity.** One daemon process can be attached
  to several repos and to several studios (work + personal) at the same
  time.
- **Run AI tasks locally.** Tasks dispatched from the studio are picked
  up by the CLI, executed inside the chosen provider (Claude Code,
  Codex, Gemini, Aider, …), and the resulting branches, PRs and review
  comments are streamed back live.
- **Bring-your-own-keys.** Provider credentials live in your OS keyring;
  the studio never sees them.
- **Operator steering.** Type a `maestro …` line into the TUI input
  while a run is happening to inject guidance into the live provider
  session and persist it for follow-up turns.

---

## Install

The CLI ships standalone binaries for macOS (Apple Silicon), Linux
(x86_64 + arm64) and Windows (x86_64). Pick whichever channel suits
the host:

```bash
# macOS · Linux — auto-detects platform + drops binary on PATH
curl -fsSL https://maestro.makerman.co/install.sh | sh

# Windows PowerShell
irm https://maestro.makerman.co/install.ps1 | iex

# Homebrew tap (macOS · Linuxbrew)
brew tap maestro-dev/homebrew https://gitlab.com/maestro-dev/homebrew.git
brew install maestro-dev/homebrew/maestro

# npm — wraps the matching binary, downloaded at install time
npm install -g maestro-makerman

# pip — wraps the matching binary, fetched on first run
pip install maestro-makerman

# Cargo (build from source — needs a Rust toolchain)
cargo install --git https://gitlab.com/maestro-dev/maestro maestro
```

Direct archives + SHA-256 sums: <https://maestro.makerman.co/download>.

### Verify

```bash
maestro --version
```

---

## Quickstart

```bash
# 1. Get an invite token from your studio (Settings → Tokens) and
#    authenticate the CLI. The bearer is stored in your OS keyring.
maestro auth <invite-token>

# 2. Inside any local git checkout, register the working tree with
#    the studio. The project is resolved from the git remote.
cd ~/code/your-project
maestro connect

# 3. (optional) Run a repo-wide analysis so the studio has up-to-date
#    context files and a directory map.
maestro analyze
```

That is enough to receive tasks dispatched from the studio. Leave the
TUI running while you work — completed tasks open pull requests against
the configured branch automatically.

---

## Common commands

| Command | What it does |
|---------|--------------|
| `maestro auth <token>` | Store the studio bearer in the OS keyring |
| `maestro init` | Drop a `.maestro.json` scaffold into the current repo |
| `maestro connect` | Register the cwd as a session with the studio |
| `maestro connect --no-tui` | Headless mode (useful for CI / workers) |
| `maestro analyze` | Refresh the studio's view of the repo |
| `maestro team --dev 2 --review 1` | Spawn a worker team alongside the lead session |
| `maestro hooks install` | Register Claude Code hooks (auto-connect, disconnect) |
| `maestro clear-steering` | Reset persisted operator-steering directives |
| `maestro --help` | Full command surface |

---

## Configuration

| File | Purpose |
|------|---------|
| `~/.maestro/credentials.toml` | Bearer + studio base URL (written by `maestro auth`) |
| `~/.maestro/projects.toml` | Local-path ↔ project uuid map |
| `.maestro.json` (per repo) | Shared project defaults (commit to git) |
| `.maestro/settings.local.json` | Machine-local overrides (gitignored) |

Override the studio URL with `MAESTRO_STUDIO_URL=https://…` or point at
a custom manifest with `MAESTRO_MANIFEST_URL=…` when installing.

---

## Updates

The CLI does not auto-update. To upgrade:

```bash
# Re-run the installer of your choice — the manifest always serves the
# latest stable release:
curl -fsSL https://maestro.makerman.co/install.sh | sh
# or
brew upgrade maestro-dev/homebrew/maestro
# or
npm  install -g maestro-makerman@latest
# or
pip  install -U maestro-makerman
```

---

## Reporting issues

Issues and merge requests are welcome at
<https://gitlab.com/eralas/maestro>. When filing a bug please include:

- `maestro --version`
- OS + architecture
- A short reproducer or the relevant TUI log (`~/.maestro/sessions/`)

---

## License

[Apache License 2.0](LICENSE). Third-party notices in
[CREDITS.md](CREDITS.md).
