Get started with the fp CLI

fp is Fetchpier’s command-line client for terminals and CI. It uses the same request engine as the desktop app, so variable resolution, authentication, cookies, TLS, scripts, and tests behave the same way. The CLI is installed separately and has its own version number.

Requirements and installation

Install Node.js 22.19.0 or later, then install the package globally:

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

fp checks the Node.js version before doing anything else. On an older runtime it stops immediately with a message naming the version it needs and the one it found, and exits with a dedicated code (18) instead of failing later inside a dependency. npm also warns about the minimum at install time, but that warning is easy to miss on a global install.

The version command prints the product name, CLI version, and copyright notice. Run fp --help or fp <command> --help for help built into the installed version.

Create or open a workspace

Initialize a workspace in a new folder:

fp init my-api
cd my-api

fp init creates the Fetchpier workspace structure, a default environment holding a single baseUrl variable, a starter request (requests/example.http), and a .gitignore when none exists. It is the same layout the desktop app creates, so the environment that a run falls back to (default) already exists. It ends by printing the command to run next — fp run --workspace my-api, or fp run when you initialize the current folder — which works as printed from the same directory. You can also use any workspace already created by the desktop application.

Run requests

Run every request in the workspace — the .http files under requests/, recursively:

fp run

With no path the CLI runs that same set from any directory: a subfolder of the workspace, or from outside it with --workspace or FETCHPIER_WORKSPACE. A folder with no .http file stops the run with exit code 19, because a run that sends nothing is not a success.

Run one file:

fp run requests/auth/login.http

Run every .http file below a folder:

fp run requests/smoke --env staging

fp run is the shorter alias of fp request run. Explicit paths are relative to the current directory, like any other command-line tool; if a path does not exist there but does inside the workspace, the error suggests the path to type. Files are run in deterministic path order and only the first request in each .http file executes; the CLI prints an informational notice when a file contains additional requests.

Select the workspace

The CLI resolves a workspace in this order:

1. --workspace <path> (or -w);
2. the FETCHPIER_WORKSPACE environment variable;
3. the nearest parent folder containing .fetchpier/, walking upward from the current directory.

For reproducible automation, set --workspace or FETCHPIER_WORKSPACE explicitly.

Select the environment

The environment is resolved independently:

1. --env <name> (or -e);
2. FETCHPIER_ENV;
3. the environment folder named default.

Matching uses the filesystem-safe environment folder name, case-insensitively. This is the handle shown by fp env list, not the display label or internal identifier.

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

The CLI never reads or changes the environment last selected in the desktop app. This separation keeps CI behavior independent of a developer’s UI state. fp env switch is not available.

Override variables for one run

Use repeatable --env-var KEY=VALUE options for values supplied by the caller:

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

A script that later sets the same variable wins over --env-var from that point on.

Unresolved {{variable}} references remain literal and produce a warning, and a {{$env.NAME}} that neither the workspace’s .env nor the process environment defines is sent empty, also with a warning. Neither fails the run by itself, but the warning makes a mistyped or missing variable visible before the server’s rejection is the only clue; assert on the response when a missing credential must fail the pipeline. Dynamic variables such as {{$guid}} resolve identically to the desktop.

Pass values between requests

A value a script sets with fp.environment.set (or removes with fp.environment.remove) applies to every later request of the same run, so a token stored by a login request reaches the authenticated call that follows. By default these changes live for the run only and nothing is written to the workspace. Add --persist-env to save them to the machine’s local values, exactly as the desktop does:

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

Proxies and timeouts

Each request has a 30-second timeout by default, the same as the desktop; change it with --timeout <ms>, or disable it with --timeout 0. The CLI honours HTTPS_PROXY, HTTP_PROXY and NO_PROXY; --proxy <url> overrides them and --no-proxy ignores them for one run. See fp CLI reference for the details.

Use secrets in CI

If a request actually reads an encrypted environment variable, inject the workspace key through the CI secret store:

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

Resolution is lazy: requests that do not touch secrets need no key. Reports and terminal output never print decrypted values: a secret shows as {secret:<name>}, including in what a script logs and in a failed assertion’s message. Run untrusted workspaces inside a container or another isolation boundary because the scripting sandbox is not intended to contain malicious code.

Next steps

• See fp CLI reference for every flag, report format, and exit code.
• See Variables for shared, local, secret, and dynamic values.
• See TLS and certificates for workspace certificate behavior.