Reqlivo docs

Uso

Este guia cobre o fluxo diário da CLI e da interface desktop do Reqlivo. Para o formato dos arquivos, consulte formato.md.

Instalação e build

cargo build --release
./target/release/reqlivo --help

Durante o desenvolvimento, substitua reqlivo por cargo run --.

Criar uma coleção

reqlivo --collection minha-api init --name "Minha API"

O comando cria opencollection.yml, README.md, .gitignore e o ambiente dev com baseUrl=http://127.0.0.1:18080. O diretório de destino deve estar vazio ou não existir.

Abra a interface:

npm ci
npm run desktop:dev -- -- --collection minha-api

Consulte desktop.md para pré-requisitos e instaladores. Abrir coleção seleciona a pasta pelo diálogo nativo. Sem argumentos, o app reabre a última pasta selecionada ou cria uma coleção nos dados locais do aplicativo. Não há servidor da interface nem comando serve.

Interface desktop

Árvore e editor

  1. Use a árvore para abrir uma pasta ou requisição.
  2. Edite nome, método, URL e tags.
  3. Percorra as abas Params, Headers, Corpo, Auth, Scripts e Testes.
  4. Use Salvar (Ctrl/Cmd+S) para gravar no arquivo.
  5. Use Enviar (Ctrl/Cmd+Enter) para executar o rascunho atual, mesmo antes de salvar.

A árvore é navegável por teclado. ↑/↓ percorre itens, Home/End vai ao início/fim, ←/→ recolhe/expande pastas e Enter/Espaço abre o item focado. O filtro da árvore fica em Ctrl/Cmd+K.

Rascunhos, alterações externas e conflitos

Lixeira

O botão Lixeira lista requisições e pastas vazias excluídas, com nome, tipo, origem e data. Selecione uma entrada e escolha pasta/nome de destino; o conteúdo original e o ID são preservados. Destino ocupado, ID já ativo, hash divergente ou entrada legada ilegível geram erro explícito, sem sobrescrever arquivos. Pastas não vazias continuam exigindo que os itens sejam movidos primeiro.

Migração

Se a coleção usa um schemaVersion anterior, a abertura não migra sozinha. O diálogo mostra schema atual/destino, arquivos, motivo, plano, revisão, backup e operações anteriores. Cancelar mantém tudo intacto; Aplicar exige confirmação explícita e grava backup verificável em .reqlivo/backups/. Depois de um rollback, a coleção entra em recuperação: leituras continuam disponíveis, escritas e execuções ficam bloqueadas até uma nova inspeção e confirmação.

Resposta

O painel mostra:

Durante o envio interativo, os headers aparecem assim que a resposta começa e o corpo textual é exibido em blocos. O estado recebendo mostra o total acumulado, o content-type, redirecionamento e truncamento. A prévia é identificada como parcial; testes, asserções e logs ficam pendentes até a conclusão. Ao terminar, a resposta final bufferizada substitui a prévia e alimenta o restante da interface.

O UTF-8 é decodificado em fluxo, então caracteres divididos entre blocos não aparecem como �. Corpos binários mostram apenas o indicador de recebimento; a prévia base64 é montada no fim. O runner e a CLI não exibem progresso incremental.

Respostas maiores que max_response_bytes são truncadas com aviso. Conteúdo binário é exibido como prévia/base64 limitada.

Runner

  1. Abra Runner (Alt+R).
  2. Escolha ambiente, tags, pasta ou “somente a requisição atual”.
  3. Inicie e acompanhe o relatório.
  4. Cancele enquanto a execução estiver em andamento.

O resultado diferencia:

Status Significado
executed houve resposta HTTP, mas não havia teste/asserção.
passed havia testes/asserções e todos passaram.
failed algum teste/asserção falhou.
error falha de preparação, rede, script ou transporte.
cancelled cancelado pelo usuário.
skipped não selecionado pelo filtro.

Ambientes e segredos

Abra Ambientes no topo. É possível:

A UI mostra apenas definido/não definido para a referência. O valor real nunca é enviado à WebView.

Configurações

O botão de engrenagem abre as configurações da coleção: timeout, timeout de script, redirects, limite de resposta, ambiente padrão, modo offline e permissão para variáveis do processo.

O botão Validar executa a mesma verificação da CLI (reqlivo validate) sem enviar requisições e mostra problemas, avisos e arquivos não suportados.

CLI

Listar e validar

reqlivo --collection minha-api requests
reqlivo --collection minha-api validate
reqlivo --collection minha-api validate --json

validate verifica método/URL, JSON/XML inválidos, herança/ciclos de ambientes, referências de segredo e arquivos não suportados. Também há avisos de migração e compatibilidade.

Executar

reqlivo --collection minha-api run --env dev
reqlivo --collection minha-api run --tag smoke
reqlivo --collection minha-api run --request req_... --json
reqlivo --collection minha-api run --folder fld_... --output /tmp/relatorio.json

--request e --tag são listas e podem ser repetidos (--tag smoke --tag demo); --folder aceita um ID. O ambiente padrão é usado quando --env é omitido.

O relatório humano mostra status, tempo e falhas. O JSON inclui summary, requests, tests, logs, response, auth, effective_variables e deterministic_hash.

Enviar uma requisição

reqlivo --collection minha-api send req_... --env dev
reqlivo --collection minha-api send req_... --json

send usa o ambiente padrão quando --env não é informado. Em caso de falha, retorna código 1.

Migrar a coleção

reqlivo --collection minha-api migration inspect
reqlivo --collection minha-api migration inspect --json
reqlivo --collection minha-api migration apply mig_... --revision <revisao>
reqlivo --collection minha-api migration rollback mig_... --revision <revisao>
reqlivo --collection minha-api migration list

inspect não altera arquivos: lista schema, motivos, arquivos e o plano preparado. apply exige o ID do plano e, quando informada, confere a revisão; cria backup completo antes da primeira escrita e valida o resultado. rollback restaura os bytes anteriores somente se nenhum arquivo tocado foi editado depois da migração; arquivos independentes permanecem intactos. Comandos comuns que encontram migração pendente retornam erro acionável e não migram silenciosamente. Após rollback, validate/run continuam bloqueados até nova inspeção e aplicação.

Importar

# cURL inline
reqlivo --collection minha-api import curl \
  "curl -X POST http://127.0.0.1:18080/echo -H 'X-Test: 1' -d '{\"a\":1}'"

# arquivo ou diretório
reqlivo --collection minha-api import curl ./requisicao.sh
reqlivo --collection minha-api import postman ./collection.json
reqlivo --collection minha-api import opencollection ./colecao-opencollection

Exportar

reqlivo --collection minha-api export curl req_... --output /tmp/echo.sh
reqlivo --collection minha-api export postman --output /tmp/postman.json
reqlivo --collection minha-api export opencollection --output /tmp/col.yml
reqlivo --collection minha-api export project --output /tmp/minha-api-copia

Exportações padrão omitem:

Templates (``) e referências de segredo são preservados. No cURL, substitua os templates pelo valor do ambiente antes de executar ou use a UI/CLI para enviar a requisição. O relatório de exportação lista os avisos. A exportação de projeto grava uma cópia sanitizada, não um espelho byte a byte; arquivos extras (README, notas) são copiados sem análise, então não coloque segredos neles.

Ambientes e histórico

reqlivo --collection minha-api env list
reqlivo --collection minha-api env show seguro
reqlivo --collection minha-api history --limit 10

env show mascara valores secretos. O histórico fica em .reqlivo/history/runs.jsonl; logs ficam em .reqlivo/logs/events.jsonl.

Demonstração

Com o servidor sintético em execução:

# Em um terminal
python3 examples/servidor_demo.py

# Em outro
reqlivo --collection examples/demo run --env dev
REQLIVO_DEMO_TOKEN=valor-sintetico reqlivo --collection examples/demo run --env seguro
reqlivo --collection examples/demo export curl req_4a2b3c4d5e6f7081

Endpoints usados: /echo, /status/404. O servidor grava requisições em $SYNTH_LOG (padrão definido pelo próprio script).

JSON e integração

Use --json para automação. Os corpos da ponte IPC usam camelCase; os relatórios do runner e os objetos de domínio usam snake_case, refletindo o modelo canônico.

Offline

Ative pela coleção (Configurações → Modo offline) ou por:

REQLIVO_OFFLINE=1 reqlivo --collection examples/demo run --env dev

No modo offline:

Erros e códigos de saída

Código Situação
0 comando concluído sem falhas/erros/cancelamentos.
1 falha de validação, execução, importação/exportação ou erro de rede.
--json o erro vai para stderr; o resultado vai para stdout.

Mensagens de erro incluem categoria, código e próximo passo quando disponível. Segredos conhecidos são redigidos. Na ponte IPC, conflitos recuperáveis usam HTTP 409 com códigos estáveis (revision_conflict, generation_conflict, draft_generation, destination_exists, duplicate_id, restore_conflict, migration_required, confirmation_required, collection_unavailable); o formulário e o rascunho permanecem disponíveis.