Node Tmux

https://github.com/starlanestudios/node-tmux
Admin
Node Tmux is a lightweight Node.js wrapper that allows you to programmatically manage tmux sessions...
Tokens:4,109
Snippets:36
Trust Score:7.8
License:ISC
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install node-tmux with npm

Source: https://github.com/starlanestudios/node-tmux/blob/master/README.md

Install the node-tmux package using npm. Ensure tmux is installed on the machine before proceeding.

```bash
npm install --save node-tmux
```

--------------------------------

### Send input to tmux sessions with node-tmux

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Illustrates sending commands with or without a newline character, and automating multi-step processes like deployments or server setups.

```javascript
import { tmux } from 'node-tmux';

async function sendCommand(sessionName, command) {
  const tm = await tmux();

  // Send command and execute it (with newline/Enter)
  await tm.writeInput(sessionName, command, true);
  console.log(`Executed "${command}" in session "${sessionName}"`);
}

// Send text without executing (no Enter key)
async function typeText(sessionName, text) {
  const tm = await tmux();

  await tm.writeInput(sessionName, text, false);
  console.log(`Typed "${text}" in session "${sessionName}"`);
}

// Automated deployment example
async function deployApplication() {
  const tm = await tmux();

  // Create deployment session
  await tm.newSession('deploy');

  // Execute deployment commands
  await tm.writeInput('deploy', 'cd /var/www/app', true);
  await tm.writeInput('deploy', 'git pull origin main', true);
  await tm.writeInput('deploy', 'npm install', true);
  await tm.writeInput('deploy', 'pm2 restart all', true);

  console.log('Deployment commands sent to session');
}

// Interactive automation
async function automateServerSetup() {
  const tm = await tmux();

  if (!await tm.hasSession('setup')) {
    await tm.newSession('setup');
  }

  // Run multiple commands sequentially
  const commands = [
    'apt update',
    'apt install -y nginx',
    'systemctl start nginx',
    'systemctl enable nginx'
  ];

  for (const cmd of commands) {
    await tm.writeInput('setup', cmd, true);
    // Add delay between commands if needed
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
}

sendCommand('my-server', 'npm run build');
```

--------------------------------

### Configure node-tmux options

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Demonstrates how to initialize the library with custom shell paths or specific tmux binary locations.

```javascript
import { tmux } from 'node-tmux';

// Default options (tmux command from PATH)
const defaultOptions = {};

// Custom shell configuration
const customShellOptions = {
  shell: '/bin/zsh'  // Use zsh instead of default shell
};

// Custom tmux binary path
const customTmuxOptions = {
  command: '/opt/homebrew/bin/tmux'  // macOS Homebrew path
};

// Full configuration
const fullOptions = {
  shell: '/bin/bash',
  command: '/usr/local/bin/tmux'
};

async function initWithOptions() {
  // For systems with tmux in non-standard location
  const tm = await tmux({
    command: '/snap/bin/tmux',  // Snap installation path
    shell: '/bin/bash'
  });

  return tm;
}

initWithOptions();
```

--------------------------------

### tmux() - Initialize Tmux Instance

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Initializes the tmux instance by validating the presence of the tmux binary on the system.

```APIDOC
## tmux()

### Description
Validates that tmux is installed on the system and returns a Promise that resolves to a Tmux instance. This is the entry point for all operations.

### Parameters
#### Request Body
- **options** (object) - Optional - Configuration object containing 'shell' (string) and 'command' (string) paths.

### Response
#### Success Response (200)
- **instance** (object) - A Tmux instance object used for further operations.
```

--------------------------------

### Configuration Options

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Details on how to configure the node-tmux client.

```APIDOC
## POST /api/tmux/init

### Description
Initializes the tmux client with optional configuration for the shell and tmux binary path.

### Method
POST

### Endpoint
/api/tmux/init

### Parameters
#### Request Body
- **shell** (string) - Optional - The path to the shell to use (e.g., \"/bin/zsh\"). Defaults to the system's default shell.
- **command** (string) - Optional - The path to the tmux binary (e.g., \"/opt/homebrew/bin/tmux\"). Defaults to finding tmux in the system's PATH.

### Request Example
```json
{
  "shell": "/bin/bash",
  "command": "/snap/bin/tmux"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the tmux client was initialized.

#### Response Example
```json
{
  "message": "Tmux client initialized with custom options."
}
```
```

--------------------------------

### Initialize Tmux Instance

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Initialize the Tmux instance. This validates tmux availability and must be called before other operations. It can accept custom shell or tmux binary paths.

```javascript
import { tmux } from 'node-tmux';

// Basic initialization
async function initializeTmux() {
  try {
    const tm = await tmux();
    console.log('Tmux initialized successfully');
    return tm;
  } catch (error) {
    console.error('Tmux not found:', error.message);
    // Output: Tmux not found: Failed to locate tmux command (exit code 127)
  }
}

// With custom options
async function initializeWithOptions() {
  const tm = await tmux({
    shell: '/bin/bash',    // Custom shell path
    command: '/usr/local/bin/tmux'  // Custom tmux binary path
  });
  return tm;
}

initializeTmux();
```

--------------------------------

### Build node-tmux Project

Source: https://github.com/starlanestudios/node-tmux/blob/master/README.md

Compile the node-tmux project for self-use. This command outputs the compiled JavaScript files into the `/lib` directory.

```bash
npm run build
```

--------------------------------

### Obtain Tmux Instance

Source: https://github.com/starlanestudios/node-tmux/blob/master/README.md

Retrieve an instance of tmux to execute commands. This validates the existence of tmux on the system. Handles 'command not found' errors.

```javascript
import {tmux} from 'node-tmux';

tmux().then(tm => {

	// Use your tm instance

}).catch(() => {

	// Command not found

});
```

--------------------------------

### newSession(name, command?) - Create New Session

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Creates a new detached tmux session with a unique name and an optional startup command.

```APIDOC
## newSession(name, command?)

### Description
Creates a new detached tmux session. Session names must be unique and cannot contain quotes or semicolons.

### Parameters
#### Path Parameters
- **name** (string) - Required - The unique name for the new session.
- **command** (string) - Optional - A command to execute within the new session.
```

--------------------------------

### Input Sending API

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

API for sending input to a specified tmux session.

```APIDOC
## POST /api/sessions/writeInput

### Description
Sends text input to a specified tmux session. Optionally appends an Enter keypress to execute the command.

### Method
POST

### Endpoint
/api/sessions/writeInput

### Parameters
#### Request Body
- **name** (string) - Required - The name of the session to send input to.
- **input** (string) - Required - The text input to send.
- **newline** (boolean) - Optional - If true, appends an Enter keypress to execute the command.

### Request Example
```json
{
  "name": "my-server",
  "input": "npm run build",
  "newline": true
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the input was sent.

#### Response Example
```json
{
  "message": "Executed \"npm run build\" in session \"my-server\""
}
```
```

--------------------------------

### listSessions() - List All Sessions

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Retrieves a list of all currently active tmux session names.

```APIDOC
## listSessions()

### Description
Returns an array of strings containing the names of all currently active tmux sessions.

### Response
#### Success Response (200)
- **sessions** (array) - An array of strings representing active session names.
```

--------------------------------

### Tmux Session Management API

Source: https://github.com/starlanestudios/node-tmux/blob/master/README.md

Methods for managing tmux sessions including creation, listing, renaming, and termination.

```APIDOC
## newSession(name, command)

### Description
Creates a new tmux session with the given name.

### Parameters
- **name** (string) - Required - The name of the new session.
- **command** (string) - Optional - The command to run in the session.

## listSessions()

### Description
Returns an array listing all current tmux session names.

## hasSession(name)

### Description
Checks if a session by the given name exists.

### Parameters
- **name** (string) - Required - The name of the session to check.

## killSession(name)

### Description
Kills the session with the given name.

### Parameters
- **name** (string) - Required - The name of the session to kill.

## renameSession(name, newName)

### Description
Renames an existing tmux session.

### Parameters
- **name** (string) - Required - The current name of the session.
- **newName** (string) - Required - The new name for the session.

## writeInput(name, print, newline)

### Description
Writes a string to the specified tmux session.

### Parameters
- **name** (string) - Required - The name of the session.
- **print** (string) - Required - The string to write.
- **newline** (boolean) - Optional - Whether to append a newline character.
```

--------------------------------

### Terminate tmux sessions with node-tmux

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Demonstrates how to kill a specific session by name or iterate through all active sessions to terminate them.

```javascript
import { tmux } from 'node-tmux';

async function terminateSession(sessionName) {
  const tm = await tmux();

  try {
    await tm.killSession(sessionName);
    console.log(`Session "${sessionName}" terminated`);
  } catch (error) {
    console.error('Failed to kill session:', error.message);
    // Output if not exists: Failed to kill session: Session 'my-server'does not exist
  }
}

// Clean up all sessions
async function killAllSessions() {
  const tm = await tmux();

  const sessions = await tm.listSessions();

  for (const name of sessions) {
    await tm.killSession(name);
    console.log(`Killed session: ${name}`);
  }

  console.log(`Terminated ${sessions.length} session(s)`);
}

terminateSession('my-server');
```

--------------------------------

### Rename tmux sessions with node-tmux

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Shows how to rename an existing session and perform conditional renaming based on session existence.

```javascript
import { tmux } from 'node-tmux';

async function renameSession(oldName, newName) {
  const tm = await tmux();

  try {
    await tm.renameSession(oldName, newName);
    console.log(`Session renamed from "${oldName}" to "${newName}"`);
  } catch (error) {
    console.error('Failed to rename session:', error.message);
  }
}

// Rename for better organization
async function organizeSessionNames() {
  const tm = await tmux();

  // Rename sessions to follow a naming convention
  if (await tm.hasSession('server')) {
    await tm.renameSession('server', 'prod-server');
  }

  if (await tm.hasSession('worker')) {
    await tm.renameSession('worker', 'prod-worker');
  }

  console.log('Sessions renamed for production');
}

renameSession('dev-server', 'staging-server');
```

--------------------------------

### Session Management API

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

APIs for managing tmux sessions, including terminating and renaming them.

```APIDOC
## POST /api/sessions/kill

### Description
Terminates the tmux session with the specified name. Throws an error if the session does not exist.

### Method
POST

### Endpoint
/api/sessions/kill

### Parameters
#### Request Body
- **name** (string) - Required - The name of the session to terminate.

### Request Example
```json
{
  "name": "my-server"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the session was terminated.

#### Response Example
```json
{
  "message": "Session \"my-server\" terminated"
}
```

## POST /api/sessions/rename

### Description
Renames an existing tmux session from the current name to a new name. The session must exist for this operation to succeed.

### Method
POST

### Endpoint
/api/sessions/rename

### Parameters
#### Request Body
- **name** (string) - Required - The current name of the session.
- **newName** (string) - Required - The new name for the session.

### Request Example
```json
{
  "name": "dev-server",
  "newName": "staging-server"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the session was renamed.

#### Response Example
```json
{
  "message": "Session renamed from \"dev-server\" to \"staging-server\""
}
```
```

--------------------------------

### List All Tmux Sessions

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Retrieve a list of all active tmux session names. Returns an empty array if no sessions are currently running.

```javascript
import { tmux } from 'node-tmux';

async function getAllSessions() {
  const tm = await tmux();

  const sessions = await tm.listSessions();

  if (sessions.length === 0) {
    console.log('No active tmux sessions');
  } else {
    console.log('Active sessions:');
    sessions.forEach((name, index) => {
      console.log(`  ${index + 1}. ${name}`);
    });
  }

  // Output example:
  // Active sessions:
  //   1. my-server
  //   2. node-app
  //   3. dev-server

  return sessions;
}

getAllSessions();
```

--------------------------------

### Create New Tmux Session

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Create a new detached tmux session with a unique name. Optionally, a command can be executed within the new session upon creation. Session names cannot contain quotes or semicolons.

```javascript
import { tmux } from 'node-tmux';

async function createSessions() {
  const tm = await tmux();

  // Create a basic session
  try {
    await tm.newSession('my-server');
    console.log('Session "my-server" created');
  } catch (error) {
    console.error('Failed to create session:', error.message);
    // Output if exists: Failed to create session: Session 'my-server' already exists
  }

  // Create a session with a startup command
  await tm.newSession('node-app', 'node server.js');
  console.log('Session "node-app" created running node server.js');

  // Create a session for running a development server
  await tm.newSession('dev-server', 'npm run dev');
  console.log('Session "dev-server" created');
}

createSessions();
```

--------------------------------

### hasSession(name) - Check Session Existence

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Checks if a specific tmux session exists by name.

```APIDOC
## hasSession(name)

### Description
Returns a boolean indicating whether a session with the given name currently exists.

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the session to check.

### Response
#### Success Response (200)
- **exists** (boolean) - True if the session exists, false otherwise.
```

--------------------------------

### Check Tmux Session Existence

Source: https://context7.com/starlanestudios/node-tmux/llms.txt

Determine if a tmux session with a specific name exists. This is useful for conditional operations like creating or modifying sessions.

```javascript
import { tmux } from 'node-tmux';

async function checkSession(sessionName) {
  const tm = await tmux();

  const exists = await tm.hasSession(sessionName);

  if (exists) {
    console.log(`Session "${sessionName}" is active`);
  } else {
    console.log(`Session "${sessionName}" does not exist`);
  }

  return exists;
}

// Conditional session creation
async function ensureSession(name, command) {
  const tm = await tmux();

  if (await tm.hasSession(name)) {
    console.log(`Session "${name}" already exists, skipping creation`);
    return;
  }

  await tm.newSession(name, command);
  console.log(`Session "${name}" created successfully`);
}

ensureSession('background-worker', 'node worker.js');
```
Tokens:
Raw