Resterm

Um cliente de API e workbench nativo de terminal para REST, GraphQL, gRPC, WebSocket e SSE.

Resterm é um workbench API-como-código — ou, em termos mais familiares, um cliente de API — construído em torno de arquivos .http e .rest simples que você pode comparar (diff), revisar e versionar. Ele combina edição interativa de requisições com fluxos de trabalho declarativos, asserções, servidores mock, tracing, profiling e automação headless. Tudo permanece na sua máquina. Sem contas, sem sincronização em nuvem, sem telemetria.

Se você procura um cliente estilo Postman centrado em coleções de GUI, Resterm provavelmente não é para você, mas experimente mesmo assim!

[!NOTE] Resterm agora está na v1! Consulte as notas de lançamento da v1.0.0 para conhecer os novos recursos e mudanças que quebram compatibilidade.

Links rápidos: Screenshots, Instalação, Início Rápido, Documentação.

Tour de screenshots

Por que Resterm

• HTTP, GraphQL, gRPC, WebSocket e SSE prontos para uso.
• A automação vive nos arquivos de requisição: condições (@when, @if/@elif/@else, @for-each), fluxos de trabalho de múltiplas etapas (@workflow / @step), captures, variáveis e asserções (@capture, @var, @assert).
• RestermScript, uma pequena linguagem de expressão criada para Resterm, com hooks JavaScript quando você quiser.
• Controles estilo Vim com dicas contextuais na barra inferior, ajuda off-line pesquisável, ajuda K sob o cursor, busca / e comandos como :w, , e .

Início Rápido

1. Instale o Resterm (veja Instalação para scripts, Windows e instalações manuais).

   root@kitploit:~

   brew install resterm
   

2. Inicialize um workspace.

   root@kitploit:~

   mkdir my-api && cd my-api
   resterm init
   

   O resterm init entrega um pequeno projeto que funciona sem conexão com a internet. O requests.http gerado inclui cenários mock locais e algumas requisições que dependem umas das outras. Eles cobrem asserções, autenticação bearer, correspondência JSON, json-rules e @for-each.

3. Inicie-o e envie sua primeira requisição.

   root@kitploit:~

   resterm
   

   Pressione Ctrl+Enter no editor para enviar a requisição destacada.

Ainda não tem arquivos? Basta executar resterm, digitar uma URL e pressionar Ctrl+Enter. Um comando curl colado também funciona.

CLI

O resterm run executa arquivos .http / .rest sem abrir a TUI, que é o que as execuções de CI fazem.

resterm run --request CreateUser requests.http

O projeto gerado fala com um servidor mock local. Inicie-o em outro terminal primeiro:

resterm mock requests.http

Na TUI, pressione g Shift+M para iniciar o mesmo servidor mock a partir do workspace.

A documentação da CLI cobre seletores, formatos de saída e mais exemplos.

Servidores Mock

Os mesmos arquivos que contêm suas requisições podem servir mocks HTTP.

• Corresponda requisições recebidas por query, cabeçalhos ou corpo JSON e escolha uma resposta nomeada ou padrão.
• Modele fluxos de polling e retry com sequências de respostas, incluindo cursores independentes por recurso ou chamador.
• Atrase respostas por um valor fixo, ou dê a cada requisição um atraso diferente com random, normal ou jitter.
• Construa respostas a partir de valores de path, query, cabeçalho e corpo, com geradores para dados dinâmicos.
• Verifique contagens de chamadas com @expect ou inspecione o tráfego recebido a partir do RestermScript.
• Hot reload de arquivos fonte e fixtures, com TLS opcional.

Dois cenários na mesma rota:

### Payment accepted
# @mock method=POST path=/payments name=accepted default=true latency=150ms
HTTP/1.1 202 Accepted
Content-Type: application/json

{"id":"pay_123","status":"pending"}

### Payment declined
# @mock method=POST path=/payments name=declined
# @match query={"mode":"decline"} headers={"X-Tenant":"demo"} json={"amount":0}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"error":"amount must be positive"}

Sirva um arquivo ou um diretório inteiro:

resterm mock ./requests.http
resterm mock --recursive --addr 127.0.0.1:9090 ./requests

Mais na referência de Servidores Mock, no guia da CLI resterm mock e no exemplo funcional.

Headless

O pacote headless é a API Go pública do mesmo motor que alimenta a TUI e a CLI. Use-o para executar requisições, workflows, asserções, comparar execuções e perfis a partir do seu próprio código Go ou de CI.

Se você preferir não criar seu próprio executor, existe o resterm-runner.

Folha de atalhos do teclado

• Foco do painel e layout
  • Tab / Shift+Tab: alterna entre sidebar, editor e resposta.
  • g+r, g+i, g+p: pula para requisições, editor ou resposta.
  • g+h / g+l: redimensiona horizontalmente. Altera a largura da sidebar quando a sidebar está focada; caso contrário, a divisão editor/resposta.
  • g+j / g+k: redimensiona a altura editor/resposta quando empilhados; recolhe ou expande ramos no navegador.
  • g+v / g+s: alterna o painel de resposta entre layout embutido e empilhado.
  • g+1, g+2, g+3: minimiza ou restaura sidebar, editor, resposta.

[!TIP] Se você só vai lembrar de três atalhos:

• Ctrl+Enter envia a requisição
• Tab / Shift+Tab alterna painéis
• g+p pula para a resposta

Instalação

Linux / macOS (Homebrew)

brew install resterm

[!NOTE] As instalações via Homebrew devem ser atualizadas com o Homebrew (brew upgrade resterm). O comando embutido resterm --update é para binários instalados a partir dos releases do GitHub ou dos scripts de instalação.

Linux / macOS (script de shell)

[!IMPORTANT] Os binários Linux pré-compilados dependem de glibc 2.32 ou mais nova. Em uma distro mais antiga, compile a partir do código-fonte com um toolchain de glibc mais novo ou atualize a glibc antes de usar os arquivos de release.

curl -fsSL https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.sh | bash

ou com wget:

wget -qO- https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.sh | bash

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.ps1 | iex

Os scripts detectam sua arquitetura, baixam o release mais recente e instalam o binário.

Instalação manual

[!NOTE] O auxiliar de instalação manual usa curl e jq. Instale o jq com seu gerenciador de pacotes (brew install jq, sudo apt install jq, etc.).

Linux / macOS

# Detect latest tag
LATEST_TAG=$(curl -fsSL https://api.github.com/repos/unkn0wn-root/resterm/releases/latest | jq -r .tag_name)

# Download the matching binary (Darwin/Linux + amd64/arm64)
curl -fL -o resterm "https://github.com/unkn0wn-root/resterm/releases/download/${LATEST_TAG}/resterm_$(uname -s)_$(uname -m)"

# Make it executable and move it onto your PATH
chmod +x resterm
sudo install -m 0755 resterm /usr/local/bin/resterm

Windows (PowerShell)

$latest = Invoke-RestMethod https://api.github.com/repos/unkn0wn-root/resterm/releases/latest
$asset  = $latest.assets | Where-Object { $_.name -like 'resterm_Windows_*' } | Select-Object -First 1
Invoke-WebRequest -Uri $asset.browser_download_url -OutFile resterm.exe
# Optionally relocate to a directory on PATH, e.g.:
Move-Item resterm.exe "$env:USERPROFILE\bin\resterm.exe"

A partir do código-fonte

go install github.com/unkn0wn-root/resterm/cmd/resterm@latest

Atualização

resterm --check-update
resterm --update

O primeiro comando informa se há um release mais novo disponível. O segundo baixa, verifica e instala no lugar. No Windows, o binário antigo permanece ao lado do novo como resterm.exe.old e é limpo na próxima atualização.

Configuração

• Ambientes são arquivos JSON (resterm.env.json) descobertos no diretório de requisições, na raiz do workspace ou no diretório de trabalho atual. Um arquivo pode definir ambientes nomeados ou grupos independentes, por exemplo api, app e credentials, que se combinam em um único ambiente. Arquivos Dotenv (.env, .env.*) são opcionais via --env-file e são de workspace único. Consulte ambientes agrupados e o exemplo executável em _examples/grouped/.
• A configuração é armazenada por SO e pode ser substituída com RESTERM_CONFIG_DIR:
  • macOS: ~/Library/Application Support/resterm
  • Windows: %APPDATA%\resterm
  • Linux/Unix: ~/.config/resterm

Coleções

Exporte um workspace como um pacote amigável ao Git e importe-o em outro. Os pacotes carregam um manifest.json com checksums, para que as importações verifiquem a integridade dos arquivos primeiro. Os valores de ambiente são exportados como placeholders REPLACE_ME, para que segredos nunca saiam da sua máquina.

resterm collection export --workspace ./my-api --out ./shared/my-api-bundle
resterm collection import --in ./shared/my-api-bundle --workspace ./my-local-api

Adicione --dry-run para pré-visualizar uma importação e --force para sobrescrever arquivos existentes. Docs: compartilhamento de coleções.

Importação de curl

Cole um comando curl no editor e pressione Ctrl+Enter para transformá-lo em uma requisição estruturada. Resterm entende os flags comuns, mescla segmentos de dados repetidos e mantém uploads multipart intactos. Prefixos de shell como sudo ou $ são ignorados. A CLI faz a mesma conversão com --from-curl.

Isto:

curl -X POST https://api.example.com/login \
  -H "Content-Type: application/json" \
  --user demo:secret \
  -d '{"user":"demo"}'

torna-se isto:

### POST https://api.example.com/login
# @auth basic demo secret
POST https://api.example.com/login
Content-Type: application/json

{"user":"demo"}

Docs: requisições inline e exemplos de importação.

RestermScript

RestermScript (RTS) é uma pequena linguagem de expressão criada para Resterm. Ela tem como alvo direto o formato de requisição, os workflows e as diretivas, o que mantém os scripts curtos e previsíveis. Hooks JavaScript continuam disponíveis quando você precisar de mais.

Exemplo rápido (módulo RTS + requisição):

// rts/helpers.rts
module helpers
export fn authHeader(token) {
  return token ? "Bearer " + token : ""
}

# @use ./rts/helpers.rts
# @when env.has("feature")
# @assert response.statusCode == 200
GET https://api.example.com/users/{{= vars.get("user") }}
Authorization: {{= helpers.authHeader(vars.get("auth.token")) }}

Referência completa: docs/restermscript.md.

Aprofundamento

OAuth 2.0

Client credentials, password grant e authorization code com PKCE. Para fluxos de auth code, Resterm abre seu navegador, executa um servidor de callback local em 127.0.0.1, captura o redirect e troca o código. Os tokens são armazenados em cache por ambiente e atualizados quando expiram. Docs: docs/resterm.md#oauth-20-directive e _examples/oauth2.http.

Workflows e scripting

Encadeie requisições com @workflow e @step, passe dados entre etapas e adicione hooks JS quando necessário. Docs e exemplo: docs/resterm.md#workflows e _examples/workflows.http.

Comparar execuções

Execute a mesma requisição em diferentes ambientes com @compare ou --compare e depois compare as respostas lado a lado com g+c. Docs: docs/resterm.md#compare-runs.

Tracing e timeline

Adicione @trace com orçamentos para capturar tempos de DNS, connect, TLS, TTFB e transferência. Resterm destaca estouros de orçamento e pode exportar spans para OpenTelemetry. Docs: docs/resterm.md#timeline--tracing.

Streaming (WebSocket e SSE)

Use @websocket com etapas @ws ou @sse para scriptar e gravar streams. A aba Stream mantém as transcrições e inclui um console interativo. Docs: docs/resterm.md#streaming-sse--websocket.

gRPC

Chamadas unárias e de streaming com transcrições, metadados e expansão de corpo. Docs: docs/resterm.md#grpc.

Importação OpenAPI

Converta especificações OpenAPI 3 em coleções .http com --from-openapi, a partir de um arquivo local ou de uma URL http(s). Escolha os blocos gerados com --openapi-mode requests, mocks ou both. Buscas remotas respeitam os flags globais --insecure e --proxy. Docs: docs/cli.md#import-examples.

Túneis SSH

Roteie tráfego HTTP, gRPC, WebSocket e SSE através de bastions com perfis @ssh. Docs: docs/resterm.md#ssh-tunnels e _examples/ssh.http.

Port-forwards de Kubernetes

A mesma ideia com perfis @k8s, direcionados a pods, services, deployments ou statefulsets. Docs: docs/resterm.md#kubernetes-port-forwards e _examples/k8s.http.

Temas e bindings

Personalize cores e atalhos de teclado com themes/*.toml e bindings.toml ou bindings.json no diretório de configuração. Docs: docs/resterm.md#theming e docs/resterm.md#custom-bindings.

Documentação

• docs/resterm.md cobre sintaxe de requisição, diretivas, scripting e transportes.
• docs/cli.md cobre resterm run, importadores, coleções e histórico.
• Compatibilidade explica as garantias de compatibilidade do Resterm para a v1.

Dentro da TUI, pressione ? ou execute :help. Use :docs quando quiser o manual web completo do release instalado.

Licença

Apache License 2.0.