Check your circle

$ grim doctor

The first command on a new machine, and the first one on the morning something that worked yesterday does not. grim doctor looks at the machine, not at your code: the tools, Docker, the database, the GitHub login, and a few facts about the project in the current directory.

It is also what to paste when you ask for help. The output leads with the grim version and where it runs from, which is what anyone helping you wants to know first.

Usage

$ grim doctor            # tools, Docker, database, login, project files
$ grim doctor --tls      # why the browser distrusts this project's certificate
$ grim doctor --perf     # timings to send along with "it is slow"
$ grim doctor --logs     # the end of the install and self-update logs

The plain run works anywhere and says more inside a project. --tls and --perf need a project directory. Every mode only looks, except --repair-perms.

Arguments and options

Check local environment for required tools

Usage

grim doctor [--logs] [--perf] [--repair-perms] [--tls]

Options

What it actually does

The plain run prints one line per check, marked ✓, ✗, or - for something that is absent but not wrong.

1. Says what is running. The version, then the path, size and date of the phar, or running from source. When the install or self-update log exists, their paths follow.
2. Checks the tools. PHP against ^8.1, Docker, Compose, Composer, Git, Node and Yarn, each with its version or ✗ Not found. A missing Yarn is shown and does not fail the run.
3. Asks Docker for more than a version. With Docker installed, the daemon has to answer: not running — start Docker Desktop. With Traefik running, ports 80 and 443 have to be bound on the host: not bound: 443 — run `grim up` to recreate.
4. Tries the database. Inside a project it logs in with the DB_* values from .env, reading host.docker.internal as 127.0.0.1. Anywhere else it tries root@127.0.0.1 with no password, which is what grim create-project needs to create a database. Outside a project a failure is only a - line.
5. Looks for a GitHub token. GitHub auth ✓ (anna), or a pointer to grim auth:login.
6. Measures free disk space on the root filesystem. Below 10 GB the check fails and suggests docker system prune.
7. Looks for grim.json and grim.lock in the current directory. Not finding them is never a failure.
8. On WSL2, checks the way to a Windows browser. The mkcert authority shared with Windows, the Windows-side authority file, certutil, the project's entry in the Windows hosts file, and whether a Snap Firefox is on the path.
9. Gives a verdict. All checks passed! and exit code 0, or Some checks failed. Fix the issues above. and exit code 1.

The other modes

Each flag replaces the plain run with one narrower report.

Pitfalls

A green GitHub line does not prove the token works

Doctor only sees that a token is stored. An expired one still gets a ✓. When GitHub refuses you in another command, run grim auth:login again, which validates the token.

The database check needs the mysql client

The check runs the mysql command on your machine. Without the client installed, a project with a healthy database still shows ✗ project DB unreachable as …. Install the client, or trust the app over this one line.

Flags do not combine

grim doctor --logs --tls shows the logs and stops. Only one mode runs, picked in the order --logs, --perf, --repair-perms, --tls, and none of them includes the plain checks. Run them one after another.

--repair-perms has nothing to do with your project

The name suggests storage/ permissions. It touches only leftovers of an old Windows install, and after One or more steps failed. it wants to be run again from an elevated PowerShell.

After it finishes

Fix the ✗ lines and run it again. The usual remedies are close by: grim setup for Traefik and certificates, grim auth:login for the token, grim hosts:windows for the Windows hosts entry.

Related spells

Recipes that use it