Flare

Flare CLI

The flare CLI lets you manage Flare error tracking and performance monitoring from the terminal. Every Flare API endpoint has a corresponding command.

Prerequisites

Check that the CLI is installed:

flare --version

If not installed:

composer global require spatie/flare-cli

Ensure Composer's global bin directory is in PATH:

composer global config bin-dir --absolute

Authentication

# Log in — you'll be prompted for your API token
flare login

# Log out
flare logout

Get your API token at https://flareapp.io/settings/api-tokens.

If any command returns a 401 error, the token is invalid or expired. Run flare login again.

Quick command reference

All commands output JSON. See references/commands.md for full parameter details.

User & team

# 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

# 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

# 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

# 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

# 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.

# 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:

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 for the full triage workflow.

Quick version:

# 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 for detailed steps.

Quick version:

# 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 for the full workflow.

Quick version:

# 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 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.

Command reference

Complete reference for all flare CLI commands. Every command outputs JSON.

User

get-authenticated-user

Get the currently authenticated user.

flare get-authenticated-user

Parameters: None

Response fields: id, name, email, photo_url, teams[] (each with id, name)

---

Projects

list-projects

List all projects (paginated).

flare list-projects

Optional parameters:

Response: Paginated. Each project has: id, name, slug, group_name, stage, technology, api_key, api_public_key, unresolved_errors_count, errors_last_7_days_count, errors_previous_7_days_count, last_error_received_at, protect_against_spikes, spike_protection_active_until, team (when included)

create-project

Create a new project.

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

Required body fields (via `--field`):

Optional body fields:

Response: The created project object with api_key and api_public_key.

delete-project

Delete a project.

flare delete-project --project-id=123

Required parameters:

Response: 204 No Content

---

Errors

list-project-errors

List all errors within a project (paginated).

flare list-project-errors --project-id=123

Required parameters:

Optional parameters:

Response: Paginated. Each error has: id, slug, exception_class, exception_message, exception_code, file, line_number, class, method, status (open/resolved), level, stage, entry_point, entry_point_type (web/cli/queue), occurrence_count, affected_user_count, first_seen_at, last_seen_at, resolved_at, resolved_by_user_name, snooze_type, snoozed_at, snoozed_until, language, framework, language_version, framework_version, application_version, latest_occurrence_has_solutions, latest_occurrence_url_on_flare, assignees[]

get-project-error-count

Get the number of unique errors in 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"

Required parameters:

Response: { "count": integer }

get-project-error-occurrence-count

Get the number of error occurrences in 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"

Required parameters:

Response: { "count": integer }

resolve-error

Mark an error as resolved.

flare resolve-error --error-id=456

Required parameters:

Response: The updated error object with status: "resolved".

unresolve-error

Reopen a resolved error.

flare unresolve-error --error-id=456

Required parameters:

Response: The updated error object with status: "open".

snooze-error

Snooze an error to suppress notifications.

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

Required parameters:

Required body fields (via `--field`):

Conditional body fields:

Response: The updated error object.

unsnooze-error

Unsnooze a snoozed error.

flare unsnooze-error --error-id=456

Required parameters:

Response: The updated error object.

---

Error occurrences

list-error-occurrences

List all occurrences of a specific error (paginated). Each occurrence includes full stack trace, context, and solutions.

flare list-error-occurrences --error-id=456

Required parameters:

Optional parameters:

Response: Paginated. Each occurrence has: id, error_id, received_at, entry_point, exception_class, exception_message, exception_code, application_path, application_version, notifier_client_name, language_version, framework_version, stage, entry_point_type, plus nested:

• `frames[]` — stack trace frames: file, relative_file, line_number, class, method, code_snippet[], application_frame (boolean)
• `attributes[]` — context items: group, key, value (groups: request, user, environment, etc.)
• `events[]` — execution trail: id, name, level, meta_data, received_at, microtime
• `solutions[]` — fix suggestions: id, title, description, links[], action_description, is_runnable
• `error` — the parent error object

get-error-occurrence

Get a single error occurrence by ID.

flare get-error-occurrence --occurrence-id=789

Required parameters:

Response: Same structure as a single item in list-error-occurrences.

---

Performance monitoring

Shared parameters

`--type` (required for most monitoring commands): routes, queries, jobs, commands, external-http, views, livewire-components

`--filter-interval` (optional, default 24h): 1h, 3h, 6h, 24h, 48h, 7d, 14d

get-monitoring-summary

Get a performance overview for a project: metrics and trends for routes, jobs, commands, and queries, plus the top-10 slowest routes and queries.

flare get-monitoring-summary --project-id=123

Required parameters:

Optional parameters:

Response: Metrics and trends per type (routes, jobs, commands, queries), plus top_slowest_routes and top_slowest_queries arrays (each up to 10 items).

list-monitoring-aggregations

List aggregated performance data for a monitoring type (paginated, sortable, filterable).

flare list-monitoring-aggregations --project-id=123 --type=routes --sort=-p95

Required parameters:

Optional parameters:

The comparison operator is encoded in the API parameter name (e.g. filter[p95:>=] → --filter-p95). Pass only the numeric value: --filter-p95=500.

Response: Paginated. Each aggregation has: uuid, type, label, p50, p90, p95, p99, average, count, error_rate, trend.

get-monitoring-time-series

Get time series data for a monitoring type.

flare get-monitoring-time-series --project-id=123 --type=routes

Required parameters:

Optional parameters:

Response: precision (minute, hour, or day) and data[] — array of time series points.

get-monitoring-aggregation

Get details for a specific aggregation (e.g. a single route, query, or job).

flare get-monitoring-aggregation --type=routes --uuid=<uuid>

Required parameters:

Optional parameters:

Response: Aggregation detail with uuid, type, label, percentiles, count, error_rate, trend, interval, parent/child links. When --include is used, includes parents[] and/or children[] arrays.

list-aggregation-traces

List traces for a specific aggregation (paginated).

flare list-aggregation-traces --type=routes --uuid=<uuid>

Required parameters:

Optional parameters:

Response: Paginated. Each trace summary has: trace_id, started_at, duration_ms.

get-trace

Get a full trace with its span tree.

flare get-trace --trace-id=<trace-id>

Required parameters:

Response: Full span tree with events, resources, and contexts for each span.

---

Teams

get-team

Get a team and its members.

flare get-team --team-id=1

Required parameters:

Response: id, name, slug, users[] (each with user_id, team_id, user_email, role — one of admin, owner, member)

remove-team-user

Remove a user from a team.

flare remove-team-user --team-id=1 --user-id=42

Required parameters:

Response: 200 OK

Workflows

Detailed workflows for common Flare CLI tasks.

Error triage

Systematically work through open errors, categorize them, and take action.

Step 1: Get an overview

# List open errors, most recent first
flare list-project-errors --project-id=123 --filter-status=open --sort=-last_seen_at --page-size=30

Present results as a table: ID, exception class, message (truncated to ~60 chars), occurrence count, last seen.

Step 2: Categorize by exception class

Group the errors by exception_class. Common patterns:

• Same class, different messages — likely the same root cause. Fix one and resolve the group.
• High occurrence count — prioritize these; they affect users most.
• `latest_occurrence_has_solutions: true` — check solutions first, they often have the fix.

Step 3: Take action on each error

For each error, decide:

Step 4: Paginate through remaining errors

# Next page
flare list-project-errors --project-id=123 --filter-status=open --sort=-last_seen_at --page-number=2 --page-size=30

Repeat until all pages are triaged. Use meta.last_page from the response to know when you're done.

---

Debug an error with local code

Use occurrence data to pinpoint the bug in the user's local codebase.

Step 1: Get the latest occurrence

flare list-error-occurrences --error-id=456 --sort=-received_at --page-size=1

Or if you have a specific occurrence ID:

flare get-error-occurrence --occurrence-id=789

Step 2: Find application frames

From the occurrence's frames array, filter for frames where application_frame is true. These are the user's code — not vendor or framework code.

Each application frame has:

• relative_file — path relative to the project root (e.g., app/Http/Controllers/OrderController.php)
• line_number — the exact line where execution was at this point in the stack
• class and method — the class and method name
• code_snippet — a few lines of code around the error line (from the production server)

Step 3: Read local source files

For each application frame, read the local file at the reported path and line number. The code may have changed since the error occurred — compare the code_snippet from the occurrence with the local file to check.

If application_version is set on the occurrence, you can also check git to see what changed:

git diff <application_version> -- <relative_file>

Step 4: Use context for clues

Attributes (attributes[]) provide request and environment context:

• group: "request" — URL, method, IP, user agent
• group: "user" — authenticated user info
• group: "environment" — PHP version, server, OS
• group: "context" — custom context added by the application

Events (events[]) show the execution trail leading up to the error:

• Database queries executed
• Log messages written
• Jobs dispatched
• Cache hits/misses
• Events and listeners fired

Events are chronological. Walk through them to understand what happened before the crash.

Step 5: Check solutions

If solutions[] is non-empty, these are AI-generated or provider-supplied fix suggestions. Each solution has:

• title — what the solution is
• description — how to apply it
• links[] — relevant documentation URLs

Present solutions prominently — they're often the fastest path to a fix.

Step 6: Present findings

Summarize for the user: 1. Error: exception class + message 2. Location: file:line in their code (link to the application frame) 3. Context: relevant attributes (request URL, user, etc.) 4. Trail: key events leading to the error 5. Solutions: any available solutions 6. Flare link: latest_occurrence_url_on_flare for the full dashboard view

---

Interpreting occurrence data

Frames

The frames array is the full stack trace, ordered from the throw point (index 0) to the entry point (last index).

• `application_frame: true` — this is code in the user's project (not vendor). Always focus on these.
• `application_frame: false` — framework/library code. Useful for understanding the call path but usually not the source of the bug.
• `code_snippet` — array of source lines from the production server. Line numbers in the snippet correspond to the actual file.

Attributes

Attributes are key-value context grouped by category:

Events

Events are a chronological log of what happened during the request/job:

Solutions

Flare's solution providers suggest fixes based on the error type. A solution includes:

• title — short description (e.g., "Add the missing method")
• description — detailed instructions
• links — documentation references
• is_runnable — whether it can be auto-applied (via Flare dashboard only, not CLI)

---

Investigate slow performance

Use the monitoring commands to find performance bottlenecks, drill into specific routes or queries, and inspect individual traces.

Step 1: Get a performance overview

flare get-monitoring-summary --project-id=123 --filter-interval=24h

This returns metrics and trends for routes, jobs, commands, and queries, plus the top-10 slowest routes and top-10 slowest queries. Start here to understand the overall health of the application.

Step 2: List aggregations for a specific type

Pick the type that looks problematic (e.g. routes or queries) and list the aggregations sorted by p95 descending:

flare list-monitoring-aggregations --project-id=123 --type=routes --sort=-p95 --filter-interval=24h

Present results as a table: label, p95, average, count, error rate. Focus on aggregations with high p95 values or high error rates.

To filter for only slow aggregations:

flare list-monitoring-aggregations --project-id=123 --type=queries --filter-p95=500 --sort=-p95

Step 3: View time series for trends

Check if slowness is a recent spike or a sustained pattern:

flare get-monitoring-time-series --project-id=123 --type=routes --filter-interval=7d

To scope to a single aggregation:

flare get-monitoring-time-series --project-id=123 --type=routes --uuid=<uuid> --filter-interval=7d

Step 4: Drill into a specific aggregation

Get details on a slow route, query, job, etc.:

flare get-monitoring-aggregation --type=routes --uuid=<uuid> --include=children

The children include shows what the route calls (queries, external HTTP, views, etc.) — these are often the source of slowness. The parents include shows what calls this aggregation.

Step 5: List traces for the aggregation

flare list-aggregation-traces --type=routes --uuid=<uuid> --sort=slowest

This returns trace summaries sorted by duration. Pick the slowest traces to inspect.

Step 6: Inspect a trace

flare get-trace --trace-id=<trace-id>

This returns the full span tree with events, resources, and contexts. Walk through the span tree to find the bottleneck:

• Look for spans with the longest duration — these are the slowest operations
• Check child spans to see where time is actually being spent
• Review events for context (queries executed, cache operations, etc.)
• Use resources and contexts for environment details

Step 7: Present findings

Summarize for the user: 1. Bottleneck: which route/query/job is slow and its p95 latency 2. Pattern: whether it's a sustained issue or a recent spike (from time series) 3. Root cause: what the trace reveals (e.g. slow query, N+1 problem, slow external API) 4. Children: downstream operations contributing to the slowness 5. Recommendation: specific actions to improve performance

---

Snooze strategies

Choose the right snooze type based on the situation:

To unsnooze any error:

flare unsnooze-error --error-id=456

---

Create a project and get API keys

Step 1: Find your team ID

flare get-authenticated-user

The response includes a teams array — note the id of the team you want to create the project in.

Step 2: Create the project

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

`technology` values: Laravel, PHP, JS, Vue, React

`stage` values: local, development, staging, production

Step 3: Retrieve the API keys

The create-project response includes two keys:

• `api_key` — for server-side SDKs (PHP, Laravel). Set as the FLARE_KEY environment variable.
• `api_public_key` — for client-side SDKs (JavaScript). Used in flare.light().

To find keys for an existing project:

# List all projects
flare list-projects

# Search by name
flare list-projects --filter-name="My App"

The project object in the response contains both api_key and api_public_key.

For instructions on installing the SDK in your application, see the Flare docs for your technology:

• Laravel: https://flareapp.io/docs/laravel
• PHP: https://flareapp.io/docs/php
• JavaScript / React / Vue: https://flareapp.io/docs/javascript

Step 4: Verify errors are flowing

Once your application is configured and sending errors:

# Check error count
flare get-project-error-count --project-id=123 --start-date="2025-01-01 00:00:00" --end-date="2025-12-31 23:59:59"

# Or list recent errors
flare list-project-errors --project-id=123 --sort=-last_seen_at --page-size=5