CLI Session Replay

CLI Session Replay allows you to record terminal sessions in your Node.js CLI applications and replay them in the Statsig Console. Use it 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. Because user input is likely to contain sensitive information, Statsig will 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' },
  {
    loggingEnabled: 'always', // Required for CLI environments
    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 details, refer to 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 session data exceeds 1 MB.

Viewing recordings

CLI session recordings appear in the Statsig Console alongside web session replays. Each recording shows 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 supports:

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