---
title: CLI Reference
description: Command-line interface for cmux
---

# CLI Reference

cmux includes a command-line tool for controlling the terminal from scripts and other tools.

## Installation

The CLI is bundled with cmux. Inside cmux terminals, it's available automatically. For external use:

```bash
# Create symlink to CLI
sudo ln -sf "/Applications/cmux.app/Contents/MacOS/cmux" /usr/local/bin/cmux
```

## Global Options

| Option | Description |
|--------|-------------|
| `--socket PATH` | Use a custom socket path |
| `--json` | Output in JSON format |
| `--tab ID` | Target a specific tab |
| `--panel ID` | Target a specific panel |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `CMUX_SOCKET_PATH` | Default socket path |
| `CMUX_TAB_ID` | Default tab ID |
| `CMUX_PANEL_ID` | Default panel ID |

## Commands

### Tab Management

#### list-tabs

List all open tabs.

```bash
cmux list-tabs
cmux list-tabs --json
```

#### new-tab

Create a new tab.

```bash
cmux new-tab
```

#### select-tab

Switch to a specific tab.

```bash
cmux select-tab --tab <tab-id>
```

#### current-tab

Get the current tab info.

```bash
cmux current-tab
cmux current-tab --json
```

#### close-tab

Close a tab.

```bash
cmux close-tab --tab <tab-id>
```

### Split Management

#### new-split

Create a new split pane.

```bash
cmux new-split right
cmux new-split down
cmux new-split left
cmux new-split up
```

#### list-panels

List panels in the current tab.

```bash
cmux list-panels
cmux list-panels --json
```

#### focus-panel

Focus a specific panel.

```bash
cmux focus-panel --panel <panel-id>
```

### Input Commands

#### send

Send text to the terminal.

```bash
cmux send "echo hello"
cmux send "ls -la\n"  # Include newline to execute
```

#### send-key

Send a key press.

```bash
cmux send-key enter
cmux send-key tab
cmux send-key escape
```

#### send-panel

Send text to a specific panel.

```bash
cmux send-panel --panel <panel-id> "command"
```

#### send-key-panel

Send a key press to a specific panel.

```bash
cmux send-key-panel --panel <panel-id> enter
```

### Notifications

#### notify

Send a notification.

```bash
cmux notify --title "Title" --body "Message body"
cmux notify --title "Title" --subtitle "Subtitle" --body "Body"
```

#### list-notifications

List all notifications.

```bash
cmux list-notifications
cmux list-notifications --json
```

#### clear-notifications

Clear all notifications.

```bash
cmux clear-notifications
```

### Utility

#### ping

Check if cmux is running and responsive.

```bash
cmux ping
```

## Examples

### Build Script with Notification

```bash
#!/bin/bash
npm run build
if [ $? -eq 0 ]; then
    cmux notify --title "✓ Build Success" --body "Ready to deploy"
else
    cmux notify --title "✗ Build Failed" --body "Check the logs"
fi
```

### Create Tab and Run Command

```bash
#!/bin/bash
# Create a new tab
result=$(cmux new-tab --json)
tab_id=$(echo "$result" | jq -r '.id')

# Select the new tab
cmux select-tab --tab "$tab_id"

# Send a command
cmux send "npm run dev\n"
```

### Monitor Multiple Tabs

```bash
#!/bin/bash
# List all tabs and their directories
cmux list-tabs --json | jq -r '.tabs[] | "\(.title): \(.directory)"'
```