Usage

Every inspection follows the same shape:

php artisan telescope:inspect [type flags] [filters] [output flags]

With no type flags you get an overview of entry counts per type and the flag for each one.

Choosing entry types

Type flags combine. Pass several to inspect them in one run:

php artisan telescope:inspect --requests --queries --exceptions --last=1h

Time windows

Use exactly one of these:

--last=15m                          # durations: 30s, 15m, 1h, 24h, 7d, 2w
--from=2026-08-01 --to=2026-08-02   # explicit window, either bound is optional

--from and --to accept anything Carbon::parse() understands (2026-08-01, 2026-08-01 14:30, ISO 8601) and are read in the application timezone. --last sets only a lower bound; it cannot be combined with --from or --to. With no time option, all recorded entries are considered.

Row filters

Filters apply only to entry types that have the matching field. Passing a filter that cannot match any selected type exits with code 2.

Examples:

php artisan telescope:inspect --requests --queries --last=1h --min-duration=500
php artisan telescope:inspect --jobs --failed --last=24h
php artisan telescope:inspect --http --status=500 --last=6h
php artisan telescope:inspect --queries --search="orders" --connection=mysql

Note that --search cannot use database indexes. On large tables, narrow it with a time window.

Deep-diving a single entry

php artisan telescope:inspect --show=<uuid>

Prints every normalized field for that UUID. Sensitive fields require --full.

Picking an entry interactively

php artisan telescope:inspect --queries --pick

After the listing renders, an arrow-key selector offers every listed entry with its time, type, summary and full file:line; confirming opens the same detail view as --show for the chosen UUID. Requires a type flag or --batch=<id>; cannot be combined with --json, --ndjson, or --watch. When no interactive terminal is available (CI, pipes) the picker says so and exits cleanly - the listing itself is never lost.

Replaying a request or job

Every entry Telescope records during one request or job shares a batch id. Replay the whole lifecycle in recording order:

php artisan telescope:inspect --batch=<batch-id>

Batch mode cannot be combined with narrowing filters or --limit - that combination is invalid usage (exit 2). Combine with --json to hand an agent or a teammate's script the complete story of one request, and note that a bus batch id (the id of an Illuminate\Bus batch) is resolved through its recorded entries too. A batch id that matches nothing exits 1.

Watching live traffic

php artisan telescope:inspect --requests --queries --watch
php artisan telescope:inspect --exceptions --watch=5   # check every 5 seconds

The command starts from what is already stored and prints new entries as they arrive, one line each. Add --ndjson for machine-consumable lines (the start-up banner stays on the human stream, so piped output is pure). Content filters such as --min-duration, --status, or --search cannot be combined with --watch: it streams everything of the selected types. Press Ctrl+C to stop; watch mode only ends by signal.

Job entries are recorded at dispatch time and updated in place later, so time windows for --jobs --failed filter by when a job was dispatched, not when it failed - use a wide enough window to catch late failures.

Managing monitored tags

Monitored tags tell Telescope to keep entries that match them even when recording is paused:

php artisan telescope:monitor list
php artisan telescope:monitor add --tag="App\Jobs\*" --tag="Auth:id:7"
php artisan telescope:monitor remove --tag="SlowRequest"

Output formats

CI gates

--fail-on turns findings into exit code 3:

php artisan telescope:inspect --last=24h --fail-on=exceptions,failed-jobs
php artisan telescope:inspect --queries --fail-on=slow-queries --min-duration=1000 --last=1h

Supported checks: exceptions, failed-jobs, slow-requests, slow-queries. Slow checks use P95 route duration for requests (top 10 routes are evaluated) and individual query duration for queries. The threshold comes from --min-duration when given, otherwise from slow_threshold_ms in config.

A practical CI recipe pairs a short window with the check so old failures do not block every future build:

php artisan telescope:inspect --fail-on=exceptions,failed-jobs --last=15m

AI agents

When the process runs under an AI coding agent, output switches to the JSON contract automatically (detected with laravel/agent-detector: Claude Code, Cursor, OpenCode, Codex, Copilot, and others). The envelope includes an agent key with the detected name.

To force tables anyway, pass --human. To turn the behavior off completely, set auto_json_for_agents to false in the config file.

A Laravel Boost skill ships with the package (resources/boost/skills/telescope-inspect). Running php artisan boost:install in a project that uses this package installs it, so connected agents know when to reach for these commands and how to read the output.

Exit codes

Finding issues does not fail the command unless --fail-on is used.