Configuration

The CLI reads its settings from four places: command-line flags, environment variables, the project's formfeed.json and your user config.

Precedence

When the same setting is given in several places, the first one wins:

1. Command-line flags (--api-key, --workspace, --region, --base-url)
2. Environment variables (FORMFEED_API_KEY, …)
3. formfeed.json in the project, searched upwards from the current directory
4. The user config written by formfeed login and formfeed config set

Not every setting can be given in every place:

Setting	Flag	Environment	formfeed.json	User config	Without any
API key	--api-key	FORMFEED_API_KEY		apiKey	Commands that need the API fail with exit code 3
Base URL	--base-url	FORMFEED_BASE_URL		baseUrl	The host of the region
Region	--region	FORMFEED_REGION	region	region	eu
Workspace	--workspace	FORMFEED_WORKSPACE	workspace	workspace	none

The API key decides the workspace. A key belongs to exactly one workspace, and every command that calls the API acts on that one. The workspace setting is a label: init --workspace records it in formfeed.json so the team knows which workspace the project belongs to, and config list shows it, but no command sends it to the API or compares it with the key. To work on another workspace, use a key of that workspace. formfeed whoami shows which workspace the current key belongs to.

formfeed config list prints the API key (its first 12 characters), base URL, workspace and region the CLI would use, the formfeed.json it found and where the user config is. It does not say which of the places above each value came from.

formfeed.json

{
  "workspace": "fennlor/production",
  "region": "eu",
  "templatesDir": "templates",
  "partialsDir": "partials",
  "filesDir": "files",
  "engine": "jinja2",
  "ignore": ["**/drafts/**"],
  "types": { "lang": "ts", "out": "src/formfeed.d.ts" },
  "pull": { "redact": ["customer.*", "iban"] }
}

formfeed init writes the file with the defaults below. The folder that holds it is the project root; the CLI finds it from any folder below.

Field	Default	Meaning
workspace	none	org-slug/workspace-slug the project belongs to; recorded for people, not used to choose a workspace (see above)
region	eu	eu or us: the API host the CLI talks to (api-eu.formfeed.dev or api-us.formfeed.dev)
templatesDir, partialsDir, filesDir	templates, partials, files	Folders relative to formfeed.json; filesDir mirrors the workspace file library. See Project layout
engine	jinja2	Template language of templates whose template.json names none, and of templates templates push creates without one (jinja2, liquid or handlebars)
ignore	["**/drafts/**"]	Glob patterns, relative to the project root, for template folders that templates push leaves out when it pushes all templates (templates/wip-*); ** spans folders and a name without / matches at any depth. A folder named on the command line is pushed anyway, and --dry-run lists the left-out folders as ignored.
types	none	Defaults of formfeed types: lang (ts or python, default ts), out (the file, relative to the project root; default formfeed.d.ts or formfeed_templates.py) and sdkModule (the module the TypeScript file augments, default @formfeed/sdk); see Typed template data
pull	none	Defaults of formfeed renders pull: redact, the data paths redacted in every pulled data set; see Reproduce a failed render

Commit formfeed.json. It contains no secrets.

Environment variables

Variable	Purpose
FORMFEED_API_KEY	API key; used instead of the stored login. The usual way to authenticate in CI.
FORMFEED_WORKSPACE	Overrides workspace (a label; the key decides the workspace)
FORMFEED_REGION	Overrides region (eu or us)
FORMFEED_BASE_URL	API base URL including /v1, used instead of the region's address (only for an address other than the public API); wins over the region
FORMFEED_CONFIG_DIR	Directory of the user config, instead of the platform default
CI	When set to any value, formfeed login opens no browser (same as --ci) and long commands draw no progress line
NO_COLOR, FORCE_COLOR	NO_COLOR turns colours off; FORCE_COLOR turns them on even when the output is not a terminal (0 or false turns them off)
PDFMONKEY_API_KEY	PDFMonkey key for formfeed import pdfmonkey, instead of --key
APITEMPLATE_API_KEY	apitemplate.io key for formfeed import apitemplate, instead of --key
APITEMPLATE_REGION	apitemplate.io region for formfeed import apitemplate, instead of --source-region (default when neither is set)

The testing helpers read FORMFEED_API_KEY, FORMFEED_REGION and FORMFEED_BASE_URL as well, and FORMFEED_REQUIRE_API=1 makes their API-backed matcher fail instead of skipping when no key is set. The CLI itself does not read FORMFEED_REQUIRE_API.

User config

The user config holds the settings that belong to you, not to a project: usually the key formfeed login stored. It lives in ~/.config/formfeed/config.json (or $XDG_CONFIG_HOME/formfeed/config.json) on macOS and Linux, %APPDATA%\formfeed\config.json on Windows, or config.json in FORMFEED_CONFIG_DIR. The CLI writes it so that only your user can read it.

formfeed config set region us
formfeed config get region        # us
formfeed config get apiKey        # the first 12 characters only

formfeed config get|set <key> reads and writes apiKey, baseUrl, workspace and region; another key name is refused with exit code 2. config set stores the value as given and does not check it.