Management Commands Overview

Purpose and Scope

This document provides an overview of Telescope's five console commands for managing recorded monitoring data. These commands enable administrators to control recording state, maintain data retention policies, and deploy configuration changes.

For detailed documentation of individual commands, see:

• telescope:clear - Removing all entries
• telescope:pause and telescope:resume - Controlling recording state
• telescope:prune - Enforcing retention policies
• telescope:publish - Deploying configuration and assets

Command Registry

Telescope provides five management commands, all registered under the telescope: namespace:

Command	Signature	Repository Contract	Primary Use Case
telescope:clear	telescope:clear	ClearableRepository	Remove all Telescope entries from storage
telescope:pause	telescope:pause	None (uses CacheFactory)	Temporarily disable all watchers
telescope:resume	telescope:resume	None (uses CacheFactory)	Re-enable watchers after pause
telescope:prune	telescope:prune {--hours=24} {--keep-exceptions}	PrunableRepository	Remove stale entries based on retention policy
telescope:publish	telescope:publish {--force}	None (publishes assets)	Deploy configuration file and frontend assets

Sources: src/Console/ClearCommand.php1-31 src/Console/PauseCommand.php1-35 src/Console/PruneCommand.php1-30

Command Architecture

The following diagram shows how Telescope's management commands integrate with the framework's console infrastructure and Telescope's storage layer:

Diagram: Command Architecture and Dependencies

All management commands extend Hypervel\Console\Command, inheriting standard console command capabilities like input/output handling, option parsing, and formatting. Commands that manipulate stored data depend on repository contracts (ClearableRepository, PrunableRepository), while state control commands (pause, resume) interact with the cache system to store recording state flags.

Sources: src/Console/ClearCommand.php10-31 src/Console/PauseCommand.php10-35 src/Console/PruneCommand.php11-30

Command Categories

Telescope's management commands fall into three functional categories:

Data Lifecycle Commands

Commands that manage the storage lifecycle of recorded entries:

telescope:clear: Performs a complete purge of all Telescope data by invoking ClearableRepository::clear(). This is a destructive operation with no undo capability, typically used during development or when resetting monitoring state. The command provides no options or arguments—it unconditionally removes all entries from telescope_entries, telescope_entries_tags, and telescope_monitoring tables.

telescope:prune: Implements retention policies by removing entries older than a specified threshold. Accepts two options:

• --hours=24: Retention period in hours (default: 24)
• --keep-exceptions: Preserves exception entries regardless of age

The command calculates the expiration timestamp using Carbon::now()->subHours() and delegates to PrunableRepository::prune(). This is designed for scheduled execution (cron jobs) to maintain database size.

Sources: src/Console/ClearCommand.php20-30 src/Console/PruneCommand.php16-29

Recording Control Commands

Commands that control whether Telescope actively records new entries:

telescope:pause: Disables all watchers by setting the cache key telescope:pause-recording to true with a 30-day TTL. When this key is present, Telescope::isRecording() returns false, preventing all watchers from submitting entries. This mechanism operates independently of the enabled configuration option, allowing temporary disablement without modifying configuration files.

telescope:resume: Re-enables recording by removing the telescope:pause-recording cache key. Once removed, Telescope::isRecording() resumes checking the enabled configuration and per-request recording decisions.

The pause/resume mechanism is implemented via cache rather than configuration to enable coordination across multiple servers without requiring configuration file changes or server restarts.

Sources: src/Console/PauseCommand.php15-34

Deployment Commands

Commands that deploy Telescope resources to the application:

telescope:publish: Copies Telescope's default configuration file and frontend assets to the application. Typically executed during initial installation. The --force option allows overwriting existing files, useful when upgrading Telescope versions.

Command Execution Flow

The following sequence diagram illustrates the typical execution flow for data manipulation commands:

Diagram: Command Execution Flow

The console kernel resolves each command's dependencies via dependency injection. Data manipulation commands (clear, prune) receive repository implementations that encapsulate database operations. The ClearCommand performs unconditional deletion across all Telescope tables, while PruneCommand applies filtering based on timestamp and optional exception preservation. State control commands interact with the cache layer to set persistent flags.

Sources: src/Console/ClearCommand.php25-29 src/Console/PruneCommand.php26-29 src/Console/PauseCommand.php25-34

Command Design Patterns

Repository Contract Abstraction

Commands that manipulate stored data depend on repository contracts rather than concrete implementations. This enables:

1. Storage Driver Independence: Commands work with any storage driver (database, Redis, etc.) without modification
2. Testability: Commands can be tested with mock repositories
3. Separation of Concerns: Commands focus on CLI interaction while repositories handle data operations

Example from ClearCommand:

The command receives ClearableRepository (contract) via constructor injection. The DI container resolves this to DatabaseEntriesRepository (implementation) at runtime based on configuration.

Sources: src/Console/ClearCommand.php25-29

Cache-Based State Management

The pause/resume mechanism uses cache-based flags rather than configuration or database storage:

This design provides:

• Immediate Effect: State changes apply instantly without restarting servers
• Distributed Coordination: All servers check the same cache key
• Automatic Expiry: 30-day TTL prevents permanent disablement from forgotten pauses
• No Database Dependency: Works even when database is experiencing issues

Sources: src/Console/PauseCommand.php28-30

Option-Based Parameterization

The PruneCommand demonstrates idiomatic option handling:

Options use Hypervel's command signature syntax:

• --hours=24: Option with default value
• --keep-exceptions: Boolean flag option
• Inline descriptions after : for help text generation

The command retrieves options using $this->option() and casts appropriately:

Sources: src/Console/PruneCommand.php16-28

Usage Recommendations

Scenario	Recommended Command	Frequency	Notes
Development reset	telescope:clear	As needed	Fast way to clear test data
Production maintenance	telescope:prune --hours=168	Daily (scheduled)	Retain 7 days of history
Exception debugging	telescope:prune --hours=24 --keep-exceptions	Daily (scheduled)	Prune normal entries, keep exceptions
Emergency disablement	telescope:pause	Rare	Use when Telescope causes performance issues
Post-maintenance re-enable	telescope:resume	After pause	Don't forget to resume
Initial installation	telescope:publish	Once	Deploy configuration and assets
Version upgrade	telescope:publish --force	After upgrade	Update configuration and assets

Sources: src/Console/ClearCommand.php1-31 src/Console/PauseCommand.php1-35 src/Console/PruneCommand.php1-30