Skip to content

README.md

Latest commit

 

History

History
132 lines (90 loc) · 4.63 KB

README.md

File metadata and controls

132 lines (90 loc) · 4.63 KB

datafast CLI

TypeScript CLI for the DataFast analytics API. Built for terminals, scripts, and AI agents.

$ datafast overview --period 7d

DataFast Overview (7d, Europe/Rome)
┌──────────────────────┬────────────┬────────────┐
│ Metric               │ Value      │ Signal     │
├──────────────────────┼────────────┼────────────┤
│ Visitors             │ 5          │ ↑ positive │
│ Sessions             │ 9          │ ↑ positive │
│ Bounce Rate          │ 44.44%     │ → watch    │
│ Avg Session Duration │ 9h 13m 42s │ ↑ positive │
│ Revenue              │ $ 0.00     │ → neutral  │
└──────────────────────┴────────────┴────────────┘

Why

DataFast has a clean API. This wraps it so you can check your analytics from the terminal — or hand it to an AI agent as a tool.

We battle-tested this by pointing MAF (our agent framework) at it and having it run a full site analysis autonomously. It found a bug. We fixed it. That's the point.

Operator writeups:

Install

# Clone and link globally
git clone https://github.com/fedewedreamlabsio/datafast-cli.git
cd datafast-cli
npm install && npm run build && npm link

Or run directly:

npx @wedreamlabs/datafast-cli overview

Auth

Your DataFast API token is loaded in this order:

  1. DATAFAST_API_KEY environment variable
  2. macOS Keychain (service: datafast-api, account: datafast)
# Set via Keychain (recommended)
security add-generic-password -a datafast -s datafast-api -w '<YOUR_TOKEN>' -U

Commands

datafast overview [--period 7d|30d|90d|all] [--fields visitors,sessions,revenue]

Site overview with metrics, signals, and formatted values.

datafast timeseries [--period 7d] [--interval hour|day|week] [--fields visitors,sessions]

Time series with tables and sparkline charts. Supports filters: --country, --device, --referrer, --page, --utm-source, --utm-medium, --utm-campaign.

datafast top [pages|referrers|countries|devices] [--period 30d] [--limit 10]

Top content, traffic sources, countries, or devices.

datafast live

Real-time visitor count.

datafast visitors <id>

Details for a specific visitor.

Global Options

Flag Description
--json Raw JSON output (pipe to jq, feed to agents)
--version Print version
--help Show help

Agent Integration

The --json flag makes every command agent-friendly. Here's what happened when we pointed MAF at it:

$ maf run --input "Run a full analytics report using the datafast CLI"

Step 0: shell.exec → datafast overview --period 30d         ✅
Step 1: shell.exec → datafast overview --period 7d          ✅
Step 2: shell.exec → datafast top pages --limit 10          ✅
Step 3: shell.exec → datafast top referrers --limit 10      ✅
Step 4: shell.exec → datafast top countries                 ✅
Step 5: shell.exec → datafast top devices                   ✅
Step 6: shell.exec → datafast live                          ✅
Step 7: shell.exec → datafast timeseries --period 7d        ✅
Step 8: fs.write   → analytics-report.md                    ✅

status=completed | 9 steps | 0 errors

The agent ran 8 datafast commands, synthesized a 200-line analytics report, and caught a www/non-www canonicalization issue we'd missed. Full trace in JSONL.

Error Handling

  • API errors show the actual message (not [object Object] — we fixed that)
  • Auth failures print clear Keychain/env var instructions
  • Network errors (timeout, refused, DNS) get friendly messages
  • Empty data shows a message instead of crashing

Tests

npm test  # 31 tests — unit (dates, format) + integration (all commands)

Development

npm run dev -- overview --period 7d   # Run from source
npm run build                          # Compile
npm run typecheck                      # Type check only

License

MIT — Cosmo Kappa