> ## Documentation Index
> Fetch the complete documentation index at: https://flatfile.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

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

The Flatfile Command Line Interface (CLI) provides tools to develop, deploy, and manage [Listeners](https://flatfile.com/docs/core-concepts/listeners.md) in your Flatfile environment.

> [!NOTE]
>
> Once listeners are deployed and hosted on Flatfile's secure cloud, they are
> called Agents.

## Installation

```bash theme={null}
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](https://platform.flatfile.com/dashboard/keys-and-secrets)".

> [!NOTE]
>
> **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:

```bash theme={null}
# .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:

```bash theme={null}
npx flatfile develop --token YOUR_API_KEY --env YOUR_ENV_ID
```

### Regional Servers

For improved performance and compliance, Flatfile supports regional deployments:

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

Set your regional URL in `.env`:

```bash theme={null}
FLATFILE_API_URL=platform.eu.flatfile.com/api
```

> [!TIP]
>
> 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

> [!WARNING]
>
> 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.

```bash theme={null}
npx flatfile develop [file-path]
```

**Options**

| Option | Description |
| - | - |
| `[file-path]` | Path to listener file (auto-detects if not provided) |
| `--token` | Flatfile API key |
| `--env` | Environment ID |

**Features**

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

**Example output**

```bash theme={null}
> 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.

```bash theme={null}
npx flatfile deploy [file-path] [options]
```

**Options**

| Option | Description |
| - | - |
| `[file-path]` | Path to listener file (auto-detects if not provided) |
| `--slug`, `-s` | Unique identifier for the agent |
| `--ci` | Disable interactive prompts for CI/CD |
| `--token` | Flatfile API key |
| `--env` | Environment ID |

**File detection order**

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

**Examples**

```bash theme={null}
# 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:

```bash theme={null}
npx flatfile deploy --slug agent-one
npx flatfile deploy --slug agent-two
```

> [!NOTE]
>
> Without a slug, the CLI updates your existing agent or creates one with slug
> `default`.

***

### agents list

Display all deployed agents in your environment.

```bash theme={null}
npx flatfile agents list
```

Shows each agent's:

* Agent ID
* Slug
* Deployment status
* Last activity

***

### agents download

Download a deployed agent's source code.

```bash theme={null}
npx flatfile agents download <slug>
```

**Use cases**

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

> [!TIP]
>
> Use `agents list` to find the agent slug you need.

***

### agents delete

Remove a deployed agent.

```bash theme={null}
npx flatfile agents delete <slug>
```

**Options**

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

***

## Related Resources

* [Listeners](https://flatfile.com/docs/core-concepts/listeners.md) - Core concept documentation
* [Events](https://flatfile.com/docs/reference/events.md) - Event system reference