Artisan console - Knowledge of Laravel

What is Artisan?

Artisan is the command-line interface (CLI) tool bundled with Laravel. It lives at the project root as the artisan script and provides many commands that streamline development and operations. Use the list command to see every available command:

php artisan list

Prefix any command with help to view its usage:

php artisan help migrate

If you use Laravel Sail, replace php artisan with sail artisan. Commands run inside the Docker container.

./vendor/bin/sail artisan list

Tinker

Laravel Tinker is a REPL environment that lets you interactively work with your entire application from the command line — Eloquent models, jobs, events, and more.

php artisan tinker

Once launched you can execute PHP code directly:

// Fetch and inspect a user
>>> App\Models\User::find(1)
// Create a record via a factory
>>> App\Models\User::factory()->create()
// Call a service class directly
>>> app(App\Services\OrderService::class)->process(1)

Tinker actually mutates data. Be very careful running it in production. It is well suited to verifying behavior or debugging in local and staging environments.

Creating custom commands

Generating a command

Use make:command to scaffold a new command class:

php artisan make:command ImportProducts

This generates app/Console/Commands/ImportProducts.php.

Command structure

A generated command class has three main elements: $signature, $description, and handle().

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class ImportProducts extends Command
{
    /**
     * The command name and its arguments/options.
     */
    protected $signature = 'import:products';

    /**
     * The command description (shown by php artisan list).
     */
    protected $description = 'Import product data from a CSV file';

    /**
     * The command's execution logic.
     */
    public function handle(): void
    {
        $this->info('Starting import...');
        // Perform the work here
        $this->info('Done.');
    }
}

Laravel 13 also supports defining commands with PHP attributes.

use Illuminate\Console\Attributes\Description;
use Illuminate\Console\Attributes\Signature;

#[Signature('import:products')]
#[Description('Import product data from a CSV file')]
class ImportProducts extends Command
{
    public function handle(): void
    {
        // ...
    }
}

Defining arguments and options

Declare the command name, arguments, and options together in $signature.

protected $signature = 'import:products
                        {file : Path to the CSV file to import}
                        {--limit= : Maximum number of records to import}
                        {--dry-run : Do not actually save to the DB (for validation)}';

Syntax	Kind	Description
`{file}`	Required argument	Omitting it raises an error
`{file?}`	Optional argument	Defaults to `null` when omitted
`{file=products.csv}`	Argument with default	Uses the default value when omitted
`{--queue}`	Flag option	`true` when passed, `false` otherwise
`{--limit=}`	Option with value	Pass a value like `--limit=100`
`{--limit=50}`	Option with default	Defaults to `50` when omitted
`{--Q\|queue}`	Option with shortcut	Can also be passed as `-Q`

Reading arguments and options

Use argument() and option() inside handle() to read values.

public function handle(): void
{
    $file    = $this->argument('file');       // Read an argument
    $limit   = $this->option('limit');        // Read an option
    $dryRun  = $this->option('dry-run');      // Flag option (bool)

    $this->info("File: {$file}");

    if ($dryRun) {
        $this->warn('Dry-run mode: skipping database writes');
    }
}

`input()` — typed accessors

The input() method exposes the same typed accessors HTTP requests use, so you can read command arguments and options with proper types.

use App\Enums\ReportType;

public function handle(): void
{
    // Retrieve arguments and options through a CommandInput instance
    $from = $this->input()->date('from');
    $type = $this->input()->enum('type', ReportType::class);
    $limit = $this->input()->integer('limit');
}

If you only want a specific value, pass its name directly (both arguments and options are searched):

$queue = $this->input('queue', 'default');

argument() and option() return strings, whereas the typed accessors on input() convert to the appropriate type. This is convenient when you want type-safe handling of dates, numbers, enums, and similar values.

User interaction

Writing output

Several helpers are available for writing colored messages to the console.

$this->info('Completed successfully');    // green
$this->warn('This action cannot be undone');    // yellow
$this->error('An error occurred');       // red
$this->line('Plain text');             // no color
$this->comment('Additional information');               // light gray

Prompting the user

You can accept interactive input from the user.

// Free-form text input
$name = $this->ask('Enter the operator name');

// With a default value
$env = $this->ask('Select the environment', 'production');

// Sensitive input such as a password (not echoed to the screen)
$password = $this->secret('Enter your API key');

// Yes/no confirmation
if (! $this->confirm('Import into the production DB?')) {
    $this->info('Cancelled.');
    return;
}

// Choose from a list
$format = $this->choice('Choose an output format', ['csv', 'json', 'xml'], 0);

Progress bars

Show progress clearly while processing large amounts of data.

use App\Models\Product;

// Passing a collection displays a progress bar automatically
$this->withProgressBar(Product::cursor(), function (Product $product) {
    $this->processProduct($product);
});

For manual, finer-grained control:

$total = Product::count();
$bar = $this->output->createProgressBar($total);
$bar->start();

Product::cursor()->each(function (Product $product) use ($bar) {
    $this->processProduct($product);
    $bar->advance();
});

$bar->finish();
$this->newLine();

Practical use cases

A data import command

A practical example of importing product data from a CSV file.

Generate the command

php artisan make:command ImportProducts

Implement the command

<?php

namespace App\Console\Commands;

use App\Models\Product;
use Illuminate\Console\Command;

class ImportProducts extends Command
{
    protected $signature = 'import:products
                            {file : Path to the CSV file}
                            {--limit= : Maximum records to import}
                            {--dry-run : Preview only (do not save)}';

    protected $description = 'Import product data from a CSV file';

    public function handle(): void
    {
        $filePath = $this->argument('file');
        $limit    = $this->option('limit') ? (int) $this->option('limit') : null;
        $dryRun   = $this->option('dry-run');

        if (! file_exists($filePath)) {
            $this->error("File not found: {$filePath}");
            return;
        }

        // Read the CSV using PHP's built-in functions
        $handle = fopen($filePath, 'r');
        $headers = fgetcsv($handle); // Treat the first row as the header
        $rows = [];
        while (($row = fgetcsv($handle)) !== false) {
            $rows[] = array_combine($headers, $row);
            if ($limit !== null && count($rows) >= $limit) {
                break;
            }
        }
        fclose($handle);

        $count = 0;

        $this->withProgressBar($rows, function (array $row) use ($dryRun, &$count) {
            if (! $dryRun) {
                Product::updateOrCreate(
                    ['sku' => $row['sku']],
                    [
                        'name'  => $row['name'],
                        'price' => $row['price'],
                    ]
                );
            }
            $count++;
        });

        $this->newLine();

        if ($dryRun) {
            $this->warn("{$count} records matched (dry run: writes were skipped)");
        } else {
            $this->info("Imported {$count} records.");
        }
    }
}

Run the command

# Regular import
php artisan import:products storage/products.csv

# Limit the number of records
php artisan import:products storage/products.csv --limit=100

# Verify with a dry run
php artisan import:products storage/products.csv --dry-run

A periodic maintenance command

An example of a maintenance command run on a schedule, such as deleting old data.

<?php

namespace App\Console\Commands;

use App\Models\Order;
use Illuminate\Console\Command;

class PruneOldOrders extends Command
{
    protected $signature = 'orders:prune {--days=90 : Delete data older than this many days}';

    protected $description = 'Delete completed orders older than the given number of days';

    public function handle(): void
    {
        $days = (int) $this->option('days');

        if (! $this->confirm("Delete completed orders older than {$days} days?")) {
            $this->info('Cancelled.');
            return;
        }

        $deleted = Order::where('status', 'completed')
            ->where('created_at', '<', now()->subDays($days))
            ->delete();

        $this->info("Deleted {$deleted} orders.");
    }
}

Combining with scheduled execution

You can schedule commands you write in routes/console.php. See Task scheduling for details.

use Illuminate\Support\Facades\Schedule;

// Run daily at 2 a.m.
Schedule::command('orders:prune --days=90')->dailyAt('2:00');

// Run every Monday at 9 a.m.
Schedule::command('import:products storage/weekly.csv')->weeklyOn(1, '9:00');

Testing commands

Use Laravel’s testing tools to verify Artisan commands behave as expected.

<?php

namespace Tests\Feature\Commands;

use App\Models\Order;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class PruneOldOrdersTest extends TestCase
{
    use RefreshDatabase;

    public function test_it_deletes_old_completed_orders(): void
    {
        // Create a completed order older than 90 days
        Order::factory()->create([
            'status'     => 'completed',
            'created_at' => now()->subDays(100),
        ]);

        // A recent completed order (should not be deleted)
        Order::factory()->create([
            'status'     => 'completed',
            'created_at' => now()->subDays(10),
        ]);

        $this->artisan('orders:prune', ['--days' => 90])
            ->expectsConfirmation('Delete completed orders older than 90 days?', 'yes')
            ->expectsOutput('Deleted 1 orders.')
            ->assertExitCode(0);

        $this->assertDatabaseCount('orders', 1);
    }

    public function test_it_cancels_when_user_declines(): void
    {
        Order::factory()->create(['status' => 'completed', 'created_at' => now()->subDays(100)]);

        $this->artisan('orders:prune', ['--days' => 90])
            ->expectsConfirmation('Delete completed orders older than 90 days?', 'no')
            ->expectsOutput('Cancelled.')
            ->assertExitCode(0);

        $this->assertDatabaseCount('orders', 1);
    }
}

Example assertion methods available through artisan():

Method	Description
`expectsOutput('...')`	Assert that the given text is output
`expectsQuestion('?', 'answer')`	Simulate input for `ask()`
`expectsConfirmation('?', 'yes')`	Simulate a response to `confirm()`
`expectsChoice('?', 'option')`	Simulate a `choice()` selection
`assertExitCode(0)`	Assert the exit code (0 = success)
`assertFailed()`	Assert the exit code is non-zero

The `dev` command

The dev Artisan command starts the multiple processes you need for local development inside a single terminal window. By default it concurrently runs the PHP development server, the queue worker, log monitoring via Pail, and Vite asset compilation.

php artisan dev

Under the hood, it uses the concurrently npm package to manage processes. Each process is labeled and color-coded, making it easy to distinguish them in the terminal output. If any process fails, all the others are automatically stopped. The processes run by default are:

Name	Command
`server`	`php artisan serve --host=localhost`
`queue`	`php artisan queue:listen --tries=1 --timeout=0`
`logs`	`php artisan pail --timeout=0`
`vite`	`npm run dev`

The vite process auto-detects the Node package manager you use (npm, pnpm, Yarn, or Bun) and invokes the appropriate command.

Customizing `dev` processes

You can customize the processes the dev command runs with the DevCommands class. Typically you register them inside the boot method of your application’s AppServiceProvider. The register method takes a command string and an optional process name.

use Illuminate\Foundation\DevCommands;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    DevCommands::register('some-command --flag', 'my-process');
}

When registering an Artisan command, use the artisan method, which automatically prefixes php artisan for you.

DevCommands::artisan('horizon', 'horizon');

Similarly, the node method prefixes the detected package manager’s run command (for example, npm run), and nodeExec prefixes the package manager’s exec command (for example, npx).

DevCommands::node('storybook', 'storybook');

DevCommands::nodeExec('tailwindcss -i resources/css/app.css -o public/css/app.css --watch', 'tailwind');

Registering a process with the same name as a default process replaces that default. For example, you can customize the server process to use a different port:

DevCommands::artisan('serve --host=localhost --port=9000', 'server');

You can also customize the color of the process label shown in the terminal. Available color methods are blue, purple, pink, orange, green, and yellow. You can also pass a custom hex color to the color method.

DevCommands::register('my-command', 'my-process')->green();

DevCommands::register('my-command', 'my-process')->color('#ff6347');

To list the registered dev processes without actually starting them, use the dev:list command.

php artisan dev:list

Filtering `dev` processes

Use the only method to run only specific processes when the dev command is executed. Similarly, except excludes specific processes.

// Only run the server and vite processes...
DevCommands::only('server', 'vite');

// Run every process except the queue worker...
DevCommands::except('queue');

If you also use Horizon or Reverb during local development, registering them with DevCommands::artisan() lets you start everything with a single php artisan dev command.

Common commands at a glance

# Create a new command
php artisan make:command CommandName

# List available commands
php artisan list

# Show help for a command
php artisan help command:name

# Launch Tinker
php artisan tinker

​What is Artisan?

​Tinker

​Creating custom commands

​Generating a command

​Command structure

​Defining arguments and options

​Reading arguments and options

​input() — typed accessors

​User interaction

​Writing output

​Prompting the user

​Progress bars

​Practical use cases

​A data import command

​A periodic maintenance command

​Combining with scheduled execution

​Testing commands

​The dev command

​Customizing dev processes

​Filtering dev processes

​Common commands at a glance

What is Artisan?

Tinker

Creating custom commands

Generating a command

Command structure

Defining arguments and options

Reading arguments and options

`input()` — typed accessors

User interaction

Writing output

Prompting the user

Progress bars

Practical use cases

A data import command

A periodic maintenance command

Combining with scheduled execution

Testing commands

The `dev` command

Customizing `dev` processes

Filtering `dev` processes

Common commands at a glance