npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@datafast/cli

v0.5.35

Published

Official CLI for DataFast analytics

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Maintainers

mcnaveenmcnaveenmarclou94marclou94

Keywords

datafastanalyticscli

Readme

DataFast logo

The DataFast CLI

Official CLI for DataFast — query analytics and manage your account from the terminal. Useful for AI agents and LLMs 🤖

Looking for the SDK? See DataFast package on NPM

1. Install

npm install -g @datafast/cli

2. Authenticate

datafast login

Create a new account API token in the DataFast dashboard under Settings → API tokens and paste it into the CLI.

3. Use (commands)

Most commands are interactive when you omit IDs or required flags. For example, datafast analytics overview prompts you to choose a website when using a dft_ account token, and datafast websites update opens a guided editor. Press Ctrl+C at any prompt to exit cleanly.

Account

datafast whoami

Websites

datafast websites
datafast websites list
datafast websites get <websiteId>
datafast websites create --domain example.com --timezone America/New_York --name "My Site"
datafast websites update <websiteId> --name "New Name"
datafast websites update
datafast websites update <websiteId> --include-renewal-revenue false
datafast websites delete <websiteId> [--yes]
datafast websites kpi

# Team
datafast websites team list <websiteId>
datafast websites team invite <websiteId> --email [email protected]
datafast websites team invite <websiteId> --email [email protected] --role member
datafast websites team remove <websiteId> <userId>

--include-renewal-revenue only controls KPI calculations such as revenue per visitor. Raw revenue metrics still include new and renewal revenue.

Access Tokens

datafast tokens list
datafast tokens create --name "CI token" --permissions "analytics:read,websites:read"
datafast tokens create --name "Full access" --permissions "*"
datafast tokens create --name "Scoped" --permissions "*" --websites <id1>,<id2>
datafast tokens delete <tokenId> [--yes]

Valid permissions: analytics:read, websites:read, websites:write, api-keys:read, api-keys:write, team:read, team:write, alerts:read, alerts:write, settings:read, settings:write, or * for full access.

Alerts

datafast alerts
datafast alerts list
datafast alerts list <websiteId>
datafast alerts get <websiteId> <alertId>
datafast alerts create <websiteId> --name "New sale" --goal "purchase"
datafast alerts create <websiteId> --name "New sale" --goal "purchase" --subject "🎉 New sale!" --message "Someone converted"
datafast alerts update <websiteId> <alertId> --disabled
datafast alerts update <websiteId> <alertId> --enabled
datafast alerts delete <websiteId> <alertId> [--yes]
datafast alerts history <websiteId>

Analytics

Run datafast analytics to choose and run a report interactively, or use a subcommand directly. When using a dft_ account token, analytics commands prompt you to choose a website if you do not pass --website or configure a default website.

All analytics commands accept:

| Flag | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------- | | --website <id> | Website ID — required when using dft_ token; not needed with df_ site key | | --website-id <id> | Alias for --website | | --period <period> | Dashboard preset: today, yesterday, last24h, last7d, last30d, last12m, week, month, year, all | | --from <date> | Custom range start as YYYY-MM-DD, or an exact ISO timestamp with Z/offset | | --to <date> | Custom range end as YYYY-MM-DD, or an exact ISO timestamp with Z/offset | | --fields <fields> | Comma-separated fields to include | | --limit <n> | Max results (default: 50) | | --offset <n> | Pagination offset (default: 0) | | --timezone <tz> | Optional IANA timezone override, e.g. America/New_York | | -F, --filter <filter> | Dashboard-style analytics filter. Repeat to combine filters. |

Date and timezone rules:

  • Prefer --period for dashboard presets. These are resolved like the dashboard for the website timezone.
  • Use --from YYYY-MM-DD --to YYYY-MM-DD for custom calendar ranges. Date-only values are interpreted by the API in the website timezone unless --timezone is provided.
  • Do not use bare datetimes like 2024-01-01T00:00:00; they are ambiguous and rejected. Exact instants must include Z or an offset, like 2024-01-01T00:00:00Z or 2024-01-01T00:00:00-08:00.

Analytics filters

Analytics commands mirror the dashboard filter system. Use repeatable filters to drill down into a segment, then run another breakdown or time series on that same segment.

Generic syntax:

datafast analytics <report> --filter <key>=<value>
datafast analytics <report> --filter <key>:<operator>=<value>
datafast analytics <report> --filter <key>=<operator>:<value>

--filter can be repeated and also has the short alias -F.

Operators:

| Operator | Meaning | | --- | --- | | is | Include matching values. This is the default. | | is_not | Exclude matching values. | | contains | Partial match. Only supported for page and entry_page. | | does_not_contain | Negative partial match. Only supported for page and entry_page. |

Valid filter keys:

| Group | Keys | | --- | --- | | URL | hostname, page, entry_page | | Source | referrer, ref, source, via | | UTM | utm_source, utm_medium, utm_campaign, utm_term, utm_content | | Location | country, region, city | | System | browser, os, device | | Custom | goal |

Friendly aliases are available for the same keys: --country, --region, --city, --browser, --os, --device, --referrer, --page, --entry-page, --hostname, --goal, --utm-source, --utm-medium, --utm-campaign, --utm-term, --utm-content, --ref, --source, and --via.

Examples:

# Dashboard equivalent: Country is United States + OS is iOS
datafast analytics overview --website <id> --country "United States" --os iOS

# Docs pages only, then rank pages inside that segment
datafast analytics pages --website <id> --filter page:contains=/docs --limit 25

# Mobile visitors from the United States, grouped by referrer
datafast analytics referrers --website <id> --country "United States" --device mobile

# Exclude internal docs traffic and return a revenue time series
datafast analytics timeseries --website <id> --fields visitors,revenue,payments --interval day \
  --filter page:does_not_contain=/docs

# Compare paid campaign traffic
datafast analytics campaigns --website <id> \
  -F utm_source=google,facebook \
  -F country="United States"

# Visitors who completed a payment goal, grouped by country
datafast analytics countries --website <id> --goal payment --period last30d

Notes:

  • Filters are sent to the same analytics API format used by the dashboard: filter_<key>=<operator>:<values>.
  • Multiple values in one filter are comma-separated, e.g. --filter country="United States,Canada".
  • Repeating the same key with the same operator merges the values.
  • Do not mix different operators for the same key in one command.
  • realtime and metadata are not segmentable reports; filters are for overview, timeseries, and analytics breakdowns.

Revenue fields:

  • overview and timeseries revenue is total business revenue from payments.
  • payments is the purchase/payment count shown beside revenue.
  • Breakdown commands such as pages, referrers, countries, browsers, and os return attributed revenue for revenue attribution.

    Breakdown revenue is attribution data: it shows which pages, sources, countries, and devices influenced new revenue. For up to 30% better attribution accuracy, set up proxy tracking because ad blockers can block tracking scripts.

# Overview
datafast analytics overview
datafast analytics overview --website <id>
datafast analytics overview --website <id> --period today
datafast analytics overview --website <id> --period last30d
datafast analytics overview --website <id> --from 2024-01-01 --to 2024-01-31
datafast analytics overview --website <id> --fields visitors,revenue,payments
datafast analytics overview --website <id> --country "United States" --os iOS

# Time series
datafast analytics timeseries
datafast analytics timeseries --website <id>
datafast analytics timeseries --website <id> --period last24h
datafast analytics timeseries --website <id> --fields visitors,sessions --interval day
datafast analytics timeseries --website <id> --fields visitors,revenue,payments --interval month --from 2024-01-01 --to 2024-12-31
datafast analytics timeseries --website <id> --fields visitors,revenue,payments --interval day --filter page:contains=/docs

# Breakdowns
datafast analytics pages
datafast analytics pages      --website <id> --period month
datafast analytics pages      --website <id> --filter page:contains=/docs
datafast analytics referrers  --website <id>
datafast analytics referrers  --website <id> --country "United States" --device mobile
datafast analytics countries  --website <id>
datafast analytics regions    --website <id>
datafast analytics cities     --website <id>
datafast analytics browsers   --website <id>
datafast analytics devices    --website <id>
datafast analytics os         --website <id>
datafast analytics campaigns  --website <id>
datafast analytics goals      --website <id>
datafast analytics hostnames  --website <id>
datafast analytics metadata   --website <id>

# Realtime
datafast analytics realtime
datafast analytics realtime --website <id>

Visitors

datafast visitors list --visited-page /pricing --period last30d
datafast visitors list --visited-page-contains /docs --completed-goal signup --period last30d
datafast visitors list --referrer Google --country France --period last30d
datafast visitors get <datafast_visitor_id>
datafast visitors get <datafast_visitor_id> --website <id>

visitors list returns matching visitor IDs with lightweight identity and acquisition context. Use visitors get to drill into one visitor and return identity, activity, completed goals, visited pages, and prediction data when available.

visitors get returns one canonical goal timeline:

  • activity.completedGoals — all completed goals, sorted by time.
  • Each goal has an origin: manual for goals tracked by the user with the SDK/API, or payment_provider for automatic goals created by connected payment providers.

Automatic payment-provider goals include payment, free_trial, and subscription lifecycle goals such as trial_started, subscription_started, subscription_renewed, and subscription_ended. They include useful metadata when available, such as provider, providerCustomerId, providerSubscriptionId, amount, currency, and MRR deltas.

Visitor drilldown use cases:

# "Show me who visited /pricing in the last 30 days"
datafast visitors list --visited-page /pricing --period last30d

# "Show me who read docs and then signed up"
datafast visitors list --visited-page-contains /docs --completed-goal signup --period last30d

# "Show me customers from a launch campaign"
datafast visitors list --utm-campaign launch --is-customer --period last30d

# "Show me who churned today"
datafast visitors list --completed-goal subscription_ended --period today

# Then drill into a visitor profile
datafast visitors get <datafast_visitor_id>

visitors get returns the Identify profile when available: profile.userId, profile.metadata, and profile.identifiedAt. It also returns payment provider goals in activity.completedGoals, which lets you inspect a visitor's full lifecycle timeline from first visit to payment, renewal, upgrade, downgrade, cancellation, or churn. See user identification to connect anonymous visitors to your own users.

When you set up revenue attribution with a payment provider, DataFast can map SaaS lifecycle events back to visitors. This lets an AI agent answer questions like "who started a trial today?", "who subscribed?", or "who churned today?", then use visitors get to return profile data from Identify.

Automatic payment-provider goals you can use with --completed-goal:

  • payment
  • free_trial
  • trial_started
  • trial_converted
  • subscription_started
  • subscription_upgraded
  • subscription_downgraded
  • subscription_renewed
  • subscription_cancel_scheduled
  • subscription_reactivated
  • subscription_ended

These names are reserved for DataFast payment-provider events. Use them to filter visitors from Stripe, Polar, LemonSqueezy, Paddle, and Shopify revenue flows; do not reuse them as custom goal names.

Funnels

datafast funnels
datafast funnels list
datafast funnels list <websiteId>
datafast funnels view <websiteId> <funnelId>
datafast funnels view <websiteId> <funnelId> --period last30d
datafast funnels view <websiteId> <funnelId> --country "United States"
datafast funnels view <websiteId> <funnelId> --filter referrer=Google
datafast funnels create <websiteId>
datafast funnels update <websiteId> <funnelId> --name "Checkout v2"
datafast funnels delete <websiteId> <funnelId> [--yes]

funnels view returns a terminal funnel with visitors, step conversion, drop-off, and attributed revenue. It accepts the same dashboard-style filters as analytics commands, including --country, --device, --referrer, --utm-source, and repeatable --filter flags.

Output

Pretty-printed JSON by default. Use --json anywhere for compact (CI-friendly) output:

datafast --json analytics overview --website <id>
datafast --json websites list | jq '.[].domain'

Testing locally (without publishing)

cd packages/datafast-cli
npm install
npm run build

# Run directly
node dist/index.js --help

# Or link globally
npm link
datafast --help

Test against local dev server:

DATAFAST_API_BASE=http://localhost:3000 DATAFAST_TOKEN=dft_xxx node dist/index.js whoami

Type-check:

npm run check-types

CLI Auth

There are two token types. They look similar, but they are used for different jobs:

| Token type | Where it is created | Scope | Analytics commands | Account-level commands (tokens, account settings) | Website management (websites, alerts, funnels, team) | Needs --website for analytics? | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | dft_ account token | Created from the DataFast dashboard API tab. This is what datafast login opens by default. | Account-level. Can access the account and any websites allowed by the token permissions. | ✅ | ✅ | ✅ | ✅ Yes, unless you set a default with datafast config set-website <websiteId>. | | df_ website API key | Created manually per website from Website settings → API, or with datafast websites apikeys create. | One website only. Built for analytics/API access to that website. | ✅ | ❌ | ❌ for account-level commands. Limited website-scoped reads may work, but do not use it to manage your account. | ❌ No. The website is implied by the key. |

In practice:

  • Use datafast login for the normal CLI setup. It redirects you to the DataFast dashboard where you create a dft_ account token, then the CLI stores it in ~/.config/datafast/config.json.
  • Use a dft_ token when you want the CLI or an AI agent to manage your DataFast account: list websites, create websites, create tokens, update settings, manage alerts, funnels, API keys, and team members.
  • Use a df_ website API key when you only want analytics access for one website. This is useful for read-only reporting, scripts, and AI agents that should not manage the whole account. See the API authentication docs.

Login (saves token to ~/.config/datafast/config.json):

datafast login                    # masked prompt
echo $MY_TOKEN | datafast login   # stdin
datafast login --token dft_xxx    # inline flag (avoid: leaks to shell history)

Environment variables (override config file):

DATAFAST_TOKEN=dft_xxx            # user token
DATAFAST_SITE_KEY=df_xxx          # analytics-only site key
DATAFAST_API_BASE=http://localhost:3000  # default: https://datafa.st