# Using the CLI


The Flare CLI lets you manage your errors, projects, and performance monitoring data directly from the terminal. List errors, resolve or snooze them, browse monitoring aggregations and traces, create projects, and more — without opening the Flare dashboard.

## Beta status

The Flare CLI is currently in beta. If you have any feedback or questions, please reach out to us at [support@flareapp.io](mailto:support@flareapp.io).

## Installation

Install the CLI globally via Composer:

```bash
composer global require spatie/flare-cli
```

Make sure Composer's global bin directory is in your `PATH`. You can find the path with:

```bash
composer global config bin-dir --absolute
```

Verify the installation:

```bash
flare --version
```

## Authentication

There are three ways to log the CLI in, all driven by the `flare login` command. Browser OAuth is the recommended path for laptops, device code covers headless or remote machines, and pasting a personal access token is still supported for CI or any environment where opening a browser isn't practical. Credentials are stored locally at `~/.flare/config.json`.

Every OAuth login creates a separate connection for that workstation. Logging in on another computer does not replace or sign out an existing connection. You can rename a connection, change its permissions, or revoke it independently from [Account → Connections](/account/connected-apps).

### Browser OAuth (recommended)

```bash
flare login
```

The CLI starts a local callback server, opens your browser to a Flare consent screen, and waits. Pick which scopes and which teams or projects this CLI may use, then approve.

![Flare CLI consent screen](/images/docs/cli-oauth-consent.png)

When you approve, the browser is redirected back to the local callback server and shows a short confirmation. The CLI exchanges the authorization code for an access token (with refresh token) and prints a success message in your terminal.

![Browser confirms login](/images/docs/cli-oauth-callback-success.png)

### Device code (for SSH, headless servers, CI)

```bash
flare login --device
```

The CLI prints a user code and a URL. Open the URL on any browser, sign in to Flare, and approve.

![Connect a device entry form](/images/docs/cli-device-user-code.png)

Following the URL with the `user_code` already in the query string skips the form and lands directly on the consent screen.

![Device consent screen](/images/docs/cli-device-consent.png)

After approving, the browser confirms the connection. The CLI's polling loop picks up the approval within a couple of seconds and prints the same success message.

![Device connected confirmation](/images/docs/cli-device-approved.png)

### Personal access token (paste-a-token)

```bash
flare login --token
```

The CLI prompts you to paste a token. Create one in [your account settings](/account/personal-access-tokens), scoped to the teams, projects, and permissions this CLI should have.

![Personal access tokens screen](/images/docs/cli-personal-access-tokens.png)

The create form lets you pick scopes (`read`, `write`, `admin`) and which teams or projects the token may access — the same picker as the OAuth consent screen above.

![Create a personal access token](/images/docs/cli-personal-access-token-create.png)

Legacy API tokens from `/account/api-tokens` also work as the token input here for backwards compatibility, but new integrations should use a personal access token. See the [API authentication reference](/docs/flare/general/using-the-api#authentication) for the full scope table.

### Checking your login and logging out

```bash
flare auth              # show the account the CLI is logged in as
flare logout            # remove the stored credentials
```

## Available commands

Every Flare API endpoint has a corresponding CLI command. Run `flare` to see all commands, or `flare <command> --help` for details on a specific command.

### Projects

- **`list-projects`** — List all projects. Supports filtering by name or team.
- **`create-project`** — Create a new project with a name, team, stage, and technology.
- **`delete-project`** — Delete a project by ID.

```bash
flare create-project --field name="My App" --field team_id=1 --field stage=production --field technology=Laravel
```

### Errors

- **`list-project-errors`** — List errors in a project. Supports filtering by status, exception class, file, stage, log level, and date ranges.
- **`get-project-error-count`** / **`get-project-error-occurrence-count`** — Get the number of unique errors or total occurrences in a date range.
- **`resolve-error`** / **`unresolve-error`** — Resolve or reopen an error.
- **`snooze-error`** / **`unsnooze-error`** — Snooze or unsnooze an error. You can snooze forever, until a date, or for a number of occurrences.

```bash
flare snooze-error --error-id=456 --field snooze_type=snooze_forever
```

### Error occurrences

- **`list-error-occurrences`** — List all occurrences of an error, including stack traces, context, and events.
- **`get-error-occurrence`** — Get a single occurrence with full details.

### Teams

- **`get-team`** — Get a team and its members.
- **`remove-team-user`** — Remove a user from a team.

### Performance Monitoring

- **`get-monitoring-summary`** — Get the monitoring dashboard summary for a project, including metrics and trends for routes, jobs, commands, and queries.
- **`list-monitoring-aggregations`** — List aggregations by type (`routes`, `queries`, `jobs`, `commands`, `external-http`, `views`, `livewire-components`). Supports filtering by p95, average, count, error rate, and free-text search.
- **`get-monitoring-time-series`** — Get time series data for graphing. Precision is auto-selected based on the interval.
- **`get-monitoring-aggregation`** — Get detailed metrics, trends, and relationship links for a single aggregation.
- **`list-aggregation-traces`** — List traces for an aggregation. Supports sorting by `slowest`, `fastest`, `latest`, or `oldest`.
- **`get-trace`** — Get the full span tree for a trace, including all span events, resources, and contexts.

```bash
flare get-monitoring-summary --project-id=123 --filter-interval=24h
flare list-monitoring-aggregations --project-id=123 --type=routes --filter-interval=7d --sort=-p95
flare list-aggregation-traces --type=routes --uuid=abc-123 --sort=slowest
```

### User

- **`get-authenticated-user`** — Get the currently authenticated user and their teams.

## Filtering and sorting

List commands support filtering and sorting through command options. Filters use `--filter-` prefixed options, and sorting uses the `--sort` option. Prefix a sort field with `-` to sort in descending order.

```bash
flare list-project-errors --project-id=123 \
  --filter-status=open \
  --filter-exception-class=RuntimeException \
  --sort=-last_seen_at
```

All list commands support pagination with `--page-number` and `--page-size` (maximum 30 items per page).

```bash
flare list-project-errors --project-id=123 --page-number=2 --page-size=20
```

## Output options

By default, the CLI displays results in a human-readable format. You can switch to structured output for scripting and automation:

- **`--json`** — Output raw JSON.
- **`--yaml`** — Output YAML.

```bash
flare list-projects --json
flare list-projects --json | jq '.data[].name'
```

## AI agent integration

The Flare CLI includes an [agent skill](/docs/flare/general/agent-skill) that teaches AI coding agents how to use the CLI to triage errors, investigate occurrences, monitor performance, and manage projects on your behalf.

```bash
flare install-skill
```