@trawlme/cli 1.11.0 → 1.13.0

package/README.md

@@ -71,12 +71,54 @@ Skills auto-update silently when you upgrade the CLI — no need to re-install m
 
 You can also install skills standalone (without the CLI): `npx @trawlme/skills install`.
 
+### Telemetry
+
+```
+trawl telemetry on       Enable usage telemetry (default)
+trawl telemetry off      Disable usage telemetry
+trawl telemetry status   Show current state, telemetry ID, and opt-out instructions
+```
+
+## Telemetry
+
+`@trawlme/cli` collects anonymous usage data to help us improve the CLI based on real usage patterns. Telemetry is enabled by default.
+
+**What we collect:**
+- Command name (e.g. `scraps list`)
+- CLI version
+- Node.js version
+- Platform (e.g. `darwin`, `linux`, `win32`)
+- Command duration (`duration_ms`)
+- Exit code (`0` = success, `1` = error)
+- Error name if the command failed (e.g. `ApiError`) — never the error message or stack
+- An opaque, randomly-generated telemetry ID (`cli_<uuid>`) stored locally in your config file
+
+**What we do NOT collect:**
+- Email address or any account identifier
+- Scrap content, scrap URLs, or request bodies
+- Org names or any business data
+- IP address (PostHog EU Cloud anonymises it)
+- Any personally identifiable information (PII)
+
+**How to opt out:**
+
+```bash
+# Permanent opt-out (written to config file)
+trawl telemetry off
+
+# Session-level opt-out (env var, takes precedence)
+TRAWL_TELEMETRY=0 trawl scraps list
+```
+
+**Why:** usage data helps us prioritise CLI features and catch silent errors before users report them.
+
 ## Environment variables
 
-| Variable      | Description                                          |
-|---------------|------------------------------------------------------|
-| `TRAWL_TOKEN` | JWT token — bypasses login prompt, useful for CI/CD |
-| `TRAWL_API_URL` | Override the default API URL (`https://api.trawl.me`) |
+| Variable           | Description                                                       |
+|--------------------|-------------------------------------------------------------------|
+| `TRAWL_TOKEN`      | JWT token — bypasses login prompt, useful for CI/CD               |
+| `TRAWL_API_URL`    | Override the default API URL (`https://api.trawl.me`)             |
+| `TRAWL_TELEMETRY`  | Set to `0` to disable telemetry for the current session           |
 
 ## API documentation
 

package/dist/commands/scraps.js

@@ -91,6 +91,7 @@ scraps
     console.log(chalk.dim(`  Last run: `) + lastRun(data));
     console.log(chalk.dim(`  Updated:  `) + new Date(data.updatedAt).toLocaleString());
 });
+const VALID_TIERS = ['tier0', 'tier1', 'tier2', 'tier3', 'tier4'];
 // create
 scraps
     .command('create')
@@ -99,13 +100,20 @@ scraps
     .option('-u, --url <url>', 'Target URL')
     .option('-r, --request <request>', 'Request/query')
     .option('-d, --description <text>', 'Scrap description')
+    .option('--tier <tier>', `Force proxy tier (${VALID_TIERS.join('|')})`)
     .action(async (opts) => {
+    if (opts.tier !== undefined && !VALID_TIERS.includes(opts.tier)) {
+        console.log(chalk.red(`✗ Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`));
+        process.exitCode = 1;
+        return;
+    }
     const spinner = ora('Creating scrap…').start();
     const data = await api.post('/api/scraps', {
         title: opts.title,
         ...(opts.url && { url: opts.url }),
         request: opts.request || '',
         ...(opts.description !== undefined && { description: opts.description }),
+        ...(opts.tier !== undefined && { proxyTier: opts.tier }),
     });
     spinner.succeed(`Scrap created: ${chalk.bold(data._id)}`);
     console.log(chalk.dim(`  Title: ${data.title}`));
@@ -126,8 +134,14 @@ scraps
     .option('--no-autofix', 'Disable AI Fix')
     .option('-p, --params <json>', 'Runtime params as JSON array of objects (e.g. \'[{"TRAWL.paramName":"value"}]\')')
     .option('--params-file <path>', 'Runtime params from a JSON file')
+    .option('--tier <tier>', `Force proxy tier (${VALID_TIERS.join('|')})`)
     .action(async (id, opts) => {
     validateObjectId(id);
+    if (opts.tier !== undefined && !VALID_TIERS.includes(opts.tier)) {
+        console.log(chalk.red(`✗ Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`));
+        process.exitCode = 1;
+        return;
+    }
     const body = {};
     if (opts.title !== undefined)
         body.title = opts.title;
@@ -174,6 +188,8 @@ scraps
         }
         body.params = parsed;
     }
+    if (opts.tier !== undefined)
+        body.proxyTier = opts.tier;
     if (Object.keys(body).length === 0) {
         console.log(chalk.yellow('Nothing to update. Provide at least one option.'));
         return;

package/dist/commands/telemetry.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const telemetry: Command;

package/dist/commands/telemetry.js

@@ -0,0 +1,43 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import config from '../lib/config.js';
+import { initPostHog } from '../lib/posthog.js';
+export const telemetry = new Command('telemetry').description('Manage CLI telemetry (usage data collection)');
+telemetry
+    .command('on')
+    .description('Enable telemetry (default)')
+    .action(() => {
+    config.set('telemetry', true);
+    // Ensure a telemetryUserId is created on opt-in
+    initPostHog();
+    console.log(chalk.green('✓ Telemetry enabled'));
+    console.log(chalk.dim('  Anonymous usage data will be collected. Run `trawl telemetry status` to view.'));
+});
+telemetry
+    .command('off')
+    .description('Disable telemetry')
+    .action(() => {
+    config.set('telemetry', false);
+    console.log(chalk.green('✓ Telemetry disabled'));
+    console.log(chalk.dim('  No data will be sent. Your telemetry ID is kept for if you re-enable later.'));
+});
+telemetry
+    .command('status')
+    .description('Show current telemetry state')
+    .action(() => {
+    const enabled = config.get('telemetry') !== false;
+    const userId = config.get('telemetryUserId') || '(not yet generated)';
+    const envOverride = process.env['TRAWL_TELEMETRY'] === '0';
+    console.log(chalk.bold('Telemetry status'));
+    console.log(chalk.dim('  State:         ') +
+        (envOverride
+            ? chalk.yellow('disabled (TRAWL_TELEMETRY=0 env var)')
+            : enabled
+                ? chalk.green('enabled')
+                : chalk.yellow('disabled')));
+    console.log(chalk.dim('  Telemetry ID:  ') + userId);
+    console.log('');
+    console.log(chalk.dim('  To opt out:'));
+    console.log(chalk.dim('    trawl telemetry off'));
+    console.log(chalk.dim('    TRAWL_TELEMETRY=0  (env var, disables for this session)'));
+});

package/dist/index.js

@@ -7,8 +7,11 @@ import { dirname, join } from 'node:path';
 import { login, logout } from './commands/login.js';
 import { scraps } from './commands/scraps.js';
 import { skills } from './commands/skills.js';
+import { telemetry } from './commands/telemetry.js';
 import { autoUpdateInstalledSkills } from './lib/skills.js';
+import { initPostHog, captureCommand, shutdown } from './lib/posthog.js';
 autoUpdateInstalledSkills();
+initPostHog();
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 const program = new Command()
@@ -16,11 +19,32 @@ const program = new Command()
     .description('Trawl CLI — manage scraps from the terminal')
     .version(pkg.version)
     .option('--debug', 'Show full error stack traces');
+// Track start times per command instance for duration measurement
+const startTimes = new WeakMap();
+program.hook('preAction', (thisCommand, actionCommand) => {
+    startTimes.set(actionCommand, Date.now());
+});
+program.hook('postAction', (thisCommand, actionCommand) => {
+    const start = startTimes.get(actionCommand);
+    if (start !== undefined) {
+        const name = actionCommand.parent
+            ? `${actionCommand.parent.name()} ${actionCommand.name()}`
+            : actionCommand.name();
+        void captureCommand(name, { duration_ms: Date.now() - start, exit_code: 0 });
+    }
+});
 program.addCommand(login);
 program.addCommand(logout);
 program.addCommand(scraps);
 program.addCommand(skills);
+program.addCommand(telemetry);
+process.on('exit', () => {
+    void shutdown();
+});
 program.parseAsync().catch((err) => {
+    // Capture error telemetry (best-effort: command name from process.argv)
+    const name = process.argv.slice(2).filter((a) => !a.startsWith('-')).join(' ') || 'unknown';
+    void captureCommand(name, { exit_code: 1, error: err.name });
     const { debug } = program.opts();
     if (debug || process.env['DEBUG']) {
         console.error(err);

package/dist/lib/api.js

@@ -1,4 +1,10 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
 import config from './config.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
+const USER_AGENT = `@trawlme/cli/${pkg.version}`;
 class ApiError extends Error {
     status;
     constructor(status, message) {
@@ -59,6 +65,7 @@ async function request(path, options = {}) {
         ...options,
         headers: {
             'Content-Type': 'application/json',
+            'User-Agent': USER_AGENT,
             ...options.headers,
             Cookie: `TOKEN=${token}`,
         },
@@ -89,6 +96,7 @@ async function upload(path, formData) {
         method: 'POST',
         body: formData,
         headers: {
+            'User-Agent': USER_AGENT,
             Cookie: `TOKEN=${token}`,
         },
     });
@@ -112,7 +120,7 @@ async function publicPost(path, body) {
     const url = `${config.get('apiUrl')}${path}`;
     const res = await fetch(url, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', 'User-Agent': USER_AGENT },
         body: body ? JSON.stringify(body) : undefined,
     });
     await throwIfError(res, true);
@@ -146,6 +154,7 @@ export const api = {
         const res = await fetch(url, {
             headers: {
                 Accept: 'text/event-stream',
+                'User-Agent': USER_AGENT,
                 Cookie: `TOKEN=${token}`,
             },
         });

package/dist/lib/config.d.ts

@@ -2,6 +2,8 @@ import Conf from 'conf';
 interface TrawlConfig {
     apiUrl: string;
     token: string;
+    telemetry: boolean;
+    telemetryUserId: string;
 }
 declare const config: Conf<TrawlConfig>;
 export default config;

package/dist/lib/config.js

@@ -4,6 +4,8 @@ const config = new Conf({
     defaults: {
         apiUrl: 'https://api.trawl.me',
         token: '',
+        telemetry: true,
+        telemetryUserId: '',
     },
 });
 export default config;

package/dist/lib/posthog.d.ts

@@ -0,0 +1,5 @@
+export declare const initPostHog: () => void;
+export declare const captureCommand: (command: string, props?: Record<string, unknown>) => void;
+export declare const shutdown: () => Promise<void>;
+/** Reset singleton state — for testing only */
+export declare const _resetForTesting: () => void;

package/dist/lib/posthog.js

@@ -0,0 +1,52 @@
+import { PostHog } from 'posthog-node';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import config from './config.js';
+// public-by-design — cf memory feedback_public_keys_in_config.md
+const POSTHOG_KEY = 'phc_pGgSLivbq8rDZzXC9trWWJG7sBjNghXeTJjETzBcnEDv';
+const POSTHOG_HOST = 'https://eu.i.posthog.com';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
+let client = null;
+let distinctId = null;
+export const initPostHog = () => {
+    if (config.get('telemetry') === false || process.env['TRAWL_TELEMETRY'] === '0')
+        return;
+    if (!config.get('telemetryUserId')) {
+        config.set('telemetryUserId', `cli_${crypto.randomUUID()}`);
+    }
+    distinctId = config.get('telemetryUserId');
+    client = new PostHog(POSTHOG_KEY, {
+        host: POSTHOG_HOST,
+        flushAt: 1,
+        flushInterval: 0,
+    });
+};
+export const captureCommand = (command, props = {}) => {
+    if (!client || !distinctId)
+        return;
+    client.capture({
+        distinctId,
+        event: 'cli.command.run',
+        properties: {
+            command,
+            cli_version: pkg.version,
+            node_version: process.version,
+            platform: os.platform(),
+            source: 'cli',
+            ...props,
+        },
+    });
+};
+export const shutdown = async () => {
+    if (client)
+        await client.shutdown();
+};
+/** Reset singleton state — for testing only */
+export const _resetForTesting = () => {
+    client = null;
+    distinctId = null;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {
@@ -45,6 +45,7 @@
     "commander": "^14.0.3",
     "conf": "^15.1.0",
     "ora": "^9.3.0",
+    "posthog-node": "^4.0.0",
     "strip-ansi": "^7.2.0"
   },
   "devDependencies": {