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
- Use a árvore para abrir uma pasta ou requisição.
- Edite nome, método, URL e tags.
- Percorra as abas Params, Headers, Corpo, Auth, Scripts e Testes.
- Use Salvar (
Ctrl/Cmd+S) para gravar no arquivo. - 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
- Enquanto o editor tem alterações, o Reqlivo protege um rascunho em
.reqlivo/drafts/(até 2 s após a última edição, com limite de 5 s durante digitação contínua). O YAML canônico só muda ao usar Salvar. - O indicador do editor diferencia “Alterações não salvas”, “Protegendo rascunho…”, “Rascunho protegido” e falha de proteção. Rascunhos são texto local sem criptografia e podem conter credenciais literais digitadas; no Unix usam permissão
0600. - Trocar de requisição/coleção, recarregar ou fechar com edição pendente abre o guardião de navegação: Salvar, Manter rascunho e continuar, Descartar alterações ou Cancelar.
- Ao reabrir, Rascunhos lista edições recuperáveis. Se o arquivo mudou, o rascunho aparece como divergente e o salvamento permanece bloqueado até uma decisão explícita. Se o arquivo sumiu, o rascunho órfão pode virar uma nova requisição com ID novo.
- A UI consulta o disco enquanto a janela está visível e ao receber foco. Uma alteração externa mostra um aviso com os caminhos afetados; com o editor sujo, a edição local é preservada. Recarregar exige que nenhuma alteração seja descartada silenciosamente.
- Comparar lê a versão atual do arquivo no disco, não o snapshot em memória usado pelo envio. Manter conserva a edição sem sobrescrever o disco; Usar disco descarta o rascunho; Aplicar sobre a nova base realinha a revisão e grava a edição local.
- YAML inválido não substitui o último snapshot válido: a UI mostra o caminho e o erro, mantém o editor utilizável e volta a reconciliar depois que o arquivo é corrigido.
- Conflitos de revisão retornam HTTP 409 (
revision_conflict,generation_conflict) e mantêm o formulário e o rascunho no lugar. Um salvamento de ambiente/configuração rejeitado não altera o estado em memória.
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:
- status HTTP e texto;
- tempo e tamanho;
- URL final e indicador de redirecionamento;
- abas de corpo, headers, testes e logs;
- botão para corpo bruto quando o conteúdo é textual;
- erros tipados (
connect,timeout,offline,script, etc.).
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
- Abra Runner (
Alt+R). - Escolha ambiente, tags, pasta ou “somente a requisição atual”.
- Inicie e acompanhe o relatório.
- 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:
- criar, editar e excluir ambientes;
- definir herança com
extends; - marcar a variável como segredo;
- informar a chave de ambiente do processo (por exemplo,
REQLIVO_API_TOKEN); - definir o ambiente padrão.
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
- O original importado é preservado em
.reqlivo/imports/quando aplicável. - Postman tem relatório de perdas; scripts ficam em
extensions.postmanScriptse não são executados. - Use
--folder <fld_...>para importar dentro de uma pasta.
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:
- Authorization, cookies, tokens, chaves e headers sensíveis literais;
- auth literal (Basic/Bearer/API key);
- parâmetros de query sensíveis literais;
- variáveis marcadas como segredo.
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:
- destinos externos são recusados antes de abrir conexão;
localhost, loopback, IPs privados e link-local são permitidos;- redirecionamentos para fora da rede local não são seguidos;
- não há chamada a telemetria, atualização ou nuvem.
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.