Skip to main content

Install and log in

Install​

The CLI is the npm package formfeed and needs Node.js 22 or later.

# run it without installing
npx formfeed --help

# or install it globally
npm install -g formfeed
formfeed --version

In a project that uses it in scripts or CI, add it as a dev dependency so everyone gets the same version: npm install -D formfeed. npx formfeed then runs that version.

The commands that work offline (init without --from-workspace, dev, validate, test, einvoice, types inside a project) need no account. Everything else needs an API key: log in once, or set FORMFEED_API_KEY.

Log in​

formfeed login
  1. The CLI prints the address of the app's Connect the command line page and a code such as ABCD-EFGH, opens the page with the code filled in, and waits. The code is valid for 10 minutes.
  2. Sign in to the app if you are not, check that the code is the one in your terminal, choose the workspace, and click Connect. Refuse ends the login in the terminal.
  3. The CLI receives an API key and stores it. It prints the organisation and workspace it was approved for.

The key is a live key (ff_live_…) named Formfeed CLI on <your machine's name>, for the workspace you chose, with the scopes of your role in the organisation. It appears under API keys in the app and can be revoked there like any other. Because it is a live key, renders made with it (formfeed render, the true render of formfeed dev, ci preview) count against your plan. For free test renders, create a test key under API keys and store it with --api-key.

  • --no-browser keeps the browser closed; open the printed address yourself, for example on a server or in an SSH session. --ci, or a set CI variable, does the same.
  • formfeed login --api-key ff_test_… (or formfeed login ff_test_…) stores an existing key instead. The CLI checks it with GET /account first: an unknown or revoked key fails with exit code 3. A key without the account:read scope is stored anyway, but formfeed whoami cannot show its workspace.
  • formfeed whoami shows the organisation, workspace and region of the stored key, the plan with the units used of those included in the current period, and whether the key is a test or live key.
  • formfeed logout removes the key from the user config. The key stays valid until you revoke it under API keys.

The key is stored in the user config, a file only your user can read: ~/.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 when that is set. login also writes the region and, when you passed one, the base URL there.

In CI, do not log in. Set FORMFEED_API_KEY from your secret store; it takes precedence over the stored login.

Bind a folder to a workspace​

formfeed init --from-workspace

This writes formfeed.json, creates templates/ and partials/, and pulls every template of the key's workspace: the published version, or the latest draft of a template that was never published. It also pulls the organisation's shared partials, so templates that include one validate at once. It needs a key with template:read.

  • Without --from-workspace, init creates a hello starter template instead and needs no key.
  • Pass a directory to create the project somewhere else: formfeed init my-templates.
  • --engine liquid (or jinja2, handlebars) sets the template language of new templates in formfeed.json; the default is jinja2.
  • --workspace fennlor/production records the workspace in formfeed.json as a note for the team. It does not choose a workspace: the API key does.
  • init refuses a folder that already has a formfeed.json (exit code 2).

Continue with Templates as code, or see Configuration and the project layout.