The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!

The Flatfile CLI provides a suite of tools to help you develop and deploy Listeners to Flatfile.

Listeners are at the core of the Flatfile ecosystem, they are responsible for picking up on Events and responding to them accordingly.

Agents are listeners deployed server-side on Flatfile’s secure cloud.

When developing with Flatfile, listeners can deployed to Flatfile on every change, or they can run directly on your machine.

​
Commands

The Flatfile CLI provides the following commands:

CommandDescription
developRun your project as a local listener
deployDeploy your project as a Flatfile Agent
listList deployed Agents in an environment
deleteDelete an Agent

​
Before you begin

You can add a .env file to bypass having to enter your API Key when running the develop command.

FLATFILE_API_KEY=sk_123456

​
Develop

Run npx flatfile develop from terminal to launch a local listener. As your code changes, file changes are detected and will be reflected immediately.

Add the file name to the command: npx flatfile develop path-to-file if you’re not running an index file.

  1. In your terminal, you’ll see a detailed log of each HTTP request made within a listener. It includes the request timing and status, enabling tracking and debugging of HTTP operations.
  2. A pub/sub stream system will deliver Events with a latency of approximately 10-50ms. This provides a local development experience closely resembling the production environment speed.
  3. Events that are being processed will be shown, along with their respective handlers. You can then respond to those Events accordingly.
> 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"})

​
Shared environments

It is highly recommended to utilize an isolated environment when developing with the local listener. That’s why the CLI is warning you when working in an environment that already has a deployed agent.

Check for existing agents

Create a new isolated environment in dashboard

​
More details

Having deployed code running at the same time within the same development environment can lead to interference, potentially resulting in a recursive loop and undesirable consequences for your local listener. To avoid such complications, it’s advisable to keep your local environment separate from any deployed code. This ensures optimal performance and helps maintain a stable development environment.

Check for agents