CLI

The rails-pulse command reads your Rails Pulse data from a terminal or a CI script, without opening the dashboard.

Overview

The gem includes a rails-pulse executable. It reads from the JSON API over HTTP, so it never loads your Rails app and can point at any environment you have a token for: your laptop, staging, or production.

Every command is read-only. Output is a table by default; add --json for the raw API response, including its meta envelope.

Setup

Set config.api_token in the app’s initializer, deploy it, then on your machine:

rails-pulse configure

This prompts for the URL, the API token and the mount path (default /rails_pulse). It makes a test request before saving anything, then writes ~/.rails-pulse, readable only by you. Existing values are shown as defaults, so you can run it again to change one.

In CI, set environment variables instead. They take precedence over the file:

export RAILS_PULSE_URL=https://yourapp.com
export RAILS_PULSE_TOKEN=$RAILS_PULSE_API_TOKEN
# RAILS_PULSE_MOUNT_PATH=/admin/pulse   if the engine is not at /rails_pulse

Commands

CommandWhat it lists
rails-pulse routes listTracked routes with request count, latency and errors
rails-pulse requests listIndividual requests
rails-pulse queries listTracked SQL queries and their analysis
rails-pulse jobs listBackground jobs with run counts, failure rates and durations
rails-pulse job_runs listIndividual job runs
rails-pulse exceptions listException groups
rails-pulse exceptions show IDOne exception group with its recent occurrences and backtraces
rails-pulse deployments listRecorded deployments, most recent first, each saying whether the release made things worse
rails-pulse insights showWhat needs attention in one summary period, and whether your thresholds fit
rails-pulse coverage showWhat has been recorded, how recently, and any collection gaps
rails-pulse install INTEGRATIONAgent instructions; see Coding Agents
rails-pulse mcpStart the MCP server

rails-pulse help COMMAND shows every flag for a command.

Common options

Every list command takes:

OptionDescription
--limit NRecords to return, 1 to 500 (default 25)
--offset NRecords to skip, for paging
--since TIMEStart of the window, ISO 8601
--until TIMEEnd of the window, ISO 8601
--jsonRaw JSON output

A timestamp with no zone is read as UTC.

Command-specific options:

CommandOptions
routes list--search (path or controller action), --sort (request_count, avg_duration, error_count), --path and --controller-action (exact lookups)
requests list--status (500, 5xx, 4xx), --path-prefix (start of the route path; a trailing * is dropped)
queries list--sort (total_duration, avg_duration, executions, max_duration), --hashed-sql (exact lookup)
jobs list--job (exact class name), --status failed
job_runs list--job, --status (failed, success, discarded, …)
exceptions list--status (open, resolved, ignored), --search, --sort (last_seen_at, first_seen_at, occurrence_count), --fingerprint (exact lookup, ignores status and window)
exceptions show--occurrences N (1 to 20, default 3)
deployments list--revision (the full revision or the start of one)
insights show--period (hour, day, week, month; default week), --at (ISO 8601, picks the period containing that time)

The exact-lookup flags take the keys shown in alerts and logs — a query’s hashed_sql, an exception group’s fingerprint, a deploy’s revision — and return that one record’s local detail.

Examples

# The last 10 server errors
rails-pulse requests list --status 5xx --limit 10

# Routes ranked by average duration since a deploy
rails-pulse routes list --since 2026-10-01T14:00:00Z --sort avg_duration

# Failed runs of one job
rails-pulse job_runs list --status failed --job ReportJob

# Open exceptions, then one in detail
rails-pulse exceptions list --status open
rails-pulse exceptions show 42

# Did yesterday's release make things worse?
rails-pulse deployments list --limit 1

# What is past its thresholds this week, and do the thresholds fit?
rails-pulse insights show --period week

# Before reading "no errors" as good news, check data is being recorded
rails-pulse coverage show

Using it in CI

Because the CLI only needs a URL and a token, a CI job can check production after a deploy. For example, fail the pipeline when any job failed in the last hour:

since=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)
failed=$(rails-pulse jobs list --status failed --since "$since" --json | jq '.meta.total')
test "$failed" -eq 0

Next Steps