CLI

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.

InstalarCopiar link da seção

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

npm install --global https://mira.example.com/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:

npm install --global https://mira.example.com/downloads/sdk/mira-cli-0.1.0.tgz

EntrarCopiar link da seção

mira login --url https://mira.example.com

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:

printf '%s\n' "$SENHA" | mira login --url https://mira.example.com --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://mira.example.com --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.

ComandosCopiar link da seção

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.

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

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çõesCopiar link da seção

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:

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 para o fluxo.

Saída e códigos de saídaCopiar link da seção

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:

Uso em CICopiar link da seção

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

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

Uso por agentesCopiar link da seção

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:

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:

{
  "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 MCPCopiar link da seção

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 passosCopiar link da seção