Apidog CLI: Cliente API na Linha de Comando

Seu espaço de trabalho de API vive em uma GUI, mas seu CI, seus scripts e seus agentes de IA vivem no terminal. Alternar entre os dois custa tempo e foco — e, em pipelines automatizados, a GUI simplesmente não está disponível. O Apidog CLI leva testes, endpoints, esquemas, ambientes, mocks e documentação do seu projeto Apidog para o shell.

Experimente o Apidog hoje

O Apidog CLI não tenta substituir curl ou HTTPie. Para enviar uma requisição GET isolada e inspecionar JSON, essas ferramentas já resolvem bem o problema. Consulte também este resumo de clientes REST de terminal e TUI. O foco do Apidog CLI é operar o seu espaço de trabalho: executar cenários de teste salvos, consultar ou atualizar contratos de API e importar ou exportar especificações em scripts, CI e fluxos de agentes.

O que o Apidog CLI faz no terminal

Enquanto ferramentas HTTP tradicionais trabalham com uma requisição por vez, o Apidog CLI opera no nível do projeto.

Tarefa	Comandos
Executar testes	run, test-scenario, test-suite, test-case, test-data, test-report
Gerenciar o contrato	endpoint, schema, folder, common-parameter, response-component, security-scheme
Publicar documentos e mocks	doc, docs-site, shared-doc, mock
Configurar e conectar	environment, variables, vault, database-connection, websocket, socketio
Operar em equipe	branch, merge-request, runner, scheduled-task, audit-log, import, export

Comece explorando comandos sem decorar a interface:

apidog --help
apidog run --help
apidog endpoint --help

A saída é JSON estruturado. Muitas respostas também incluem agentHints.nextSteps, com sugestões do próximo comando. Isso facilita a automação em scripts e permite que agentes sigam fluxos de trabalho sem depender de tentativa e erro.

Instale e autentique o CLI

O CLI é distribuído como o pacote npm apidog-cli e funciona em macOS, Linux e Windows. É necessário ter Node.js 16 ou superior.

npm install -g apidog-cli
apidog --version

Em seguida, autentique-se usando um token de acesso da API. No aplicativo Apidog, abra o menu do avatar, acesse as Configurações da Conta e copie o valor em Token de Acesso à API.

apidog login --with-token <SEU_TOKEN>

O token é salvo em ~/.apidog/config.toml. Não versione esse arquivo nem exponha o token em logs.

Em CI, prefira passar o token por um segredo de ambiente usando --access-token:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenario_id> \
  -e <env_id> \
  -r cli

As flags globais mais úteis são:

Flag	Uso
--project	Seleciona o projeto
--branch	Seleciona o branch
--access-token	Sobrescreve o login salvo
--api-base-url	Aponta o CLI para uma implantação Apidog auto-hospedada

Para detalhes sobre tokens em pipelines, consulte o guia de autenticação do Apidog CLI.

Execute cenários de teste no CI

O fluxo principal é simples:

1. Crie um cenário no editor visual do Apidog.
2. Encadeie requisições, extraia variáveis e configure asserções.
3. Copie o comando da aba CI/CD do cenário.
4. Execute-o localmente ou no pipeline.

# Copie os IDs da aba CI/CD do cenário no Apidog
apidog run -t <scenario_id> -e <env_id> -r cli

O comando retorna:

• Código 0 quando todas as asserções passam.
• Código diferente de zero quando uma etapa falha.

Isso permite bloquear uma build sem scripts auxiliares:

apidog run -t "$SCENARIO_ID" -e "$STAGING_ENV_ID" -r cli,junit

Troque -e para executar o mesmo cenário em desenvolvimento, staging ou produção.

Execute testes orientados por dados

Para iterar um cenário sobre dados CSV ou JSON, forneça o arquivo de dados ao fluxo configurado no Apidog. Assim, você reutiliza as mesmas etapas sem duplicar cenários. Veja o guia de testes baseados em dados com Apidog CLI.

Se estiver começando, siga este passo a passo para testar uma API REST pela linha de comando.

Gere relatórios para o pipeline

Use -r para selecionar os formatos de relatório:

Formato	Uso
cli	Mostra o resultado passo a passo no terminal
html	Gera um relatório HTML
json	Gera dados estruturados para processamento
junit	Gera resultados compatíveis com ferramentas de CI

Os relatórios são salvos em apidog-reports/.

# Saída no terminal e arquivo JUnit para o CI
apidog run -t <scenario_id> -e <env_id> -r cli,junit

Consulte o guia de relatórios de teste para ver os formatos em detalhes.

Para remover a dependência do laptop, use os grupos runner e scheduled-task para gerenciar runners auto-hospedados e execuções agendadas. Essa é a base dos testes de API agendados no Apidog.

Consulte e gerencie o contrato da API

O Apidog CLI também permite trabalhar com a definição da API sem abrir o aplicativo.

# Liste endpoints de um projeto
apidog endpoint list --project <project_id>

# Consulte um esquema
apidog schema get <schema_id>

# Liste ambientes disponíveis
apidog environment list

# Liste expectativas de mock
apidog mock list

Você pode consultar e editar recursos como:

• Endpoints e pastas
• Esquemas de dados
• Ambientes e variáveis
• Esquemas de segurança
• Componentes reutilizáveis
• Expectativas de mock
• Documentação publicada
• Configurações de banco de dados para cenários de teste

Os comandos doc e docs-site gerenciam documentação publicada. Os grupos websocket e socketio atendem endpoints WebSocket e Socket.IO, enquanto database-connection cobre configurações de banco usadas pelos cenários.

Importe e exporte especificações

O CLI trabalha com OpenAPI 3.x, Swagger 2.0 e coleções Postman. Isso é útil em migrações e sincronizações automatizadas.

# Importe uma especificação OpenAPI para um projeto
apidog import openapi.json --project <project_id>

# Exporte a definição do projeto como OpenAPI
apidog export --format openapi

Swagger 2.0 segue a especificação adotada por grande parte das toolchains de API.

Use o CLI com agentes de IA

Os lançamentos de 2026 do CLI adicionam recursos para que agentes de codificação operem espaços de trabalho de API de forma estruturada.

1. Consuma saída estruturada

Cada comando retorna JSON que um agente pode analisar. O campo agentHints.nextSteps sugere ações seguintes e caminhos de recuperação após erros.

2. Valide payloads antes de escrever

Use cli-schema para obter o formato de entrada esperado, validar o JSON e só então executar operações de escrita.

# Liste os esquemas disponíveis
apidog cli-schema list

# Consulte o esquema de um comando específico
apidog cli-schema get <schema_id>

# Valide um payload antes de criar ou atualizar recursos
apidog cli-schema validate <payload.json>

O fluxo seguro para automações é:

1. Obter o esquema.
2. Gerar o JSON.
3. Validar o payload.
4. Executar create ou update.

3. Carregue a skill do CLI

O comando skill entrega o conhecimento operacional do CLI em um formato que agentes podem carregar diretamente. Veja por que a skill do Apidog CLI foi criada.

Segundo as medições publicadas pelo Apidog, agentes que usam o esquema do CLI fizeram cerca de 30% menos chamadas de ferramenta e consumiram 25% menos tokens do que agentes que tentavam adivinhar payloads. Os detalhes estão nesta análise.

4. Isole escritas de IA em branches

Por padrão, escritas originadas por IA em um branch são bloqueadas até que um humano ative as Permissões de Edição Externa de IA.

No cliente Apidog 2.8.32 ou posterior, acesse:

Configurações do Projeto
→ Configurações de Recursos
→ Configurações de Recursos de IA

Outra opção é usar um branch de IA. O agente importa os recursos necessários, faz alterações isoladas e entrega o resultado em uma solicitação de mesclagem para revisão. Branches de IA não utilizados são arquivados automaticamente após 24 horas.

O que o Apidog CLI não é

Não é um cliente HTTP interativo

Não há um comando focado em digitar um POST ad-hoc e imprimir a resposta formatada. Para isso, use curl, HTTPie ou clientes TUI.

Não é de código aberto

O pacote é proprietário, o npm é o único canal de instalação e operações além de --help exigem uma conta Apidog. A camada gratuita cobre o fluxo de criação e execução de cenários descrito aqui. Se uma licença auditável for obrigatória, um executor open source é uma opção mais adequada.

Não é autônomo

Cenários, endpoints e ambientes vivem no projeto Apidog, não em arquivos locais. Essa é a troca para manter uma fonte única de verdade entre design, testes, mocks e documentação.

Onde ele se encaixa na sua stack

A diferença entre runners está principalmente em onde os testes são criados:

• Newman e Postman CLI executam coleções criadas no Postman.
• Hurl e Bruno executam testes definidos em arquivos de texto.
• Apidog CLI executa cenários criados no editor visual do Apidog, onde também vivem contrato, mocks e documentação.

Leia a comparação entre Apidog CLI e Newman e o panorama das principais ferramentas de teste de API baseadas em terminal.

Uma configuração prática para a maioria das equipes:

curl ou xh     → requisições rápidas e ad-hoc
apidog run     → cenários completos no CI

Para começar no GitHub Actions, use este passo a passo para Apidog CLI no GitHub Actions.

FAQ

O Apidog CLI é gratuito?

Sim. O pacote é instalado gratuitamente via npm, e o nível gratuito do Apidog cobre a criação e execução de cenários pelo CLI. Planos pagos adicionam recursos para equipes, não o acesso básico ao CLI.

Ele substitui curl ou HTTPie?

Não. curl e HTTPie enviam requisições ad-hoc. O Apidog CLI executa cenários salvos e gerencia recursos do projeto. É comum usar ambos no mesmo terminal.

Ele roda sem interface gráfica em CI?

Sim. Passe --access-token a partir de um segredo do CI, execute apidog run com o ID do cenário e condicione a build ao código de saída. Nenhum aplicativo desktop é necessário no executor.

Quais formatos ele pode importar e exportar?

OpenAPI 3.x, Swagger 2.0 e coleções Postman, em ambas as direções.

Como agentes de IA usam o CLI com segurança?

Use a validação de esquema antes das escritas e isole mudanças em branches de IA. O comando cli-schema validate detecta payloads malformados antes que sejam registrados, enquanto branches de IA mantêm as alterações isoladas até a revisão humana. Veja como usar o Apidog CLI no Claude Code.

O terminal já é onde seus testes rodam e onde seus agentes trabalham. Instale o CLI, execute um cenário de ponta a ponta e use a página do Apidog CLI como referência ao expandir além de run. Você também pode baixar o Apidog.