Empezar con la CLI fp

fp es el cliente de línea de comandos de Fetchpier para terminales y CI. Usa el mismo motor de solicitudes que la app de escritorio, por lo que la resolución de variables, la autenticación, las cookies, TLS, los scripts y los tests se comportan igual. La CLI se instala por separado y tiene su propio número de versión.

Requisitos e instalación

Instala Node.js 22.19.0 o posterior y luego instala el paquete de forma global:

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

fp verifica la versión de Node.js antes de hacer cualquier otra cosa. En un runtime más viejo se detiene de inmediato con un mensaje que nombra la versión que necesita y la que encontró, y sale con un código dedicado (18) en lugar de fallar más tarde dentro de una dependencia. npm también advierte el mínimo al instalar, pero esa advertencia es fácil de pasar por alto en una instalación global.

El comando de versión imprime el nombre del producto, la versión de la CLI y el aviso de copyright. Usa fp --help o fp <command> --help para ver la ayuda incluida en la versión instalada.

Crear o abrir un workspace

Inicializa un workspace en una carpeta nueva:

fp init my-api
cd my-api

fp init crea la estructura de workspace de Fetchpier, un entorno default con una sola variable baseUrl, una solicitud inicial (requests/example.http) y un .gitignore si no existe ninguno. Es el mismo layout que crea la app de escritorio, así que el entorno al que recurre una ejecución por defecto (default) ya existe. Al final imprime el comando a ejecutar a continuación — fp run --workspace my-api, o fp run cuando inicializas la carpeta actual —, que funciona tal como se imprime desde el mismo directorio. También puedes usar cualquier workspace ya creado por la aplicación de escritorio.

Ejecutar solicitudes

Ejecuta todas las solicitudes del workspace — los archivos .http bajo requests/, de forma recursiva:

fp run

Sin path, la CLI ejecuta ese mismo conjunto desde cualquier directorio: una subcarpeta del workspace, o desde fuera de él con --workspace o FETCHPIER_WORKSPACE. Una carpeta sin ningún archivo .http detiene la ejecución con el código de salida 19, porque una ejecución que no envía nada no es un éxito.

Ejecuta un archivo:

fp run requests/auth/login.http

Ejecuta todos los archivos .http bajo una carpeta:

fp run requests/smoke --env staging

fp run es el alias corto de fp request run. Los paths explícitos son relativos al directorio actual, como en cualquier otra herramienta de línea de comandos; si un path no existe ahí pero sí dentro del workspace, el error sugiere el path que debes escribir. Los archivos se ejecutan en un orden de path determinístico y solo se ejecuta la primera solicitud de cada archivo .http; la CLI imprime un aviso informativo cuando un archivo contiene solicitudes adicionales.

Seleccionar el workspace

La CLI resuelve el workspace en este orden:

1. --workspace <path> (o -w);
2. la variable de entorno FETCHPIER_WORKSPACE;
3. la carpeta padre más cercana que contenga .fetchpier/, subiendo desde el directorio actual.

Para una automatización reproducible, define --workspace o FETCHPIER_WORKSPACE explícitamente.

Seleccionar el entorno

El entorno se resuelve de forma independiente:

1. --env <name> (o -e);
2. FETCHPIER_ENV;
3. la carpeta de entorno llamada default.

La comparación usa el nombre de la carpeta del entorno (seguro para el filesystem), sin distinguir mayúsculas de minúsculas. Es el identificador que muestra fp env list, no la etiqueta visible ni el identificador interno.

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

La CLI nunca lee ni cambia el entorno seleccionado por última vez en la app de escritorio. Esta separación mantiene el comportamiento en CI independiente del estado de la UI de cada desarrollador. fp env switch no está disponible.

Sobrescribir variables para una ejecución

Usa opciones --env-var KEY=VALUE repetibles para los valores que aporta quien invoca la CLI:

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

Un script que más adelante define la misma variable prevalece sobre --env-var a partir de ese momento.

Las referencias {{variable}} sin resolver quedan literales y generan un warning, y un {{$env.NAME}} que no define ni el .env del workspace ni el entorno del proceso se envía vacío, también con un warning. Ninguno de los dos falla la ejecución por sí solo, pero el warning hace visible una variable mal escrita o faltante antes de que el rechazo del servidor sea la única pista; agrega aserciones sobre la respuesta cuando una credencial faltante deba hacer fallar el pipeline. Las variables dinámicas como {{$guid}} se resuelven igual que en el escritorio.

Pasar valores entre solicitudes

Un valor que un script define con fp.environment.set (o elimina con fp.environment.remove) se aplica a todas las solicitudes posteriores de la misma ejecución, así que un token guardado por una solicitud de login llega a la llamada autenticada que sigue. Por defecto estos cambios viven solo durante la ejecución y no se escribe nada en el workspace. Agrega --persist-env para guardarlos en los valores locales de la máquina, exactamente como lo hace el escritorio:

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

Proxies y timeouts

Cada solicitud tiene por defecto un timeout de 30 segundos, igual que en el escritorio; cámbialo con --timeout <ms> o desactívalo con --timeout 0. La CLI respeta HTTPS_PROXY, HTTP_PROXY y NO_PROXY; --proxy <url> los sobrescribe y --no-proxy los ignora durante una ejecución. Consulta la referencia de la CLI fp para ver los detalles.

Usar secretos en CI

Si una solicitud realmente lee una variable de entorno cifrada, inyecta la clave del workspace desde el secret store de tu CI:

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

La resolución es perezosa: las solicitudes que no tocan secretos no necesitan clave. Los reportes y la salida de la terminal nunca imprimen valores descifrados: un secreto se muestra como {secret:<name>}, incluso en lo que un script registra en el log y en el mensaje de una aserción fallida. Ejecuta los workspaces no confiables dentro de un contenedor u otra frontera de aislamiento, porque el sandbox de scripting no está pensado para contener código malicioso.

Próximos pasos

• Consulta la referencia de la CLI fp para ver cada flag, formato de reporte y código de salida.
• Consulta Variables para los valores compartidos, locales, secretos y dinámicos.
• Consulta TLS y certificados para el comportamiento de los certificados del workspace.