Debugging workflows

Profile an Artisan command

Supported Artisan commands get their own profiles. Use the local MCP server to inspect what happened after the command exits.

Run the command

Laravel records the command lifecycle and supported activity.
Find its profile

Match the runtime name, recorded time, and exit code through MCP.
Inspect the cause

Follow findings, queries, logs, and retained source evidence.

A command profile describes work in that process. Queue workers create individual job profiles.

Start with an installed local app

Install the package and connect MCP to the same Laravel app. Its command process must use an allowed environment and the same accessible profile storage.

In the public benchmark, this command refreshes a journey and creates query, cache, Redis, and log activity:

php artisan morrow:refresh kyoto-autumn

That command belongs to the benchmark, not The New Debug Bar package. For your own app, run an existing finite Artisan command.

Try a small command with a clear result

Create app/Console/Commands/InspectWorkspaceCommand.php in a local example app. Register it through your Laravel version’s normal command registration if the app does not discover that directory.

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;

/** Produces a small command profile with a controlled exit status. */
class InspectWorkspaceCommand extends Command
{
    protected $signature = 'app:inspect-workspace {--fail}';

    protected $description = 'Inspect the local workspace connection';

    public function handle(): int
    {
        DB::select('select 1');
        Log::info('Workspace connection checked.');

        return $this->option('fail') ? self::FAILURE : self::SUCCESS;
    }
}

php artisan app:inspect-workspace
php artisan app:inspect-workspace --fail

Find the exact runtime profile

Ask your agent to call list-debug-profiles with a path fragment matching the command:

{
  "path": "artisan:app:inspect-workspace",
  "limit": 5
}

Choose by runtime name, recorded time, and exit code. Read the Request inspector, which is labeled Runtime for non-HTTP work, then Queries and Logs. The failure case should have exit code 1; the successful case should have exit code 0.

Workers and long-running commands

The package does not wrap queue:work, queue:listen, horizon, mcp:start, mcp:inspector, octane:start, reverb:start, schedule:work, or serve in one unbounded command profile. Queue jobs can create separate profiles when they execute.

Use Queues to move from an originating request to worker attempts. Restart a worker after a change that requires it to reload application code or configuration.

What a test-command profile means

An Artisan test lifecycle can be labeled as test-command context. That is not per-test-case tracing and does not guarantee that child-process activity is captured. To protect a particular HTTP route, use the exact response ID and profile assertions.

Verify the command result

Check the command’s real exit code or output separately, then compare it with the profile. A healthy profile does not prove every side effect completed; a nonzero exit code does not automatically contain an exception. Follow the evidence that the command actually retained.

Next step

Follow background jobs

Inspect each job attempt separately from the command that keeps the worker running.

Read the guide