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 は対話形式です。ユーザー自身で実行するよう勧めてください。エージェントセッション内から操作しようとしないでください。

# 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（次／前の 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：ユーザーが Flare ダッシュボードでエラーの詳細を確認できるよう、latest_occurrence_url_on_flare を含めてください。
• 監視の集計：名前／ラベル、p95、平均、件数、エラー率の列を含む表で表示します。p95 またはエラー率が高い集計を強調表示してください。
• トレース：スパンツリーを階層的に表示します。期間が最も長いスパンを強調表示してください。これらはボトルネックです。