CLI Reference

Command line interface for developing, deploying, and managing Flatfile Agents

The Flatfile Command Line Interface (CLI) provides a comprehensive set of 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

The Flatfile CLI is available as an npm package and can be invoked with npx.

npx flatfile@latest <command>

Authentication

To interact with agents in your environment, you must authenticate with your Flatfile API key. You can do this in two ways:

1. Environment variables - Set FLATFILE_API_KEY and FLATFILE_ENVIRONMENT_ID in your environment or .env file:

   FLATFILE_API_KEY=your_api_key_here
   FLATFILE_ENVIRONMENT_ID=your_environment_id_here
   

2. Command flags - Pass credentials directly with the --token and --env flags:

   npx flatfile develop --token YOUR_API_KEY --env YOUR_ENV_ID
   

Available Commands

Command	Description
develop	Run your project as a local listener for development
deploy	Deploy your project as a Flatfile Agent
agents list	List all deployed Agents in your environment
agents download	Download an agent from your environment
agents delete	Delete an Agent from your environment

Development Workflow

A typical development workflow with the Flatfile CLI follows these steps:

1. Develop Locally

   Use the develop command to run your listener locally with live reloading for rapid iteration.

2. Deploy to Flatfile Cloud

   When ready, use the deploy command to deploy your listener as an Agent.

3. Manage Agents

   Use the agents commands to list, download, or delete deployed Agents as needed.

---

develop

Run your project as a local listener with automatic file watching and live reloading.

npx flatfile develop [file-path]

Options

Option	Description
[file-path]	Path to your listener file (optional, auto-detects common paths)
--token	Your Flatfile API key
--env	Your environment ID

Features

• Live reloading - File changes are detected and reflected immediately
• Real-time logging - Detailed HTTP request logs with timing and status
• Event streaming - Low-latency event delivery (10-50ms) similar to production
• Event handling visibility - See which events are being processed and their handlers

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"})

Use an isolated environment for development to avoid conflicts with deployed Agents. The CLI will warn you when working in an environment that already has deployed Agents.

---

deploy

Deploy your listener as a Flatfile Agent to the secure cloud.

npx flatfile deploy [file-path] [options]

Options

Option	Description
[file-path]	Path to your listener file (optional, auto-detects)
--slug, -s	Unique identifier for the agent
--ci	Disable interactive prompts for CI/CD pipelines
--token	Your Flatfile API key
--env	Your environment ID

Auto-Detection

The CLI automatically looks for your listener file in this order:

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

Example Usage

# Basic deployment
npx flatfile deploy

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

# Deploy specific file in CI mode
npx flatfile deploy ./src/listener.ts --ci

Example Output

> npx flatfile deploy
✔ Code package compiled to .flatfile/build.js
✔ Code package passed validation
✔ Environment "production" selected
✔ Event listener deployed and running on your environment "production". us_ag_1234

Multiple Agents

Deploy multiple agents to the same environment by specifying unique slugs:

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

If you don’t specify a slug and have only one or no deployed agents, the CLI will update your existing agent or create your first agent with the slug default.

CI/CD Integration

Use the --ci flag in automated environments:

• Disables interactive prompts
• Returns clear error messages if configuration is missing
• Skips TypeScript configuration checks

---

agents list

List all deployed agents in your environment.

npx flatfile agents list

This command displays all agents with their:

• Agent ID
• Slug
• Deployment status
• Last activity

---

agents download

Download the source code of a deployed agent to your local machine.

npx flatfile agents download <slug>

Parameters

Parameter	Description
<slug>	The slug or ID of the agent to download

Use Cases

• Examine deployed agent code
• Make modifications to existing agents
• Back up agent source code
• Debug issues with deployed agents

Use the agents list command to get the slug of the agent you want to download.

---

agents delete

Remove a deployed agent from your Flatfile environment.

npx flatfile agents delete <slug>

Parameters

Parameter	Description
<slug>	The slug or ID of the agent to delete

Options

Option	Description
--agentId, -ag	Use agent ID instead of slug

---

Regional Servers

Flatfile supports regional deployments for improved performance and compliance.

Available Regions

Region	Platform URL	API URL
UK	platform.uk.flatfile.com	platform.uk.flatfile.com/api
EU	platform.eu.flatfile.com	platform.eu.flatfile.com/api
AU	platform.au.flatfile.com	platform.au.flatfile.com/api
CA	platform.ca.flatfile.com	platform.ca.flatfile.com/api

Configuration

Set your regional API URL in your .env file:

FLATFILE_API_URL=platform.eu.flatfile.com/api

Contact support to enable regional server deployment for your account.

---

Environment Isolation

For optimal development experience:

• Use separate environments for development and production
• Avoid running local listeners in environments with deployed agents
• Multiple agents in the same environment can interfere with each other

The CLI will warn you when working in an environment that already has deployed agents to help prevent conflicts.

---

Related Resources

• Listeners - Understand the core concept
• Events - Learn about the event system