flare

Flare CLI

flare CLI 可让你在终端中管理 Flare 错误跟踪和性能监控。每个 Flare API 端点都有对应的命令。

前置条件

检查 CLI 是否已安装：

flare --version

如果尚未安装：

composer global require spatie/flare-cli

确保 Composer 的全局 bin 目录位于 PATH 中：

composer global config bin-dir --absolute

身份验证

flare login 需要交互操作。建议用户自行运行——不要尝试在 Agent 会话中代为操作。

# 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

凭据按 OAuth 发行方和 API 基础 URL 存储在 ~/.flare/config.json 中。当前使用的 API 基础 URL 来自 FLARE_BASE_URL，默认值为 https://flareapp.io/api。生产、预发布和可自托管配置文件可以共存。

个人访问令牌可在 https://flareapp.io/account/api-access 生成。脚本和 CI 中可使用 flare login --token，但不要将其用作日常工作站登录方式。

如果 CLI 提示 OAuth 会话已过期、已撤销或无法刷新，建议运行 flare login。如果提示缺少连接权限，请引导用户访问 CLI 打印的 API Access URL。

命令快速参考

所有命令均输出 JSON。完整参数详情请参阅 references/commands.md。

用户与团队

# 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

项目

# 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

错误

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

错误操作

# 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

发生记录

# 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

性能监控

--type 参数接受：routes、queries、jobs、commands、external-http、views、livewire-components。

--filter-interval 参数接受：1h、3h、6h、24h（默认值）、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>

分页

所有列表命令均支持分页：

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

响应包含 meta（current_page、total、last_page）和 links（next/prev URL）。

常见工作流

错误分诊

列出未解决的错误，按异常类分类，并批量解决或暂缓处理。完整分诊工作流请参阅 references/workflows.md。

简要版本：

# 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

使用本地代码调试错误

获取发生记录，查找应用程序堆栈帧，然后读取对应的本地文件。详细步骤请参阅 references/workflows.md。

简要版本：

# 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

调查性能缓慢问题

获取性能概览，深入查看缓慢的聚合数据，并检查单个跟踪记录。完整工作流请参阅 references/workflows.md。

简要版本：

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

创建项目并获取 API 密钥

通过 CLI 创建项目、获取 API 密钥，并验证错误是否正常上报。分步指南请参阅 references/workflows.md。

输出格式

所有命令均返回 JSON。向用户展示结果时：

• 错误：以表格展示，列包括：ID、异常类、消息（截断）、状态、发生次数、最近发生时间。始终包含 latest_occurrence_url_on_flare 链接。
• 发生记录：突出显示应用程序堆栈帧（application_frame 为 true 的帧）——这些属于用户代码，而非供应商代码。显示 relative_file 和 line_number。
• 解决方案：如果 solutions 非空，始终醒目展示——其中包含可执行的修复建议。
• 属性：展示上下文时，按 group 字段（例如 request、user、environment）分组。
• 事件：按时间顺序展示——它们代表导致错误的执行轨迹（查询、日志、作业等）。
• Flare URL：包含 latest_occurrence_url_on_flare，以便用户在 Flare 控制面板中查看完整错误。
• 监控聚合数据：以表格展示，列包括：名称/标签、p95、平均值、数量、错误率。突出显示 p95 或错误率较高的聚合数据。
• 跟踪记录：以层级结构展示跨度树。突出显示持续时间最长的跨度——这些是性能瓶颈。