lara-shell — an interactive artisan command shell

The idea

One prompt, three languages

Run php artisan shell and you get an artisan> prompt. Every line you type is classified and routed automatically — you never prefix an artisan command.

• Bare words run as artisan. Type migrate or route:list and it dispatches the artisan command directly — no php artisan boilerplate.
• Raw PHP still evaluates. Anything that is not a recognized command falls through to PsySH and is evaluated as PHP — the full Tinker experience, in the same session.
• Escape to PHP with ;. Prefix a line with a semicolon to force PHP evaluation, even when the first word collides with a command name.
• Fuzzy resolution. Prefix abbreviations (mig), colon-segment abbreviations (m:f → migrate:fresh) and fzf-style subsequence matching all resolve to the canonical command when the winner is unambiguous.

Under the hood each typed line is classified as artisan, macro, meta or php — empty lines and anything starting with ; go to PHP; a leading @ runs a macro; a first word that is a built-in meta-command runs that; a resolvable artisan name dispatches; everything else is PHP.

Capabilities

Command reference

Every capability, with the exact syntax read from the package source. The prompt is artisan>.

Meta-command syntax

A realistic session

What it feels like

Start a dev server in the background, migrate, define a shortcut, run a macro, drop into PHP, then manage jobs — all without leaving the prompt.

# long-running commands auto-background — no & needed
artisan> serve
Started background job 1a2b3c4d (serve)

artisan> migrate
This command is guarded. Re-type "migrate" to proceed: migrate
   INFO  Running migrations.
  2024_01_01_000000_create_users_table ..................... DONE

# make a reusable shortcut (rewrites the first word)
artisan> alias add fresh migrate:fresh --seed
Added alias fresh => migrate:fresh --seed

# run a macro defined in .lara-shell.php (steps run in order)
artisan> @reset
  cache:clear ... DONE
  config:clear ... DONE
  migrate:fresh --seed ... DONE

# unrecognized input evaluates as PHP — full Tinker
artisan> ; App\Models\User::count()
=> 42

# background a worker explicitly with a trailing &
artisan> queue:work --tries=3 &
Started background job 9f3a1c2b (queue:work --tries=3)

artisan> jobs
+-----------+----------------------+---------+--------+
| ID        | Command              | Status  | Uptime |
+-----------+----------------------+---------+--------+
| 1a2b3c4d  | serve                | running | 3m12s  |
| 9f3a1c2b  | queue:work --tries=3 | running | 8s     |
+-----------+----------------------+---------+--------+

artisan> logs 9f3a1c2b -f
[2024-01-01 12:00:08] Processing: App\Jobs\SendWelcome
# ^C to stop following, then reap the job
artisan> kill 9f3a1c2b
Killed job 9f3a1c2b.

Configuration

Two config files

Package behavior lives in config/lara-shell.php. Your project-local aliases and macros live in .lara-shell.php at the project root — created and updated for you as you run alias add/alias rm.

Publish the package config with php artisan vendor:publish --tag=lara-shell-config.

return [
  // command name + aliases
  'command' => [
    'name' => 'shell',
    'aliases' => ['terminal', 'repl'],
  ],

  // auto-backgrounded commands
  'long_running' => [
    'serve', 'queue:work', 'queue:listen',
    'schedule:work', 'horizon', 'pail',
    'reverb:start', 'octane:start', ...
  ],

  // production safety guard
  'guard' => [
    'environments' => ['production'],
    'block'   => [],
    'confirm' => [
      'migrate', 'migrate:fresh',
      'db:wipe', 'db:seed',
      'cache:clear', 'optimize:clear', ...
    ],
  ],

  'php_escape'  => ';',   // force-PHP prefix
  'macro_sigil' => '@',   // macro trigger
];

// project root — aliases & macros.
// managed by `alias add` / `alias rm`,
// and safe to hand-edit.
return [

  // first-word rewrites
  'aliases' => [
    'fresh' => 'migrate:fresh --seed',
    'tw'    => 'tinker',
  ],

  // named step lists, run in order.
  // invoke with @name; steps may
  // reference other @macros.
  'macros' => [
    'reset' => [
      'cache:clear',
      'config:clear',
      'migrate:fresh --seed',
    ],
    'up' => [
      '@reset',
      'serve',
    ],
  ],
];