Skip to content
GRIMOIRY

Run a command on the server

$ grim remote:exec docker compose ps

The question is about the server, not about Laravel. Are all containers up. What did the app log in the last ten minutes. Is the disk full. grim remote:exec runs one command on the host, in the directory the project is deployed to, and brings the output back. You do not have to remember the address, the user or the path.

The command runs on the host, not in a container. For artisan there is grim remote:artisan, and for a shell inside a container grim remote:shell.

Usage

$ grim remote:exec docker compose ps                        # are the containers up
$ grim remote:exec docker compose logs --tail=100 app       # what the app logged
$ grim remote:exec df -h                                    # disk space on the server
$ grim remote:exec sh -c 'docker compose logs app | grep ERROR'

Run it from the project directory, on a machine where the project's server is registered in ~/.grim/servers.json.

Arguments and options

Run an arbitrary shell command in the remote project directory

Usage

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

Arguments

Argument Description
args Command to run (e.g. tail -100 storage/logs/laravel.log) (optional, repeatable)

What it actually does

  1. Takes everything after the command name as the command, options included.
  2. Finds the server in ~/.grim/servers.json, using the project's default environment there. There is no environment argument; grim remote:artisan explains what that means for staging.
  3. Prints where it is going. Running on shop (203.0.113.10): docker compose ps.
  4. Runs it over SSH as the deploy user, after a cd into the project's directory. With a terminal attached, the session is interactive, so docker compose logs -f follows until you press Ctrl+C.
  5. Exits with the command's exit code.

What is in that directory

Less than you might expect. The deployed project's directory holds the docker-compose.yml and the .env. The application's code is inside the image, uploads are in a Docker volume, and a project deployed by grim logs to the containers' output, not to a file. That is why the useful commands here start with docker compose, and why tail storage/logs/laravel.log finds nothing.

Pitfalls

Pipes and redirects do not reach the server

Each word you type is quoted before it is sent, so the server sees |, >, && and * as plain text. Unquoted, your local shell takes them first and pipes grim's output on your machine, which often is what you wanted. To run a pipeline on the server, hand it to a shell as one quoted argument: grim remote:exec sh -c 'docker compose logs app | grep ERROR'.

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

grim reads its own global options wherever they stand. Put -- first to pass them on: grim remote:exec -- df --help.

The server is not registered on this machine

No default environment configured for project "shop". Run `grim server:add-project` first. means servers.json here has no entry for the project. A host in grim.json is not enough for the remote:* commands.

Nothing is filtered and nothing is asked. grim remote:exec docker compose down -v takes production down and deletes its volumes. Treat the command line as what it is: a shell on the server as the deploy user.

After it finishes

You are back in your own shell with the command's exit code, and nothing stays connected. With no arguments at all the command prints its usage with three examples and fails.

grim remote:artisan

Run artisan on the server

Run one artisan command inside the app container of the deployed project, from your own terminal.

grim remote:shell

Step into a server container

Open an interactive bash session inside a container of the deployed project, the app container unless you name another.

grim logs

Read the logs

Show what the containers have been printing, for one service or all of them, on your machine or on a deployed server.

grim server:status

Look over a server

List the servers you have registered, or look at one of them: its containers, its disk, Traefik and its projects.

Recipes that use it

Debug production

Look at the server, read what the app logged, search the log on the server, question the app through artisan, turn the log level up for a while, and go inside the container when nothing else answers.