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

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

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