The Flatfile Command Line Interface (CLI) provides tools to develop, deploy, and manage Listeners in your Flatfile environment.

Once listeners are deployed and hosted on Flatfile’s secure cloud, they are called Agents.

​
Installation

npx flatfile@latest <command>

​
Configuration

​
Authentication

The CLI requires your Flatfile API key and Environment ID, provided either in Environment variables (ideally in a .env file) or as command flags. You can find your API key and Environment ID in your Flatfile dashboard under “API Keys and Secrets”.

Recommended approach: Use a .env file in your project root for secure, convenient, and consistent authentication. If you’re using Git, make sure to add .env to your .gitignore file.

Using .env file

Create a .env file in your project root:

# .env file
FLATFILE_API_KEY=your_api_key_here
FLATFILE_ENVIRONMENT_ID=your_environment_id_here

This approach keeps credentials out of your command history and makes it easy to switch between environments.

Using command flags

For one-off commands or CI/CD environments:

npx flatfile develop --token YOUR_API_KEY --env YOUR_ENV_ID

​
Regional Servers

For improved performance and compliance, Flatfile supports regional deployments:

RegionAPI URL
UKplatform.uk.flatfile.com/api
EUplatform.eu.flatfile.com/api
AUplatform.au.flatfile.com/api
CAplatform.ca.flatfile.com/api

Set your regional URL in .env:

FLATFILE_API_URL=platform.eu.flatfile.com/api

Contact support to enable regional server deployment for your account.

​
Development Workflow

1

Develop Locally

Use develop to run your listener locally with live reloading

2

Deploy to Production

Use deploy to push your listener to Flatfile’s cloud as an Agent

3

Manage Agents

Use agents commands to list, download, or delete deployed agents

Use separate environments for development and production to avoid conflicts. The CLI will warn you when working in an environment with existing agents.

​
Commands

​
develop

Run your listener locally with automatic file watching and live reloading.

npx flatfile develop [file-path]

Options

OptionDescription
[file-path]Path to listener file (auto-detects if not provided)
--tokenFlatfile API key
--envEnvironment ID

Features

  • Live reloading on file changes
  • Real-time HTTP request logging
  • Low-latency event streaming (10-50ms)
  • Event handler visibility

Example output

> npx flatfile develop
✔ 1 environment(s) found for these credentials
✔ Environment "development" selected
ncc: Version 0.36.1
ncc: Compiling file index.js into CJS
  ✓ 427ms      GET    200 https://platform.flatfile.com/api/v1/subscription 12345

 File change detected. 🚀
  ✓ Connected to event stream for scope us_env_1234
 ▶ commit:created  10:13:05.159 AM us_evt_1234
 ↳ on(**, {})
 ↳ on(commit:created, {"sheetSlug":"contacts"})

​
deploy

Deploy your listener as a Flatfile Agent.

npx flatfile deploy [file-path] [options]

Options

OptionDescription
[file-path]Path to listener file (auto-detects if not provided)
--slug, -sUnique identifier for the agent
--ciDisable interactive prompts for CI/CD
--tokenFlatfile API key
--envEnvironment ID

File detection order

  1. ./index.js
  2. ./index.ts
  3. ./src/index.js
  4. ./src/index.ts

Examples

# Basic deployment
npx flatfile deploy

# Deploy with custom slug
npx flatfile deploy --slug my-agent

# CI/CD deployment
npx flatfile deploy ./src/listener.ts --ci

Multiple agents

Deploy multiple agents to the same environment using unique slugs:

npx flatfile deploy --slug agent-one
npx flatfile deploy --slug agent-two

Without a slug, the CLI updates your existing agent or creates one with slug default.

​
agents list

Display all deployed agents in your environment.

npx flatfile agents list

Shows each agent’s:

  • Agent ID
  • Slug
  • Deployment status
  • Last activity

​
agents download

Download a deployed agent’s source code.

npx flatfile agents download <slug>

Use cases

  • Examine deployed code
  • Modify existing agents
  • Back up source code
  • Debug deployment issues

Use agents list to find the agent slug you need.

​
agents delete

Remove a deployed agent.

npx flatfile agents delete <slug>

Options

OptionDescription
--agentId, -agUse agent ID instead of slug