@fingerprintiq/pulse

Privacy-respecting CLI usage analytics and machine fingerprinting. Like PostHog, but for CLI tools and AI agents.

Zero dependencies. <5KB gzipped. Respects DO_NOT_TRACK.

• Docs: docs.fingerprintiq.com/guides/pulse
• npm: npmjs.com/package/@fingerprintiq/pulse
• Issues: github.com/fingerprintiq/pulse/issues

Install

npm install @fingerprintiq/pulse

Quick Start

import { Pulse } from '@fingerprintiq/pulse';

const pulse = new Pulse({
  apiKey: 'fiq_live_...',
  tool: 'my-cli',
  version: '2.4.1',
});

await pulse.track('command:deploy', {
  target: 'production',
  durationMs: 3400,
});

await pulse.track('command:init', {
  template: 'react',
});

// Call before process exits
await pulse.shutdown();

What You Get

• Unique machines — deduplicated by hardware fingerprint, not IP
• Command analytics — which commands are used, error rates, durations
• Environment breakdown — CI vs local vs container
• Version adoption — how fast users upgrade
• Retention — machine-level return rates

Privacy First

• DO_NOT_TRACK=1 or FINGERPRINTIQ_OPTOUT=1 disables all collection
• Hostnames, MAC addresses, disk serials are SHA-256 hashed before leaving the machine
• No PII ever transmitted
• Offline-safe — network failures are swallowed and never affect CLI behavior
• CLI never blocks or fails due to analytics
• Timer uses .unref() — never keeps your process alive
• track() queues locally and returns without waiting on FingerprintIQ network calls

Machine Fingerprint Signals (26 total)

| Signal | Purpose | |--------|---------| | OS + arch | Platform identity | | OS version | macOS 15, Ubuntu 22.04, Windows 11 | | Hostname (hashed) | Machine identity | | CPU model + cores | Hardware fingerprint | | Memory | Hardware class | | Network MACs (hashed) | Stable identity across IP changes | | Shell | zsh, bash, fish, powershell | | Terminal emulator | iTerm2, VS Code, Terminal.app, etc. | | Terminal columns | Display context | | Is TTY | Interactive vs piped/scripted | | Node.js version (full + major) | Runtime version tracking | | process.versions | v8, openssl, libuv, zlib versions | | Package manager | npm, yarn, pnpm, bun | | Node version manager | nvm, fnm, volta, asdf | | CI provider | GitHub Actions, GitLab CI, CircleCI, etc. | | Container type | Docker, Codespaces, WSL, Gitpod | | WSL distro | Ubuntu, Debian, etc. on WSL | | System uptime | Machine age indicator | | Locale + timezone | Regional context |

Configuration

const pulse = new Pulse({
  apiKey: 'fiq_live_...',       // Required
  tool: 'my-cli',              // Required — your CLI tool name
  version: '1.0.0',            // Required — current version
  endpoint: 'https://...',     // Custom endpoint
  respectOptOut: true,         // Honor DO_NOT_TRACK (default: true)
  flushInterval: 30000,        // Auto-flush interval in ms (default: 30000)
  maxBatchSize: 25,            // Max events per flush (default: 25)
  requestTimeout: 1000,        // Network timeout in ms (default: 1000)
});

Sibling Packages

| Package | Purpose | |---------|---------| | @fingerprintiq/js | Browser fingerprinting | | @fingerprintiq/server | Server-side caller classification (Hono, Express) | | @fingerprintiq/pulse | CLI usage analytics (this package) | | fingerprintiq (PyPI) | Python SDK — Identify, Sentinel, Pulse |

Contributing

This repo is a read-only public mirror. The master copy lives in the private FingerprintIQ monorepo and is synced here on every push to main. Please file issues rather than PRs.

License

MIT