Command line

The rainlytics command reads analytics from your AWS account.

pnpm exec rainlytics --help

You can also run the package without installing it in a project:

npx @kensio/rainlytics --help

Authentication uses your existing AWS credentials.

Credentials and region

The command uses the AWS SDK default credential chain. It supports named AWS profiles, IAM Identity Center sessions, assumed roles, environment credentials and workload roles.

Choose a profile and region with the normal AWS settings:

AWS_PROFILE=analytics AWS_REGION=us-east-1 rainlytics pageviews --last 7d

Every command that reaches AWS also accepts --region. Athena commands accept --database and --workgroup when the deployment changed their defaults.

The region must contain the Glue table, Athena workgroup and summary bucket. A missing workgroup in the selected region is often a profile or region mistake.

Select your deployment

Use these environment variables or command options to select the deployed resources. The database and workgroup have default names. Stored reads always need a summary bucket name:

Variable	Option	Default
RAINLYTICS_DATABASE	--database	rainlytics
RAINLYTICS_WORKGROUP	--workgroup	rainlytics
RAINLYTICS_SUMMARY_BUCKET	--summaries	none

export RAINLYTICS_DATABASE=analytics
export RAINLYTICS_WORKGROUP=analytics
export RAINLYTICS_SUMMARY_BUCKET=rainlytics-summaries-1a2b
rainlytics pageviews --last 7d

Command options override environment variables. RollupSummaries uses the same variable names for its scheduled jobs.

Read a named question

The named commands cover pageviews, referrers, browsers, status codes, cache hit ratio, searches, JavaScript errors and Web Vitals.

rainlytics pageviews --last 7d
rainlytics referrers --last 30d
rainlytics status-codes --last 24h --include-bots

These commands read precomputed summaries. Name the bucket with an option or environment variable:

rainlytics pageviews --last 7d --summaries rainlytics-summaries-1a2b

export RAINLYTICS_SUMMARY_BUCKET=rainlytics-summaries-1a2b
rainlytics pageviews --last 7d

Use --query to run the same question against raw logs with Athena:

rainlytics pageviews --last 2h --query

This runs an Athena query over the available raw logs and incurs query cost. Missing summaries never trigger an automatic Athena query.

Read a calendar report

report reads one stored report for a closed calendar period:

rainlytics report day 2026-08-30
rainlytics report week 2026-08-24 --time-zone Europe/London
rainlytics report month 2026-07 --compare
rainlytics report year 2025

The time zone and first weekday must match the RollupSummaries deployment. Defaults are UTC and Monday. --compare reads the preceding period too and calculates the changes between both stored reports. Report commands never run Athena.

Reports always use JSON because their period, source coverage and section metadata are part of the answer.

Run saved SQL

RollupQueries stores generated SQL in Athena. Run a saved query by name:

rainlytics saved-query countries

The rainlytics- prefix is optional. countries and rainlytics-countries select the same saved query.

A saved query already contains its range, row limit and filters. It accepts --region, --workgroup and output options, but it does not accept named-rollup filters such as --last or --path.

Use rainlytics query for SQL written at the terminal. See Query.

Output formats

Named questions, saved queries and ad-hoc queries support JSON, CSV and tables.

rainlytics pageviews --last 7d --output table
rainlytics pageviews --last 7d --output json
rainlytics pageviews --last 7d --output csv > pageviews.csv

Without --output, a terminal receives a table and a pipe receives JSON:

rainlytics pageviews --last 7d | jq '.[0].path'

JSON output is an array of row objects. CSV follows RFC 4180 apart from using LF line endings. Table output contains no color codes or trailing spaces.

Import CSV into spreadsheet software with every external-text column set to text. Referrers and user agents come from requests, and a value beginning with =, +, - or @ can be treated as a formula when a CSV file is opened directly.

Output streams and exit codes

Data goes to standard output. Help, warnings, source coverage and query cost go to standard error. Standard output stays empty when a command fails.

Exit code	Meaning
0	The command completed.
1	AWS or the requested operation failed. A retry may succeed.
2	The command line was invalid. The same command will fail again.

Put the command before its options:

rainlytics pageviews --output csv

Run rainlytics <command> --help for the full option list and examples for one command.

Permissions

Reading named questions and reports needs s3:GetObject on the summaries bucket. A normal AWS read-only role often has this access.

Athena operations need query access to the workgroup, Glue catalog reads, raw log reads and writes to the query results bucket. Grant the set with workgroup.grantQuerying(role, table). See Query workgroup.