Skip to main content

CLI Session Replay (Beta)

CLI Session Replay allows you to record terminal sessions in your Node.js CLI applications and replay them in the Statsig Console. This enables you to understand how users interact with your command-line tools, diagnose issues, and improve the user experience.

The plugin records terminal output and resize events. User input is planned for a future version, but given that it's likely to contain sensitive information, we'll release it after introducing methods to pause, filter or redact recordings.

Installation​

Install the CLI session replay package for Node.js:

npm install @statsig/js-client @statsig/cli-session-replay-node

Basic Usage​

import { StatsigClient } from '@statsig/js-client';
import { StatsigCliSessionReplayPlugin } from '@statsig/cli-session-replay-node';

const client = new StatsigClient(
  'your-client-key',
  { userID: 'user-123' },
  {
    plugins: [new StatsigCliSessionReplayPlugin()],
  }
);

// Recording starts here
console.log('Hello from CLI!');

await client.initializeAsync();

// Your CLI application logic here
console.log('Continue');

Configuration Options​

The StatsigCliSessionReplayPlugin accepts optional configuration:

import { StatsigCliSessionReplayPlugin } from '@statsig/cli-session-replay-node';

const plugin = new StatsigCliSessionReplayPlugin({
  // Override the start timestamp (in milliseconds)
  startTimestamp: Date.now(),
  
  // Custom Asciicast header properties
  asciicastHeader: {
    title: 'My CLI App Session',
    command: 'my-cli-tool --verbose',
    env: {
      TERM: 'xterm-256color',
      SHELL: '/bin/bash'
    },
  }
});

Configuration Properties​

  • startTimestamp (optional): Override the recording start time in milliseconds. Defaults to Date.now().
  • asciicastHeader (optional): Custom properties for the Asciicast header. For detailed information, visit the Asciicast v2 File Format page. Common fields include:
    • title: Human-readable title for the recording
    • command: The command that was executed
    • env: Environment variables relevant to the session
    • theme: Terminal color theme object.

Recording Limits​

  • Duration: Sessions automatically end after 4 hours
  • Size: Recording stops if the session data exceeds 1MB

Viewing Recordings​

CLI session recordings appear in the Statsig Console alongside web session replays. The recordings can be played back to see exactly what happened in the terminal, including:

  • All terminal output
  • Terminal resize events
  • Timing information for each interaction
  • Session metadata and environment details

Manual Recording Control​

You can access the recording instance for manual control:

import { CliRecording } from '@statsig/cli-session-replay-node';

// Check if currently recording
if (CliRecording.isRecording()) {
  console.log('Session is being recorded');
}

// Get current recording instance
const recording = CliRecording.currentRecording;

// Manually finish recording
CliRecording.finish();

Platform Support​

CLI Session Replay is currently supported on:

  • Node.js applications
  • Linux, macOS, and Windows terminals
  • Any terminal that supports standard input/output streams