TrackFox CLI

Instrument websites and inspect TrackFox Analytics without leaving the terminal.

Quick start

trackfox config add
trackfox analytics

Create a website-scoped key in TrackFox → Website settings → API. config add asks for the website ID and masks the key, validates both, and stores a named local profile. Add --api-key-stdin to read a key from stdin or --force to replace a profile.

To create and instrument a new site instead:

npx trackfox add

Analytics commands

trackfox analytics [profile]             Dashboard summary and chart
trackfox realtime [profile] --watch      Live visitors
trackfox top-pages [profile]             Most-viewed pages
trackfox entry-pages [profile]           Pages where visits started
trackfox exit-pages [profile]            Pages where visits ended
trackfox exit-links [profile]            Outbound links visitors clicked
trackfox referrers [profile]             Top referrers
trackfox countries [profile]             Visitors by country
trackfox regions [profile]               Visitors by region
trackfox cities [profile]                Visitors by city
trackfox browsers [profile]              Visitors by browser
trackfox devices [profile]               Visitors by device
trackfox operating-systems [profile]     Visitors by operating system
trackfox custom-events [profile]         Custom events
trackfox electron versions [profile]     Electron version adoption

Use --period today|yesterday|last24h|last7d|last30d|wtd|mtd|ytd|all|custom. A custom period also requires --start-date and --end-date. Analytics commands accept --timezone; list commands accept --limit and --all.

Output is formatted as tables by default. Select JSON explicitly with --output json.

trackfox top-pages --period last7d --all --output json | jq '.data'
trackfox analytics --period custom --start-date 2026-07-01 --end-date 2026-07-10

Profiles and security

trackfox config list
trackfox config show [profile]
trackfox config use <profile>
trackfox config remove <profile>

Config lives at %APPDATA%\TrackFox\config.json on Windows and ${XDG_CONFIG_HOME:-~/.config}/trackfox/config.json elsewhere. Keys are redacted in display output. On POSIX the directory and file use 0700 and 0600 permissions.

For CI or temporary use, avoid persistence:

TRACKFOX_WEBSITE_ID=site_123 TRACKFOX_API_KEY=tf_secret trackfox analytics --output json

TRACKFOX_API_URL overrides the API host. TRACKFOX_CONFIG_DIR overrides configuration storage for testing. Rotate or revoke keys in TrackFox settings.

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Unexpected/API service failure | | 2 | Invalid arguments | | 3 | Missing or invalid configuration | | 4 | Authentication or authorization failure | | 5 | Network or timeout failure | | 6 | API validation, rate-limit, or not-found failure | | 130 | Interrupted |

Troubleshooting

• No profile: run trackfox config add.
• Invalid key: create a replacement in Website settings → API, then rerun config add --force.
• Port in use during add: set TRACKFOX_CALLBACK_PORT.
• Network details: set DEBUG=1; credentials remain redacted.
• Plain output: set NO_COLOR=1 or use --no-color.

Requires Node.js 18 or newer. CLI documentation: trackfox.app/docs/cli/overview. API reference: trackfox.app/docs/api-reference/overview.