Save this content to: .claude/skills/flare/SKILL.md

# Flare CLI

The `flare` CLI lets you manage [Flare](https://flareapp.io) error tracking and performance monitoring from the terminal. Every Flare API endpoint has a corresponding command.

## Prerequisites

Check that the CLI is installed:

```bash
flare --version
```

If not installed:

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

Ensure Composer's global bin directory is in `PATH`:

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

## Authentication

`flare login` is interactive. **Recommend the user run it themselves** — don't try to drive it from inside an agent session.

```bash
# Default: browser-based OAuth (PKCE). Opens a browser to flareapp.io,
# user approves the requested scopes + team/project access, tokens are
# stored locally and refreshed transparently before each API call.
flare login

# Optionally suggest an editable workstation connection name.
flare login --name="Work laptop"

# Headless / SSH terminal: device-code flow. Prints a short user code +
# verification URL; the user enters the code on any other device.
flare login --device

# Automation/CI fallback: paste a personal access token or legacy API
# token instead of creating an interactive workstation connection.
flare login --token

# Remote logout revokes the OAuth connection before local cleanup.
flare logout
flare logout --all

# Offline cleanup when Flare is unavailable. This may leave the remote
# OAuth connection active.
flare logout --local-only

# Inspect the active OAuth issuer/API profile without exposing tokens.
flare auth
```

Credentials are stored by OAuth issuer and API base URL in `~/.flare/config.json`. The active API base comes from `FLARE_BASE_URL` and defaults to `https://flareapp.io/api`. Production, staging, and self-hosted profiles can coexist.

Personal access tokens can be generated at https://flareapp.io/account/api-access. Use them with `flare login --token` for scripts and CI, not as the normal workstation login.

If the CLI reports an expired, revoked, or unrefreshable OAuth session, suggest `flare login`. If it reports missing connection permissions, direct the user to the API Access URL printed by the CLI.

## Quick command reference

All commands output JSON. See [references/commands.md](references/commands.md) for full parameter details.

### User & team

```bash
# Who am I?
flare get-authenticated-user

# Get team details (includes members and roles)
flare get-team --team-id=1

# Remove a user from a team
flare remove-team-user --team-id=1 --user-id=42
```

### Projects

```bash
# List all projects (paginated)
flare list-projects

# Filter by name or team
flare list-projects --filter-name="My App" --filter-team-id=1

# Include team info
flare list-projects --include=team

# Create a project
flare create-project --field name="My App" --field team_id=1 --field stage=production --field technology=Laravel

# Delete a project
flare delete-project --project-id=123
```

### Errors

```bash
# List errors for a project
flare list-project-errors --project-id=123

# Filter by status, class, file, stage, or level
flare list-project-errors --project-id=123 --filter-status=open --filter-exception-class=RuntimeException

# Sort by most recent
flare list-project-errors --project-id=123 --sort=-last_seen_at

# Get error counts for a date range
flare get-project-error-count --project-id=123 --start-date="2025-01-01 00:00:00" --end-date="2025-01-31 23:59:59"

# Get occurrence counts for a date range
flare get-project-error-occurrence-count --project-id=123 --start-date="2025-01-01 00:00:00" --end-date="2025-01-31 23:59:59"
```

### Error actions

```bash
# Resolve an error
flare resolve-error --error-id=456

# Reopen a resolved error
flare unresolve-error --error-id=456

# Snooze forever
flare snooze-error --error-id=456 --field snooze_type=snooze_forever

# Snooze until a date
flare snooze-error --error-id=456 --field snooze_type=snooze_until --field snooze_until=2025-06-01T00:00:00Z

# Snooze for N more occurrences
flare snooze-error --error-id=456 --field snooze_type=snooze_number_of_occurrences --field snooze_number_of_occurrences=50

# Unsnooze
flare unsnooze-error --error-id=456
```

### Occurrences

```bash
# List occurrences for an error (includes frames, attributes, events, solutions)
flare list-error-occurrences --error-id=456

# Sort oldest first
flare list-error-occurrences --error-id=456 --sort=received_at

# Get a single occurrence by ID
flare get-error-occurrence --occurrence-id=789
```

### Performance monitoring

The `--type` parameter accepts: `routes`, `queries`, `jobs`, `commands`, `external-http`, `views`, `livewire-components`.

The `--filter-interval` parameter accepts: `1h`, `3h`, `6h`, `24h` (default), `48h`, `7d`, `14d`.

```bash
# Get a performance summary for a project (metrics + trends + top-10 slowest)
flare get-monitoring-summary --project-id=123

# List aggregated performance data for routes (paginated, sortable, filterable)
flare list-monitoring-aggregations --project-id=123 --type=routes --sort=-p95

# Filter aggregations — the operator is encoded in the parameter name (e.g. p95:>=), pass only the value
flare list-monitoring-aggregations --project-id=123 --type=queries --filter-p95=500

# Get time series data for a monitoring type
flare get-monitoring-time-series --project-id=123 --type=routes --filter-interval=7d

# Get details for a specific aggregation (e.g. a single route or query)
flare get-monitoring-aggregation --type=routes --uuid=<uuid> --include=parents,children

# List traces for an aggregation (slowest first by default)
flare list-aggregation-traces --type=routes --uuid=<uuid> --sort=slowest

# Get a full trace with span tree, events, resources, and contexts
flare get-trace --trace-id=<trace-id>
```

### Pagination

All list commands support pagination:

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

Response includes `meta` (current_page, total, last_page) and `links` (next/prev URLs).

## Common workflows

### Error triage

List open errors, categorize by exception class, resolve or snooze in batches. See [references/workflows.md](references/workflows.md) for the full triage workflow.

Quick version:

```bash
# 1. List open errors sorted by most recent
flare list-project-errors --project-id=123 --filter-status=open --sort=-last_seen_at

# 2. Review each error, resolve fixed ones
flare resolve-error --error-id=456

# 3. Snooze noisy but non-critical errors
flare snooze-error --error-id=789 --field snooze_type=snooze_forever
```

### Debug an error with local code

Fetch an occurrence, find application frames, then read the corresponding local files. See [references/workflows.md](references/workflows.md) for detailed steps.

Quick version:

```bash
# 1. Get the latest occurrence
flare list-error-occurrences --error-id=456 --sort=-received_at --page-size=1

# 2. Look at the frames where application_frame=true
# 3. Read the local file at the reported line number
# 4. Check attributes for request context, events for log trail, solutions for fixes
```

### Investigate slow performance

Get a performance overview, drill into slow aggregations, and inspect individual traces. See [references/workflows.md](references/workflows.md) for the full workflow.

Quick version:

```bash
# 1. Get the performance summary
flare get-monitoring-summary --project-id=123 --filter-interval=24h

# 2. List the slowest routes by p95
flare list-monitoring-aggregations --project-id=123 --type=routes --sort=-p95

# 3. Get details on a specific slow route
flare get-monitoring-aggregation --type=routes --uuid=<uuid> --include=children

# 4. List traces for that route, slowest first
flare list-aggregation-traces --type=routes --uuid=<uuid>

# 5. Inspect the slowest trace
flare get-trace --trace-id=<trace-id>
```

### Create a project and get API keys

Create a project via CLI, retrieve API keys, and verify errors are flowing. See [references/workflows.md](references/workflows.md) for the step-by-step guide.

## Output format

All commands return JSON. When presenting results to the user:

- **Errors**: Show as a table with columns: ID, exception class, message (truncated), status, occurrence count, last seen. Always include the `latest_occurrence_url_on_flare` link.
- **Occurrences**: Highlight application frames (where `application_frame` is `true`) — these are the user's code, not vendor code. Show the `relative_file` and `line_number`.
- **Solutions**: If `solutions` is non-empty, always present them prominently — they contain actionable fix suggestions.
- **Attributes**: Group by the `group` field (e.g., request, user, environment) when displaying context.
- **Events**: Show chronologically — they represent the execution trail leading to the error (queries, logs, jobs, etc.).
- **Flare URLs**: Include `latest_occurrence_url_on_flare` so the user can view the full error in the Flare dashboard.
- **Monitoring aggregations**: Show as a table with columns: name/label, p95, average, count, error rate. Highlight aggregations with high p95 or error rate.
- **Traces**: Show the span tree hierarchically. Highlight spans with the longest duration — these are the bottlenecks.