Run artisan on the server

$ grim remote:artisan migrate:status

Production behaves differently from your machine and you need to ask it something: which migrations ran, what a config value resolves to, whether the queue is alive. Or you need it to do one thing, such as clear a cache or restart the workers. grim remote:artisan is php artisan with the deployed app on the other end, without you opening an SSH session and finding the right directory and container first.

It is for one command at a time. To look around inside the container, use grim remote:shell. For anything that is not artisan, such as container status or logs, use grim remote:exec.

Usage

$ grim remote:artisan migrate:status                 # which migrations production has run
$ grim remote:artisan migrate --force                # flags go to artisan untouched
$ grim remote:artisan tinker --execute="echo config('app.url');"
$ grim remote:artisan -- queue:work --help           # artisan's help, not grim's

Run it from the project directory, on a machine where the project's server is registered in ~/.grim/servers.json. That is the machine grim server:add-project was run on.

Arguments and options

Run a Laravel artisan command on the remote production app container

Usage

grim remote:artisan [<args>...]

Arguments

What it actually does

1. Takes everything after the command name as artisan's arguments, options included. grim does not read --force or --env as its own.
2. Finds the server in ~/.grim/servers.json, under the project's deploy name from grim.json. It uses the project's default environment there, which is the first one you registered, production in the usual case.
3. Prints where it is going. Running on shop (203.0.113.10): php artisan migrate:status.
4. Runs it over SSH. As the deploy user, in the project's directory on the server, docker compose exec -T app php artisan …. Output arrives as it is produced.
5. Exits with artisan's exit code, so a script can tell whether the command worked.

Which environment it talks to

There is no environment argument, and that is the main difference from the env:* commands.

So for a project registered with both production and staging, all three remote:* commands reach the one that was registered first. For the other one, connect yourself: ssh deploy@<host>, then cd /opt/shop-staging.

Pitfalls

The server is not registered on this machine

No default environment configured for project "shop". Run `grim server:add-project` first. means servers.json on this machine has no entry for the project. A host in grim.json is not enough for these commands. Work from the machine that registered the project.

--help, -v and -q are taken by grim

grim reads its own global options before it hands anything over, so grim remote:artisan migrate --help shows the help of remote:artisan. Put -- first and everything after it goes to artisan: grim remote:artisan -- migrate --help.

There is no terminal to answer questions in

artisan runs inside the container without a terminal of its own. A command that stops to ask for confirmation in production has nobody to ask. Pass the flag that skips the question, such as --force for migrate.

After it finishes

You are back in your own shell; nothing stays connected. Whoever holds an SSH key for the deploy user can do all of this, and the server keeps no record of it beyond its own logs. The investigation this command is usually part of is written up as the recipe Debug production.

Related spells

Recipes that use it