# 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.
Statsig plans to record user input in a future version. Because user input is likely to contain sensitive information,
Statsig releases it after introducing methods to pause, filter, or redact recordings.

## Installation

Install the CLI session replay package for Node.js:

{% tabs %}
{% tab title="npm" %}
```bash
npm install @statsig/js-client @statsig/cli-session-replay-node
```
{% /tab %}

{% tab title="yarn" %}
```bash
yarn add @statsig/js-client @statsig/cli-session-replay-node
```
{% /tab %}

{% tab title="pnpm" %}
```bash
pnpm add @statsig/js-client @statsig/cli-session-replay-node
```
{% /tab %}
{% /tabs %}

## Basic usage

```javascript
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');
```

{% callout type="note" %}
**CLI logging requirement**: CLI applications must set `loggingEnabled: 'always'` when initializing the StatsigClient. By default, Statsig enables logging only in browser environments. CLI session replay requires you to enable logging in all environments to capture and send session data.
{% /callout %}

## Configuration options

The `StatsigCliSessionReplayPlugin` accepts optional configuration:

```javascript
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](https://docs.asciinema.org/manual/asciicast/v2/#header). Common fields include:
  * `title`: Human-readable title for the recording
  * `command`: The command that ran
  * `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:

```javascript
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