CLI Commands

Install the local CLI

Run bun run pack:local in the Realanalytics repository. Use the version and filename in dist/local-packages/manifest.json. The examples below use the installed CLI, not an assumed registry release.

# global
npm install -g /path/to/realanalytics-0.1.0.tgz

# use the installed command
realanalytics <command>

Available commands

login

login prints a short code and opens /cli/device in your browser. Sign in, check that the code matches your terminal, and approve the request. The CLI waits for the approval and then saves a 30-day access token. The code expires after 15 minutes.

npx --no-install realanalytics login

# terminal output:
# Your one-time code: BCDF-GHJK
# Waiting for approval...

To use a one-time token from /cli/auth instead, run npx --no-install realanalytics login --paste, or pass the token directly with npx --no-install realanalytics login --token <token>.

init

npx --no-install realanalytics init

Optional project naming: npx --no-install realanalytics init --name my-project.

Creates project credentials and starter files:

• analytics/events.ts
• analytics/dashboards/overview.ts
• .realanalytics/credentials.json

build

npx --no-install realanalytics build

# custom output directory
npx --no-install realanalytics build --output dist/analytics

Output files: events.json and dashboards.json, plus attribution.json when analytics/attribution.ts exists.

deploy

npx --no-install realanalytics deploy

# preview the same diff without persisting anything
npx --no-install realanalytics deploy --dry-run

# report review context with the deploy receipt
npx --no-install realanalytics deploy --pr 42 --reviewer alice --reviewer bob

Runs build and the lint checks, then POSTs compiled JSON to the platform using your project secret key + CLI session token. Both modes print the lint result and one diff with events, dashboards, attribution configs, and breaking changes. Attribution changes are always listed, including a deploy that changes only attribution.ts or deletes it. A dry run reports no changes only when events, dashboards, and attribution are all unchanged. It exits with code 1 when it finds breaking changes. Lint errors do not stop a deploy; the failed result is recorded in the deploy receipt.

Deploy receipts

Each persisted deploy stores a receipt next to the schema version. The CLI reports the context below. Realanalytics validates and bounds every field, but it does not verify them with GitHub. The dashboard labels them as reported and shows Not reported for absent fields. A dry run sends no receipt.

Commit, pull request, and CI run links appear only when the repository and an https server URL are known. Error responses are printed with your project secret key and CLI token redacted. See Governance for how to read the diff.

lint

npx --no-install realanalytics lint

Validates your analytics definitions by checking event references, property references, naming conventions, and unused events. Property references include breakdownBy, defaultBreakdown, widget filters, funnel step filters, and every series event. Each error names the dashboard, widget, and field. Exits with code 1 if errors are found.

See Governance for full details on what the linter checks.

whoami and status

npx --no-install realanalytics whoami
npx --no-install realanalytics status

Typical workflow

# one-time
npx --no-install realanalytics login
npx --no-install realanalytics init

# repeat for changes
npx --no-install realanalytics lint
npx --no-install realanalytics deploy

Next Steps

• CLI configuration files
• Defining dashboards
• SDK tracking