Privacy-Respecting Telemetry Demo CLI

A comprehensive demonstration of how to implement privacy-first telemetry in a TypeScript CLI application. This todo application showcases best practices for collecting anonymous usage analytics while respecting user privacy and providing full transparency and control.

🔒 Privacy-First Telemetry Features

This project demonstrates a complete privacy-respecting telemetry implementation with:

• 🚫 Opt-out by Default: Telemetry is enabled by default but can be disabled at any time
• 🔧 Multiple Control Methods: Environment variables, configuration files, and CLI commands
• 📋 First-Run Disclosure: Clear privacy notice before any data collection begins
• ⚡ Non-blocking: Telemetry never interrupts or slows down the user experience
• 🛡️ Fail-Safe: Silent failures ensure telemetry issues never break the application

🎯 Demo Application Features

The underlying todo CLI includes:

• ✅ Add, list, complete, and delete todos
• 📊 View statistics and productivity graphs
• 🎯 Interactive mode for continuous use
• 💾 Persistent storage in .todos.json
• 🎨 Colorful terminal output
• 📅 Timestamps for task creation and completion

🚀 Installation & Usage

NPM Installation

Install globally via npm:

npm install -g @1984vc/telemetry-todo

Or run directly with npx (no installation required):

npx @1984vc/telemetry-todo <command>

Development Setup

1. Clone the repository:

   git clone https://github.com/1984vc/telemetry-todo.git
   cd telemetry-todo

2. Install dependencies:

   pnpm install

3. Build the project:

   pnpm run build

4. Run the CLI:

   node dist/main.js <command>

Development Mode

Run directly from TypeScript source:

pnpm run dev <command>

📊 Telemetry Privacy Controls

Environment Variables

Control telemetry through environment variables:

# Disable all telemetry (respects DO_NOT_TRACK standard)
export DO_NOT_TRACK=1

# Application-specific telemetry control
export TELEMETRY_TODO_TELEMETRY=false

# Enable telemetry explicitly
export TELEMETRY_TODO_TELEMETRY=true

CLI Commands

Manage telemetry settings directly:

# Check current telemetry status
npx @1984vc/telemetry-todo telemetry status

# Enable telemetry (with privacy disclosure)
npx @1984vc/telemetry-todo telemetry enable

# Disable telemetry
npx @1984vc/telemetry-todo telemetry disable

Configuration File

Settings are stored in .telemetry-config.json:

{
  "telemetryEnabled": true,
  "firstRun": true,
  "anonymousId": "4ff13743-eaeb-4f88-bb69-33fd3638c876"
}

🔍 Privacy-Compliant Data Collection

What We Track (Anonymously)

• Command Usage: Which commands are executed (add, list, done, etc.)
• Performance Metrics: Command execution times for optimization
• Error Events: Anonymous error reporting for debugging
• System Info: Platform and Node.js version (no personal data)
• Country-Level Geographic Data: Country, continent, and timezone information only (for usage patterns)

What We DON'T Track

• ❌ IP addresses (not stored or logged)
• ❌ Personal information or identifiers
• ❌ Todo content or user data
• ❌ File paths or system details
• ❌ Network information

Example Privacy-Compliant Payload

{
  "api_key": "phc_IFaExYAUhS9kpVwk6zTBuk80H1D4Dr6QQdCfu",
  "event": "command_executed",
  "properties": {
    "distinct_id": "4ff13743-eaeb-4f88-bb69-33fd3638c876",
    "$referrer": "$direct",
    "$referring_domain": "$direct",
    "$lib": "telemetry-todo-cli",
    "$lib_version": "1.0.0",
    "$ip": "0.0.0.0",
    "command": "add",
    "platform": "darwin",
    "node_version": "v24.4.1"
  }
}

📝 Todo Commands

Basic Operations

# Add a todo
npx @1984vc/telemetry-todo add "Your task here"

# List all todos
npx @1984vc/telemetry-todo list

# Mark a todo as complete
npx @1984vc/telemetry-todo done <number>

# Delete a todo
npx @1984vc/telemetry-todo delete <number>

# Clear all todos
npx @1984vc/telemetry-todo clear

Advanced Features

# View statistics
npx @1984vc/telemetry-todo stats

# Interactive mode
npx @1984vc/telemetry-todo

# Help
npx @1984vc/telemetry-todo help

🏗️ Technical Implementation

Architecture

telemetry-todo/
├── src/
│   ├── main.ts          # Main CLI with telemetry integration
│   └── telemetry.ts     # Privacy-first telemetry module
├── dist/                # Compiled JavaScript output
├── .telemetry-config.json # User telemetry preferences
├── package.json         # Project configuration
├── tsconfig.json        # TypeScript configuration
└── README.md           # This documentation

Key Technical Features

• Direct HTTPS Requests: Uses Node.js built-in https module instead of heavy SDKs
• Timeout Protection: 1-second timeout prevents hanging requests
• Non-blocking Execution: setImmediate() ensures telemetry never blocks user operations
• Error Resilience: Comprehensive error handling with silent failures
• TypeScript: Full type safety and modern async/await patterns

PostHog Integration

This demo uses PostHog as the analytics backend with privacy-first configuration:

• Endpoint: https://us.i.posthog.com/capture/
• No IP Address: IP Adress is manually set to 0.0.0.0

�️ Privacy Compliance

This implementation follows privacy best practices:

• Transparent: Full disclosure of data collection practices
• User Control: Multiple ways to disable and control telemetry
• Data Minimization: Only collects essential anonymous usage metrics

🔧 Development & Testing

Building

pnpm run build

Testing Telemetry

1. Check telemetry status (enabled by default):

   npx @1984vc/telemetry-todo telemetry status

2. Execute commands and observe privacy-compliant requests:

   npx @1984vc/telemetry-todo add "Test task"
   npx @1984vc/telemetry-todo list

3. If needed, enable or disable telemetry:

   npx @1984vc/telemetry-todo telemetry enable
   npx @1984vc/telemetry-todo telemetry disable

Verifying Privacy Protection

The telemetry module logs request details (in development) showing:

• No personal or identifying information

Learning Outcomes

This demo teaches:

• Privacy-First Design: How to collect useful analytics while protecting user privacy
• Transparent Telemetry: Best practices for user disclosure and consent
• Technical Implementation: Direct HTTP requests, error handling, and non-blocking execution
• User Experience: Ensuring telemetry never degrades application performance

🤝 Contributing

This is a demonstration project showcasing privacy-respecting telemetry implementation. Feel free to:

• Study the code for educational purposes
• Adapt the privacy patterns for your own projects
• Suggest improvements to the privacy implementation
• Report any privacy concerns or issues

📄 License

This project is provided as an educational demonstration of privacy-respecting telemetry implementation.

🔒 Privacy Notice: This application collects anonymous usage analytics by default but respects your privacy. No personal information, IP addresses, or location data is ever collected. You can disable telemetry at any time using the commands above or environment variables.