# CLI

URL: /desenvolvedores/cli

Use o Mira pelo terminal, em scripts e em agentes de IA.

A CLI `mira` chama a API REST do Mira pelo terminal, para consultas, scripts e agentes de IA que leem e atualizam reports sem navegador. Ela faz tudo o que o dono do token pode fazer na API. Para agentes com permissões limitadas por token e por projeto, use o [MCP](/desenvolvedores/mcp).

## Instalar [#instalar]

A CLI precisa do Node 24 ou mais novo. O Mira serve o pacote sem login:

```bash
npm install --global https://app.miraqa.org/downloads/mira-cli.tgz
mira --version
```

`/downloads/mira-cli.tgz` redireciona para a versão mais recente. Para atualizar, rode o mesmo comando. Para fixar uma versão, instale pela URL dela:

```bash
npm install --global https://app.miraqa.org/downloads/sdk/mira-cli-0.1.0.tgz
```

## Entrar [#entrar]

```bash
mira login --url https://app.miraqa.org
```

A CLI pede email e senha no terminal, sem mostrar a senha, e cria um token pessoal chamado `mira-cli@<hostname>`. Fora de um terminal interativo, a senha vem do stdin, para não ficar no histórico do shell:

```bash
printf '%s\n' "$SENHA" | mira login --url https://app.miraqa.org --email pessoa@empresa.com
```

Quem entrou só pelo Google não tem senha: defina uma em **Definir senha**, no menu do perfil, ou use um token pessoal. Com um token pessoal `mira_pat_` que você já criou, use `mira login --url https://app.miraqa.org --token mira_pat_...`. Tokens de agente do MCP não funcionam na CLI.

A credencial fica em `~/.config/mira/config.json` ou em `$XDG_CONFIG_HOME/mira/config.json`, com modo 0600. As variáveis `MIRA_URL` e `MIRA_TOKEN` têm precedência sobre o arquivo, o que serve para CI e containers.

- `mira whoami` mostra a URL e o usuário do token em uso.
- `mira logout` revoga o token no Mira e apaga o arquivo.

## Comandos [#comandos]

Cada rota da API vira um comando, com o nome da rota em kebab-case: `list-projects`, `list-reports`, `get-report`, `update-report`, `create-comment`, `upload-attachment`. Rotas que não aceitam token pessoal ficam de fora, como as do widget, da ingestão de erros e da API de consulta.

Para descobrir os comandos:

- `mira commands` lista os comandos, e `mira commands --json` devolve a lista em JSON.
- `mira describe <comando>` mostra as flags e o JSON Schema da entrada e da saída.
- `mira <comando> --help` resume as flags.

Os campos de nível superior viram flags: `reportId` vira `--report-id`. Um campo com o nome de uma opção da CLI ganha o prefixo da parte, como o texto do comentário, que vira `--body-body`.

| Opção | Efeito |
| --- | --- |
| `--body <json\|@arquivo\|->` | Body inteiro em JSON, de um arquivo ou do stdin. As flags de campo sobrescrevem o JSON |
| `--file <caminho>` | Arquivo de um campo de upload, como o anexo de `upload-attachment` |
| `--output <arquivo>` | Grava a resposta binária, como o conteúdo de um anexo |
| `--all` | Segue o cursor das listagens e junta os itens, até `--max-items` (padrão 1000) |
| `--dry-run` | Mostra o request sem enviar |

A CLI valida a entrada com o schema da rota antes de enviar.

```bash
mira list-reports --project-id <id> --status triaged --all
mira get-report --report-id <id>
mira update-report --report-id <id> --status in_progress --assignee-id <user id>
mira create-comment --report-id <id> --body-body "Corrigido no PR owner/repo#42"
mira upload-attachment --report-id <id> --id "$(uuidgen | tr A-Z a-z)" --kind screenshot --name tela.png --file tela.png
mira get-attachment-content --attachment-id <id> --output tela.png
```

## Migrações [#migrações]

Um admin conduz as migrações entre instâncias pela CLI, com o token pessoal de um admin. São 12 comandos de administração, gerados das rotas:

| Comando | Faz |
| --- | --- |
| `create-migration-token`, `list-migration-tokens`, `revoke-migration-token` | Emite, lista e revoga tokens de migração |
| `preview-migration` | Lê a outra instância e devolve os projetos e as contagens |
| `create-migration` | Começa uma migração, trazendo ou enviando |
| `list-migrations`, `get-migration` | Lista as migrações e mostra o detalhe |
| `list-migration-failures`, `list-migration-notices` | Lista as falhas e os avisos de uma migração |
| `resume-migration`, `retry-migration-failures`, `cancel-migration` | Retoma, refaz as falhas e cancela |

As rotas que a outra instância chama com o token `mira_mig_` (exportação e importação) não viram comandos. Veja [Migrações](/administrar/migracoes) para o fluxo.

## Saída e códigos de saída [#saída-e-códigos-de-saída]

O sucesso sai em JSON no stdout. O erro sai no stderr, como `{ "error": { "code", "message", "details" } }`, com um código de saída por tipo:

| Código | Erro |
| --- | --- |
| 0 | Sucesso |
| 1 | Erro genérico, inclusive falha de rede |
| 2 | Entrada inválida (`validation_failed`) |
| 3 | Sem credencial, token recusado ou sem permissão (`unauthorized`, `forbidden`) |
| 4 | Não encontrado (`not_found`) |
| 5 | Conflito (`conflict`) |

## Uso em CI [#uso-em-ci]

Defina `MIRA_URL` e `MIRA_TOKEN` no ambiente do job e chame os comandos direto, sem `mira login`:

```yaml
- run: npm install --global https://app.miraqa.org/downloads/mira-cli.tgz
- run: mira list-reports --project-id "$MIRA_PROJECT_ID" --status new --all
  env:
    MIRA_URL: https://app.miraqa.org
    MIRA_TOKEN: ${{ secrets.MIRA_TOKEN }}
```

## Uso por agentes [#uso-por-agentes]

`mira agent-guide` imprime, em Markdown, o fluxo para implementar um report e as regras que o agente segue: um report por vez, nunca marcar `resolved` por conta própria e alterar o report só a pedido da pessoa. É o mesmo fluxo do prompt `implement_report` do MCP. Uma linha no `AGENTS.md` ou no `CLAUDE.md` do repositório da app basta para o agente encontrar o guia:

```md
Reports do Mira: rode `mira agent-guide` antes de pegar um report.
```

A CLI não pede confirmação. A trava fica nas permissões do agente sobre os comandos de shell: libere as leituras e deixe as escritas pedirem aprovação. No Claude Code, por exemplo, em `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "Bash(mira list-projects:*)",
      "Bash(mira list-reports:*)",
      "Bash(mira get-report:*)",
      "Bash(mira list-comments:*)",
      "Bash(mira get-attachment-content:*)"
    ]
  }
}
```

Toda escrita pela CLI grava a origem `cli` na atividade do report, só para auditoria. O comentário aparece como da pessoa, sem o selo "via agente".

## CLI ou MCP [#cli-ou-mcp]

| | CLI | MCP |
| --- | --- | --- |
| Credencial | Token pessoal, o mesmo da extensão | Token de agente, só no `/mcp` |
| Alcance | Tudo o que o dono do token faz na API | Leitura de reports, comentar e alterar, dentro do teto do projeto |
| Evidência | Qualquer anexo que o dono vê | Só os tipos liberados no token e no teto. Nunca replay |
| Confirmação | Permissões de shell do agente | O cliente MCP pede a cada `update_report` |
| Origem na atividade | `cli` | `mcp`, com o rótulo **agente** |

Prefira o MCP quando o projeto testa com dados reais ou quando o agente não deve ver tudo o que a pessoa vê. Use a CLI em scripts, em agentes sem suporte a MCP e em operações fora das tools do MCP.

## Próximos passos [#próximos-passos]

<Cards>
<Card href="/desenvolvedores/mcp" title="MCP" description="Dê ao agente só o acesso de que ele precisa." />
<Card href="/desenvolvedores/api" title="API externa" description="Consulte reports por HTTP, sem a CLI." />
<Card href="/desenvolvedores/tokens" title="Tokens" description="Crie e revogue o token pessoal da CLI." />
</Cards>