CLI

Flatfile Command Line Interface

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 Command Line Interface (CLI) provides a set of tools to help you develop, deploy, and manage Listeners in your Flatfile environment.

Once listeners deployed are 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 the agents in your environment, you must authenticate with your Flatfile API key. You may do so in two ways:

1. Pass your credentials with your command via the the --token and --env flags
2. Making the FLATFILE_API_KEY and FLATFILE_ENVIRONMENT_ID variables available in your environment, via .env file in your project directory or other configurations

Available Commands

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

Development Workflow

A typical development workflow with the Flatfile CLI looks like this:

1. develop locally

   Configure your listener in local development using the develop command.

   This command runs your listener locally. It will respond to events in your configured environment just as it would once deployed, but changes to your listener will be watched so you can test changes in real-time.

2. deploy to the flatfile cloud

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

   To facilitate easy management, name your listener via the --slug/-s flag.

3. managing agents

   Use the list command to view deployed Agents and the delete command to remove them when needed.

4. download deployed agents

   Use the download to retrieve the code of a deployed Agent for inspection or modification.

Environment Isolation

It’s recommended to use an isolated environment for development to avoid conflicts with deployed Agents. The CLI will warn you if you’re working in an environment that already has deployed Agents.

Next Steps

• Learn more about Listeners
• Understand Events in Flatfile
• Explore Workbooks and Spaces