PHPackages                             amims71/lara-shell - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. amims71/lara-shell

ActiveLibrary[CLI & Console](/categories/cli)

amims71/lara-shell
==================

An interactive artisan command shell (php artisan shell): a PsySH-based REPL where bare words run as artisan commands, with managed background jobs, aliases, macros, fuzzy matching and a production safety guard.

v0.2.1(today)00MITPHPPHP ^8.2CI passing

Since Jul 1Pushed todayCompare

[ Source](https://github.com/amims71/lara-shell)[ Packagist](https://packagist.org/packages/amims71/lara-shell)[ RSS](/packages/amims71-lara-shell/feed)WikiDiscussions master Synced today

READMEChangelog (3)Dependencies (7)Versions (4)Used By (0)

lara-shell
==========

[](#lara-shell)

**An interactive artisan command shell for Laravel.** Run `php artisan shell` and you get a REPL where bare words execute as artisan commands, `;`-prefixed lines evaluate as PHP (Tinker-style), and you get fuzzy command matching, managed background jobs, aliases, macros, and a production safety guard on top.

```
$ php artisan shell
artisan> serve
  INFO  Server running on [http://127.0.0.1:8000].
artisan> route:list
artisan> migrate

```

It fuses two workflows into one prompt: the ergonomics of an artisan command runner and the power of a Tinker/PsySH PHP REPL.

---

Requirements
------------

[](#requirements)

- PHP **8.2+**
- Laravel **10, 11, or 12** (`illuminate/console`, `illuminate/contracts`, `illuminate/support` `^10|^11|^12`)
- `psy/psysh` `^0.12.20`, `symfony/process` `^6.4|^7`

Installation
------------

[](#installation)

```
composer require amims71/lara-shell
```

The service provider (`Amims71\LaraShell\LaraShellServiceProvider`) is **auto-discovered** — no manual registration needed.

To customize behavior, optionally publish the config file:

```
php artisan vendor:publish --tag=lara-shell-config
```

This copies `config/lara-shell.php` into your app's `config/` directory.

Quick start
-----------

[](#quick-start)

Launch the shell:

```
php artisan shell
```

The command is also registered under the aliases `terminal` and `repl`, so `php artisan terminal` and `php artisan repl` open the same shell.

Then just type commands at the `artisan>` prompt:

```
artisan> serve
artisan> route:list
artisan> migrate

```

New here? Type **`help`** (or `h`) for a built-in guide to everything the shell can do, and **`help `** for a specific command's usage. A short hint is printed on launch.

---

Features
--------

[](#features)

### `help` and `h` — the built-in guide

[](#help-and-h--the-built-in-guide)

Type `help` (or its aliases `h`, `about`, `guide`) for an overview of everything the shell does. Pass a command name to see its usage, arguments, and options — rendered from the live command catalog, no subprocess:

```
artisan> help
artisan> help migrate      # usage, arguments and options for migrate

```

The shell prints a one-line hint on launch pointing you at `help` and `palette`.

### Bare-word artisan commands

[](#bare-word-artisan-commands)

Type any artisan command name (with its usual arguments and options) with no `artisan` prefix. It runs against your application:

```
artisan> make:model Post -m
artisan> queue:work --queue=high
artisan> config:cache

```

### Fuzzy matching, `palette`, and `?`

[](#fuzzy-matching-palette-and-)

You don't have to type the full command name. lara-shell resolves input in tiers:

1. Exact name or alias.
2. Unambiguous prefix abbreviation — `mig` → `migrate` (when only one command starts with it).
3. Colon-segment abbreviation — `m:f` → `migrate:fresh`, `r:l` → `route:list`.
4. fzf-style subsequence match, when there is a single clear winner.

```
artisan> r:l          # resolves to route:list
artisan> m:f          # resolves to migrate:fresh

```

When you want to browse or search the catalog, use the `palette` command (aliased `?`):

```
artisan> palette
+-------------------+------------------------------------------+
| Command           | Description                              |
+-------------------+------------------------------------------+
| ...               | ...                                      |

artisan> palette migrate
artisan> ? route

```

With no query, `palette` lists commands name-sorted; with a query it ranks by fuzzy score against command names and descriptions.

### PHP eval / Tinker fusion — the `;` escape

[](#php-eval--tinker-fusion--the--escape)

Anything that isn't a known command runs as PHP, exactly like Tinker (lara-shell is built on PsySH). You can also **force** a line to be treated as PHP by prefixing it with `;` (the `php_escape` character). This is useful when your PHP expression would otherwise collide with a command name:

```
artisan> User::count()
= 42

artisan> ; migrate('a string variable, not the command')

```

An empty line and any line starting with `;` are always classified as PHP.

### Background jobs — `&`, `jobs`, `kill`, `logs`

[](#background-jobs---jobs-kill-logs)

Append `&` to any artisan command to run it detached in the background:

```
artisan> queue:work &
Started background job a1b2c3d4 (queue:work)

```

Commands listed under `long_running` in the config (`serve`, `queue:work`, `horizon`, `pail`, `octane:start`, …) are backgrounded **automatically**, so you don't need the trailing `&`:

```
artisan> serve
Started background job 9f8e7d6c (serve)

```

Manage running jobs with the meta-commands:

```
artisan> jobs
+----------+------------+---------+--------+
| ID       | Command    | Status  | Uptime |
+----------+------------+---------+--------+
| a1b2c3d4 | queue:work | running | 3m12s  |
+----------+------------+---------+--------+

artisan> logs a1b2c3d4          # print the job's captured output
artisan> logs a1b2c3d4 --follow # or: logs a1b2c3d4 -f  (tail live)

artisan> kill a1b2c3d4          # terminate the job and its process tree
Killed job a1b2c3d4.

```

Jobs are tracked in a shared file registry, so `jobs`, `logs`, and `kill` see jobs started from any lara-shell session in the same project.

### Aliases and `@macro`s

[](#aliases-and-macros)

**Aliases** rewrite the first word of a line. Manage them from inside the shell:

```
artisan> alias add fresh migrate:fresh --seed
Added alias fresh => migrate:fresh --seed

artisan> fresh          # runs: migrate:fresh --seed

artisan> alias list
fresh => migrate:fresh --seed

artisan> alias rm fresh
Removed alias fresh

```

A real command always wins over an alias of the same name, and alias expansion is loop-guarded.

**Macros** are named sequences of steps, invoked with the `@` sigil (`macro_sigil`). Each step is a line (an artisan command, an alias, or another `@macro`). Macros are defined in the per-project `.lara-shell.php` file (see [Configuration](#configuration)):

```
artisan> @deploy          # runs each step of the "deploy" macro in order

```

Macro recursion is loop-guarded and depth-capped.

Both aliases and macros are stored in a per-project **`.lara-shell.php`** file at your application root.

### Production safety guard

[](#production-safety-guard)

When your app is in a guarded environment (by default `production`), destructive commands are gated. The guard has three levels:

- **allow** — runs normally.
- **confirm** — you must **re-type the exact command name** to proceed; anything else aborts.
- **block** — refused outright.

The default config marks a list of destructive commands as **confirm** (`migrate`, `migrate:fresh`, `db:wipe`, `db:seed`, `cache:clear`, `queue:flush`, …). Passing `--force`/`-f` also escalates a command to **confirm** in a guarded environment. Outside guarded environments, everything is allowed.

```
artisan> migrate:fresh
This command is guarded. Re-type "migrate:fresh" to proceed:
migrate:fresh

```

### `reload`

[](#reload)

Refresh the command catalog (and, on drivers that support it, reload code):

```
artisan> reload
Reloaded. Command catalog refreshed.

```

The current cross-platform driver already runs each command in a fresh subprocess, so your code is always current; `reload` refreshes the in-shell command catalog so newly registered commands become resolvable.

---

Configuration
-------------

[](#configuration)

### `config/lara-shell.php`

[](#configlara-shellphp)

Publish it with `php artisan vendor:publish --tag=lara-shell-config`. Keys:

KeyDescription`command.name`The artisan command name (default `shell`).`command.aliases`Command aliases (default `terminal`, `repl`).`driver`Execution driver: `auto` (warm-fork on Unix, subprocess elsewhere), `forking`, or `local`.`long_running`Commands auto-backgrounded without a trailing `&`. Supports `fnmatch` patterns like `queue:*`.`guard.environments`Environments where the safety guard is active (default `['production']`).`guard.block`Commands refused outright in a guarded environment.`guard.confirm`Commands requiring a re-typed confirmation in a guarded environment.`php_escape`Prefix that forces a line to evaluate as PHP (default `;`).`macro_sigil`Prefix that invokes a macro (default `@`).Default config:

```