Começar com a CLI fp

fp é a CLI do Fetchpier para terminais e CI. Usa o mesmo motor de requisições do app desktop, portanto resolução de variáveis, autenticação, cookies, TLS, scripts e testes se comportam da mesma forma. A CLI é instalada separadamente e possui número de versão próprio.

Requisitos e instalação

Instale Node.js 22.19.0 ou posterior e, depois, o pacote global:

npm install -g @fetchpier/cli
fp --version

fp verifica a versão do Node.js antes de fazer qualquer outra coisa. Em um runtime mais antigo, ele para imediatamente com uma mensagem que nomeia a versão necessária e a encontrada, e sai com um código dedicado (18) em vez de falhar mais tarde dentro de uma dependência. O npm também avisa sobre o mínimo na instalação, mas esse aviso é fácil de passar despercebido em uma instalação global.

O comando de versão imprime o nome do produto, a versão da CLI e o aviso de copyright. Use fp --help ou fp <command> --help para a ajuda embutida na versão instalada.

Criar ou abrir um workspace

Inicialize um workspace em uma nova pasta:

fp init my-api
cd my-api

fp init cria a estrutura do workspace do Fetchpier, um ambiente default com uma única variável baseUrl, uma requisição inicial (requests/example.http) e um .gitignore quando não existe nenhum. É o mesmo layout que o app desktop cria, então o ambiente ao qual uma execução recorre por padrão (default) já existe. Ao final, imprime o comando a executar em seguida — fp run --workspace my-api, ou fp run quando você inicializa a pasta atual —, que funciona exatamente como impresso a partir do mesmo diretório. Qualquer workspace já criado pelo app desktop também serve.

Executar requisições

Execute todas as requisições do workspace — os arquivos .http dentro de requests/, recursivamente:

fp run

Sem path, a CLI executa esse mesmo conjunto a partir de qualquer diretório: uma subpasta do workspace, ou de fora dele com --workspace ou FETCHPIER_WORKSPACE. Uma pasta sem nenhum arquivo .http para a execução com o código de saída 19, porque uma execução que não envia nada não é um sucesso.

Execute um arquivo:

fp run requests/auth/login.http

Execute todos os arquivos .http abaixo de uma pasta:

fp run requests/smoke --env staging

fp run é o alias curto de fp request run. Paths explícitos são relativos ao diretório atual, como em qualquer outra ferramenta de linha de comando; se um path não existe ali mas existe dentro do workspace, o erro sugere o path a digitar. Os arquivos são executados em ordem determinística de path e apenas a primeira requisição de cada arquivo .http é executada; a CLI imprime um aviso informativo quando um arquivo contém requisições adicionais.

Selecionar o workspace

A CLI resolve o workspace nesta ordem:

1. --workspace <path> (ou -w);
2. a variável de ambiente FETCHPIER_WORKSPACE;
3. a pasta pai mais próxima que contenha .fetchpier/, subindo a partir do diretório atual.

Para automações reproduzíveis, defina --workspace ou FETCHPIER_WORKSPACE explicitamente.

Selecionar o ambiente

O ambiente é resolvido de forma independente:

1. --env <name> (ou -e);
2. FETCHPIER_ENV;
3. a pasta de ambiente chamada default.

A comparação usa, sem diferenciar maiúsculas, o nome seguro para o sistema de arquivos da pasta do ambiente. É o identificador mostrado por fp env list, não o rótulo de exibição nem o identificador interno.

fp env list
fp env current --env staging
fp run requests/smoke --env staging

A CLI nunca lê nem altera o ambiente selecionado por último no app desktop. Essa separação mantém o comportamento do CI independente do estado da UI de um desenvolvedor. fp env switch não existe.

Sobrescrever variáveis em uma execução

Use as opções repetíveis --env-var KEY=VALUE para valores fornecidos por quem chama:

fp run requests/smoke \
  --env ci \
  --env-var BASE_URL=https://api.example.test \
  --env-var BUILD_ID=1234

Um script que depois define a mesma variável prevalece sobre --env-var a partir desse ponto.

Referências {{variable}} não resolvidas permanecem literais e geram um aviso, e um {{$env.NAME}} que nem o .env do workspace nem o ambiente do processo definem é enviado vazio, também com um aviso. Nenhum dos dois faz a execução falhar por si só, mas o aviso torna visível uma variável mal digitada ou ausente antes que a rejeição do servidor seja a única pista; faça asserções sobre a resposta quando uma credencial ausente precisar fazer o pipeline falhar. Variáveis dinâmicas como {{$guid}} se resolvem exatamente como no desktop.

Passar valores entre requisições

Um valor que um script define com fp.environment.set (ou remove com fp.environment.remove) se aplica a todas as requisições posteriores da mesma execução, então um token guardado por uma requisição de login chega à chamada autenticada seguinte. Por padrão essas mudanças valem apenas durante a execução e nada é escrito no workspace. Adicione --persist-env para salvá-las nos valores locais da máquina, exatamente como o desktop faz:

fp run requests/auth --env staging --persist-env

Proxies e timeouts

Cada requisição tem um timeout de 30 segundos por padrão, o mesmo do desktop; altere-o com --timeout <ms> ou desative-o com --timeout 0. A CLI respeita HTTPS_PROXY, HTTP_PROXY e NO_PROXY; --proxy <url> as sobrescreve e --no-proxy as ignora em uma execução. Veja Referência da CLI fp para os detalhes.

Usar segredos no CI

Se uma requisição realmente lê uma variável de ambiente criptografada, injete a chave do workspace pelo cofre de segredos do CI:

export FETCHPIER_WORKSPACE_KEY='FPK1-...'
fp run requests/smoke --env ci

A resolução é preguiçosa: requisições que não tocam segredos não precisam de chave. Relatórios e saída do terminal nunca imprimem valores descriptografados: um segredo aparece como {secret:<name>}, inclusive no que um script registra e na mensagem de uma asserção que falhou. Rode workspaces não confiáveis dentro de um contêiner ou de outra barreira de isolamento, porque o sandbox de scripting não pretende conter código malicioso.

Próximos passos

• Veja Referência da CLI fp para cada flag, formato de relatório e código de saída.
• Veja Variáveis para valores compartilhados, locais, secretos e dinâmicos.
• Veja TLS e certificados para o comportamento dos certificados do workspace.