Console administration

WarnFire command-line client

Install and inspect heartbeat jobs, describe status pages, and manage planned component maintenance.

The warnfire client monitors a job by reporting its start and completion to a heartbeat monitor . Install it on the machine that runs the job. The client does not create a monitor in the console; create one first and copy its ping URL.

Client 1.1.0 also manages planned maintenance for status-page components . The installed executable is warnfire (warnfire.exe on Windows). Use warnfire version to check its version and source commit.

Commands

warnfire version prints a client version plus the exact build commit, for example warnfire 1.0.0 (commit abc123…). The commit identifies the binary; the client version names its command behavior. The client version is separate from the server release version.

Status-page commands

These commands require client 1.1.0 or later and a workspace credential. Read commands require the status-pages:read API-key scope. Pause and resume additionally require status-pages:manage and config:manage. An authorized tenant console session can also be used. API keys with status-pages:manage can request page publication or withdrawal through the public API.

Set WARNFIRE_API_URL to the API origin for your environment; it defaults to https://api.warnfire.com. Remote API origins must use HTTPS. Supply exactly one credential source: WARNFIRE_API_TOKEN, injected securely into the environment, or WARNFIRE_API_TOKEN_FILE, pointing to a private regular file. On Unix the file must deny group and other access, such as mode 0600. Never put a token in a command argument or commit it to a repository. Status commands do not run a local job.

warnfire version
warnfire status list
warnfire status describe "Customer API" --page "Service status"
warnfire status pause "Customer API" --page "Service status"
warnfire status pause "Customer API" --page "Service status" --for 20m --reason "Reboot"
warnfire status resume "Customer API" --page "Service status"

Use an exact page title or component name, or its UUID. Quote names containing spaces. --page selects the page when a component name is ambiguous; ambiguous matches are refused without changing anything. Selecting a page pauses or resumes all its mapped components. Selecting a component affects its enabled linked services, including services shared with other components.

Pause defaults to 30 minutes. --for accepts Go-style durations from 1m through 24h, in whole seconds. --reason is optional and applies only to Pause. The window ends automatically; Resume ends the selected page or component’s window early. Repeating Pause while its window is already active does not extend it. Existing incidents and other overlapping maintenance windows are preserved, and the customer page stays online.

Describe shows current status, service mappings, and maintenance. Add --json to any status command for structured output. Use Describe after a transport failure to check the server’s current state before retrying a write. See the status-page guide for web and mobile controls, manual display overrides, and publication.

run options

Client 1.2.0 or later accepts repeatable --message=TEXT and --json=JSON options before -- to record event messages after the start check-in. Use warnfire log --run-id UUID --text TEXT or --json JSON to append a later message. Each run allows 20 messages of at most 4096 UTF-8 bytes each. JSON must be a nonempty object or a text string. See Record event messages for examples and run details.

--protocol=native uses WarnFire path actions and is the default. --protocol=cronitor uses Cronitor-style states on the WarnFire ping URL. The environment variable WARNFIRE_HEARTBEAT_PROTOCOL sets the same choice; the option takes precedence. The required -- ends client options. Everything after it is the job executable and its arguments. If the job needs pipes, redirection, or other shell operators, call a shell explicitly, such as warnfire run -- /bin/sh -c 'command1 | command2'.

Set one URL source:

The client removes those variables from the child job’s environment. It forwards stdin, stdout, and stderr, but sends the combined last 16 KiB of stdout and stderr to WarnFire with the completion check-in. This diagnostic tail can contain secrets if the job prints them. WarnFire applies the monitor’s exit-code set to the numeric code. Without a set, 0 succeeds and nonzero codes fail. Writing to stderr alone does not determine the result. The wrapper still returns the original child exit code, even when a mapping classifies it as successful in WarnFire.

The client runs the job even if a check-in fails and returns the job’s exit code. Usage or configuration errors return 2; failure to start the job returns 127. A lost check-in appears on stderr as a safe error without printing the ping URL.

job install options

warnfire job install --name NAME --scheduler cron|systemd|kubernetes \
  --schedule SPEC --url-stdin -- /absolute/path/to/job [args...]

The CLI creates ~/.config/warnfire/jobs/NAME/url with mode 0600 and a runner with mode 0700. $XDG_CONFIG_HOME replaces ~/.config when set. Cron entries and systemd units contain only the managed file paths. Kubernetes gets a managed Secret, CronJob, and WarnFire CLI init container in the specified context and namespace. Install while logged in as the account that will run the job. job install sets up the next scheduled run; use run separately to test the job immediately.

job status checks that the cron entry exists, the systemd timer is enabled and active, or the managed Kubernetes CronJob and Secret exist. It does not verify the last run; check Heartbeats → History for that. job remove stops future runs and deletes the managed URL file. It does not delete the monitor or its incident history.

See the step-by-step cron and systemd examples .

Docker, Kubernetes, and Windows

For scheduled Docker containers, warnfire job install --scheduler cron or --scheduler systemd can wrap an attached docker run command. The Docker job guide covers image layout, private URLs, exit status, output, and verification.

job install --scheduler kubernetes applies a managed Secret and CronJob through kubectl; see the full EKS, AKS, and GKE guide . Windows Task Scheduler uses a different installation model and is not yet managed by job install. The wrapper command warnfire run works inside a Windows scheduled task when its URL is provided securely.