Nova Command Runner Laravel Package

Getting Started

1. Install the package via Composer:

   composer require guratr/nova-command-runner
   

2. Register the tool in app/Providers/NovaServiceProvider.php inside the tools() method:

   use Guratr\NovaCommandRunner\NovaCommandRunner;
   
   public function tools()
   {
       return [
           new NovaCommandRunner,
       ];
   }
   

3. Publish any config (if the package ships one) so you can control which commands are exposed:

   php artisan vendor:publish --provider="Guratr\NovaCommandRunner\ToolServiceProvider"
   

4. Open Nova, look for the Command Runner entry in the sidebar.

Where to look first: the vendor source (vendor/guratr/nova-command-runner/src) — this is a small (43-star) package with limited public documentation, so the NovaCommandRunner class and its Vue component are the source of truth for available options and command whitelisting behavior.

First use case: running routine php artisan tasks (cache clears, queue restarts, small data migrations) without SSH access — e.g. cache:clear, config:clear, queue:restart, migrate:status. Treat it as a convenience panel for whitelisted, idempotent commands, not a general shell.

Implementation Patterns

• Whitelist-first workflow. Don't expose every artisan command. Maintain an allowlist of commands your team actually needs on the panel (clear caches, restart workers, run storage:link, route:cache, etc.). Anything destructive (migrate:fresh, db:wipe) should be excluded.
• Sidebar grouping via Nova tool registration. Since Nova 4 groups tools automatically, name the tool something clear (Artisan Runner) so it lands in a sensible menu slot.
• Pair with policies/super-admin gates. Restrict the tool to super-admins using Nova's canSee() on the registered tool instance:

  NovaCommandRunner::make()->canSee(fn ($request) => $request->user()->isSuperAdmin()),
  

• Deploy-safe command set. Keep the whitelist in a config or service provider constant so it's version-controlled and reviewed in PRs rather than clicked-and-forgotten in the UI.
• Use it as a break-glass tool, not the primary workflow. The primary path should still be deploy scripts and scheduled commands; the panel is for "oh no, the queue is stuck" moments.
• Audit logging. Wrap usage with a small listener or middleware that logs the user + command + timestamp, since Nova doesn't ship command-run audit trails for tools.
• Cache-heavy workflows. Forgetting config:clear after editing .env is a classic — a Route/Cache/Config clear composite (single command per run) saves clicks.
• Environment gating. Register the tool conditionally so it never appears on production if your security posture requires it:

  if (! app()->environment('production')) {
      // do not register
  }
  

Gotchas and Tips

• Security is the whole ballgame. Anyone with Nova access to this tool is effectively running CLI commands on your server. Restrict aggressively via canSee()/Nova authorization and never expose destructive or arbitrary-input commands.
• Long-running commands will appear to hang. PHP-FPM/Nova HTTP timeouts and browser timeouts will kill the request while the command keeps running server-side (or dies mid-flight). For anything beyond a few seconds, prefer queue:restart-style fire-and-forget commands or run them via a queued job.
• Output is not always streamed. Depending on the package version, output is captured after completion via Artisan::call() and Artisan::output(), so interactive commands (asking for confirmation) will fail or hang — avoid commands that require prompts.
• State mismatch. Artisan::call() runs in the web request's process — env vars, cwd, and loaded config may differ from a CLI shell. If a command behaves oddly from the panel but fine in terminal, suspect config:cache/env differences first.
• Small-package maintenance risk. With only ~43 stars, expect sparse docs and infrequent updates. Pin a version in composer.json and be prepared to read/patch the source (the allowlist logic and Vue component are simple enough to fork).
• Whitelist changes need a cache clear. If the allowlist is cached (config cache), update it and php artisan config:clear before assuming the tool is broken.
• Nova version compatibility. Nova tool registration and asset compilation have changed across Nova 3/4/5 — verify the package supports your Nova major version before adding it to a production dashboard.
• Debugging: if the tool doesn't render, check php artisan nova:publish was run for assets and that the tool provider is auto-discovered (php artisan package:discover). Errors land in storage/logs/laravel.log — tail it while running a command from the UI.
• Extension point: for team-specific needs (e.g., custom command presets, output styling, history), fork the small source into app/Nova/Tools rather than fighting the vendor package.