Artisan Commands

Spectra provides four Artisan commands for installation, pricing management, data retention, and statistics maintenance. These commands are the primary interface for managing Spectra's database state outside of the dashboard.

spectra:install

Interactive installer that publishes the configuration file and database migrations, optionally runs migrations, and optionally imports the default pricing catalog. This is the recommended way to set up Spectra after installing the Composer package.

php artisan spectra:install

The installer performs the following steps in order:

1. Publishes configuration — Copies config/spectra.php to your application's config directory.
2. Publishes migrations — Copies all Spectra migration files to database/migrations/.
3. Runs migrations (optional) — Prompts you to run php artisan migrate to create the seven Spectra database tables.
4. Imports pricing (optional) — Prompts you to run spectra:pricing --force to populate the pricing catalog with default data for all built-in providers.

If you prefer manual control, you can skip the installer entirely and publish resources individually:

php artisan vendor:publish --tag=spectra-config
php artisan vendor:publish --tag=spectra-migrations

spectra:pricing

Imports or updates the pricing catalog from a JSON file into the spectra_models and spectra_pricing database tables. The command matches records by provider name and model internal name, creating new entries or updating existing ones as needed. After import, the pricing cache is cleared automatically.

php artisan spectra:pricing [--force] [--path=]

Options

Option	Description
--force	Overwrite existing pricing data without prompting for confirmation
--path=	Path to a custom pricing JSON file. Defaults to the bundled database/data/pricing.json

Examples

# Import bundled pricing (prompts if data already exists)
php artisan spectra:pricing

# Force overwrite existing pricing
php artisan spectra:pricing --force

# Import from a custom file
php artisan spectra:pricing --path=/path/to/my-pricing.json --force

Custom Pricing File Format

The JSON file follows this structure. Prices for token-based models are in cents per million tokens. Prices for non-token models (images, audio, etc.) are in cents per unit:

{
  "providers": [
    {
      "internal_name": "openai",
      "display_name": "OpenAI",
      "models": [
        {
          "internal_name": "gpt-4o",
          "display_name": "GPT-4o",
          "type": "text",
          "pricing_unit": "tokens",
          "pricing": [
            {
              "tier": "standard",
              "input_price": 250,
              "output_price": 1000,
              "cached_input_price": 125
            },
            {
              "tier": "batch",
              "input_price": 125,
              "output_price": 500
            }
          ]
        }
      ]
    }
  ]
}

spectra:prune

Deletes old request records and their associated daily statistics to manage storage growth. Pruning is irreversible — make sure your retention period meets your audit and compliance requirements before scheduling this command.

php artisan spectra:prune [--hours=24]

Options

Option	Default	Description
--hours=	24	Delete records older than this many hours

The command deletes rows from spectra_requests where created_at is older than the specified cutoff, corresponding rows from spectra_daily_stats where date is before the cutoff date, and any orphaned pivot records in spectra_requests_tags via cascade delete.

Examples

# Delete requests older than 24 hours (default)
php artisan spectra:prune

# Keep 7 days of data
php artisan spectra:prune --hours=168

# Keep 30 days of data
php artisan spectra:prune --hours=720

Scheduling

Add pruning to your application's scheduler for automatic retention management:

use Illuminate\Support\Facades\Schedule;

Schedule::command('spectra:prune --hours=168')->daily();

spectra:rebuild-stats

Rebuilds the spectra_daily_stats table by re-aggregating data from the raw spectra_requests records. Use this command after data migrations, manual database edits, bulk imports, or whenever dashboard statistics appear out of sync with the underlying request data.

The command deletes existing daily stats for the target date range and then re-aggregates from scratch, grouping by date, provider, model, model type, and trackable entity.

php artisan spectra:rebuild-stats [--from=] [--to=] [--yesterday]

Options

Option	Description
--from=	Start date in Y-m-d format (e.g., 2026-01-01)
--to=	End date in Y-m-d format (e.g., 2026-01-31)
--yesterday	Rebuild only yesterday's statistics

Examples

# Rebuild all stats (prompts for confirmation)
php artisan spectra:rebuild-stats

# Rebuild a specific date range
php artisan spectra:rebuild-stats --from=2026-01-01 --to=2026-01-31

# Rebuild yesterday only (suitable for scheduled runs)
php artisan spectra:rebuild-stats --yesterday

Scheduling

If you want to ensure statistics stay fresh, schedule a nightly rebuild:

Schedule::command('spectra:rebuild-stats --yesterday')->dailyAt('01:00');

Command Summary

Command	Purpose	Typical Usage
spectra:install	One-time interactive setup	After composer require
spectra:pricing --force	Import or update pricing catalog	After pricing changes or package upgrades
spectra:prune --hours=168	Delete old request data	Scheduled daily for retention management
spectra:rebuild-stats --yesterday	Rebuild aggregated statistics	Scheduled daily or after data corrections