Ohdear Cli Laravel Package

Getting Started

nunomaduro/ohdear-cli is a standalone Laravel Zero CLI, not a package you install into your Laravel app. Install it on your workstation (or CI image) as a global binary:

composer global require nunomaduro/ohdear-cli
export PATH="$PATH:$(composer global config bin-dir --absolute)"
ohdear --help          # or `ohdear list` — this is your map of the tool

Authenticate with a personal API token from the Oh Dear dashboard (Account → API tokens):

ohdear auth

The token is persisted for your OS user, so you only do this once per machine.

Where to look first: run ohdear list and read the command groups. The shape is almost always <resource> <site-or-check-id>, so the first two commands you will actually live in are:

ohdear sites              # find the numeric ID(s) for the apps you own
ohdear site <id>          # full status: uptime, SSL, broken links, cron, etc.

First real use case: during a deploy or an incident, open a terminal next to your logs and run ohdear site <id> to see whether the problem is application-level (your logs) or edge-level (uptime, DNS, certificate, cron ping). Being able to answer "is it just me or is it down for everyone?" without a browser tab is the entire value proposition.

Implementation Patterns

Maintenance windows around deploys. The highest-value day-to-day integration is wrapping deploys so Oh Dear doesn't page anyone during a migration:

#!/usr/bin/env bash
set -euo pipefail
SITE_ID="$1"

ohdear maintenance:start "$SITE_ID" --no-interaction
trap 'ohdear maintenance:stop "$SITE_ID" --no-interaction || true' EXIT

php artisan down --retry=60
php artisan migrate --force
php artisan up

The trap matters: if the deploy dies mid-migration, you still close the window instead of leaving checks silenced.

Deploy hooks. Drop the two maintenance calls into Forge/Envoyer deploy scripts or a GitHub Actions step. Keep the site ID in an env var (OHDEAR_SITE_ID) so the same script works across staging and production.

Cron/scheduler verification. After you touch routes/console.php, Horizon, or a queue worker, confirm the scheduled-job check is actually receiving pings:

ohdear cron-checks <id>

This is the fastest way to prove the problem is your scheduler and not Oh Dear's alerting.

SSL and certificate triage. Before renewing certs, check what Oh Dear currently sees so you do not chase a problem that is already resolved (or miss one that has not propagated yet):

ohdear certificate <id>    # confirm the exact command name with `ohdear list`

Makefile / justfile recipes. Codify the three or four commands you actually use so nobody has to remember IDs:

ohdear-status:
	ohdear site $(OHDEAR_SITE_ID)

ohdear-maint-start:
	ohdear maintenance:start $(OHDEAR_SITE_ID) --no-interaction

ohdear-maint-stop:
	ohdear maintenance:stop $(OHDEAR_SITE_ID) --no-interaction

CI gating. For "don't promote if production is unhealthy," be deliberate: human-readable output is not a contract. Prefer a --json/machine format if your version exposes one; otherwise treat the CLI as an operator tool and shell out to the Oh Dear API directly from CI for anything that must reliably fail a build.

Pairing with webhooks. Let Oh Dear webhooks do the alerting; use the CLI for the response. A Slack alert links to a runbook whose first step is ohdear site <id>.

Gotchas and Tips

• Do not composer require this into your Laravel app. It is a Laravel Zero application with its own binary and dependency tree. Global install (or a downloaded PHAR) only. Pulling it into an app invites command-name collisions and a bloated vendor/.
• Tokens are user-scoped, not project-scoped. What ohdear sites shows depends on the token owner's team memberships. Sharing one token across a team is an anti-pattern — issue per-person tokens so revoking one person does not blind everyone.
• Stored in plaintext on disk. Treat the config file as a secret: keep it out of synced/shared home directories, and in CI inject an ephemeral token from your secret store rather than baking it into a Docker image.
• Interactive prompts break scripts. Commands like maintenance:start may ask for a duration. Always pass --no-interaction plus the explicit flag in automation, and test the exact invocation once by hand first.
• Maintenance windows are time-boxed. Set a sane duration as a belt-and-braces guard even though you call maintenance:stop — a CI runner that dies before trap fires should not silence monitoring for a week.
• Results are eventually consistent. "Check now"-style actions and newly created sites take time to reflect real state. If you script a verify step immediately after a deploy, sleep or poll rather than asserting on a stale snapshot.
• Rate limits apply. Looping the CLI over every site in a watch is rude to the API. Cache site lists, and prefer one site <id> call per poll.
• Output formatting is not an API. Column layouts and wording change between releases. Pin the CLI version in CI (composer global require nunomaduro/ohdear-cli:^X) and never grep for prose you do not control.
• Exit codes are not guaranteed to reflect health. A command that prints "site is down" may still exit 0. Do not build a CI gate on $? without verifying it on a known-failing site.
• This is a client, not monitoring. It cannot observe anything Oh Dear is not already checking. If a check does not exist for the site, no CLI command will conjure it — fix the gap in the dashboard first.
• Extension points are limited on purpose. It is a thin API wrapper built on Laravel Zero; if you need custom logic, write it against ohdearapp/ohdear-php-sdk in your own artisan command rather than forking the CLI.