Skip to main content
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

​
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:
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:

​
Regional Servers

For improved performance and compliance, Flatfile supports regional deployments: Set your regional URL in .env:
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.
Options Features
  • Live reloading on file changes
  • Real-time HTTP request logging
  • Low-latency event streaming (10-50ms)
  • Event handler visibility
Example output

​
deploy

Deploy your listener as a Flatfile Agent.
Options File detection order
  1. ./index.js
  2. ./index.ts
  3. ./src/index.js
  4. ./src/index.ts
Examples
Multiple agents Deploy multiple agents to the same environment using unique slugs:
Without a slug, the CLI updates your existing agent or creates one with slug default.

​
agents list

Display all deployed agents in your environment.
Shows each agent’s:
  • Agent ID
  • Slug
  • Deployment status
  • Last activity

​
agents download

Download a deployed agent’s source code.
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.
Options