# Getting started

The Frontline CLI ships two binaries that share the same API key store:

- **`frontline`** — Public REST API client: agents, workflows, billing, tables, objects, tools, raw GETs.
- **`max`** — Max chat & admin client: send messages, manage conversations, REPL.


## Install

```bash
npm install -g @getfrontline/cli
```

Or run any command on demand:

```bash
npx @getfrontline/cli --help
```

Requires Node **18+**.

## First-time setup

```bash
frontline auth login <api-key>
frontline auth whoami
```

Generate your API key from the Frontline app: click your user name in the bottom-left of the sidebar → **Settings**, then choose **Bring your own Agent** (for a personal `USER` key) or **Developer** (for an account-level `GENERAL` key). See [Authentication](/cli/authentication) for the full breakdown and which scope each command needs.

The same login also authenticates `max`:

```bash
max auth whoami
```

## Profiles

You can store multiple API keys side-by-side and switch between them:

```bash
frontline auth profiles list             # all saved profiles + active one
frontline auth profiles use prod         # switch active profile
frontline auth logout                    # remove active profile
frontline auth logout --profile staging  # remove a specific profile
```

Every command accepts a one-off `--profile <name>` override for scripting and CI.

## Output formats

All `frontline` commands print **JSON to stdout by default** so they pipe into `jq` and other tools cleanly. Opt into human-readable output with:

- `--pretty` — key/value blocks, spinners, icons.
- `--table` — tabular rendering for list endpoints.


Errors always go to **stderr** in human form; in default JSON mode they also appear on stdout as structured JSON so scripts can branch on `ok`/`error` fields.

## Global flags

Available on every `frontline` command:

| Flag | Purpose |
|  --- | --- |
| `--api-key <key>` | Override the stored API key for one call. |
| `--profile <name>` | Use a specific saved profile. |
| `--debug` | Verbose request/response logs. |
| `--pretty` | Human-readable output. |
| `--table` | Tabular output for list endpoints. |


`max` exposes a similar set: `--api-key`, `--profile`, `--base-url`, `--debug`, `--pretty`, `--json`.

## Your first call

```bash
frontline agents list --table
```

Or with the Max binary:

```bash
max "Hola Max"
```

For the full command reference, browse the **frontline** and **max** groups in the sidebar.

## Claude Code skills

Optional: install Frontline skills into Claude Code (auto-detected on `npm install`):

```bash
frontline setup --claude-skills          # install new skills
frontline setup --claude-skills --force  # overwrite existing
```

## Troubleshooting

| Symptom | Likely cause |
|  --- | --- |
| **"No API key found"** | Run `frontline auth login <key>`. |
| **"Missing or invalid API key"** | Key expired or revoked. Create a new one in **Settings → Bring your own Agent** (personal) or **Settings → Developer** (account). |
| **`401 Unauthorized`** on a write | You're using a `GENERAL` key on a `USER`-only endpoint (e.g. creating an agent, publishing a flow). Generate a personal key under **Bring your own Agent**. |
| **"Request timed out"** | Network issue or backend slow. Retry. |
| **`429 Too Many Requests`** | Rate limit (1000 req/min per account). Back off. |
| **CLI outdated error** | Upgrade with `npm i -g @getfrontline/cli@latest`. |


## Need help using the platform itself?

These docs cover the **CLI**. For walkthroughs of the Frontline app — setting up channels, configuring agents in the UI, billing in-product, troubleshooting end-user flows — head to [https://help.getfrontline.ai](https://help.getfrontline.ai).