> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novita.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Reference

Complete reference for all NovitaClaw CLI commands.

## `launch`

Create a new sandbox instance.

```bash CLI icon="terminal" theme={"system"}
novitaclaw launch [OPTIONS]
```

| Option | Description |
| - | - |
| `--api-key` | Novita API key |
| `--gateway-token` | Custom gateway token (optional, auto-generated by default) |
| `--timeout` | Creation timeout in seconds (default: `60`) |
| `--type` | Sandbox type: `persistent` (default) or `on-demand` |
| `--idle-timeout` | Idle timeout in seconds for on-demand mode (default: `300`, range: 60–86400) |

## `list`

List active sandbox instances.

```bash CLI icon="terminal" theme={"system"}
novitaclaw list --api-key YOUR_API_KEY
```

| Option | Description |
| - | - |
| `--api-key` | Novita API key |
| `--quiet`, `-q` | Only print sandbox IDs, one per line (useful for scripting) |

## `status`

Check a sandbox instance status. Displays webhook URLs for all configured channels.

```bash CLI icon="terminal" theme={"system"}
novitaclaw status --api-key YOUR_API_KEY
```

| Option | Description |
| - | - |
| `--api-key` | Novita API key |
| `--json` | Output in JSON format (useful for extracting webhook URLs) |

## `stop`

Terminate a sandbox instance.

```bash CLI icon="terminal" theme={"system"}
novitaclaw stop --api-key YOUR_API_KEY
```

| Option | Description |
| - | - |
| `--api-key` | Novita API key |
| `--yes`, `-y` | Skip confirmation prompt |

## `pause`

Pause a sandbox instance. Zero billing while paused.

```bash CLI icon="terminal" theme={"system"}
novitaclaw pause --api-key YOUR_API_KEY
```

## `resume`

Resume a paused sandbox instance (\~1s to restore).

```bash CLI icon="terminal" theme={"system"}
novitaclaw resume --api-key YOUR_API_KEY
```

## `config set`

Update sandbox runtime configuration.

```bash CLI icon="terminal" theme={"system"}
# idle-timeout range: 60–86400 seconds
novitaclaw config set idle-timeout 600
# timeout in seconds
novitaclaw config set timeout 3600
```

## `tui`

Connect to a sandbox via terminal UI.

```bash CLI icon="terminal" theme={"system"}
novitaclaw tui --token YOUR_GATEWAY_TOKEN
```

## `doctor`

Run diagnostics and repair checks on a sandbox instance.

```bash CLI icon="terminal" theme={"system"}
novitaclaw doctor --api-key YOUR_API_KEY
```

| Option | Description |
| - | - |
| `--api-key` | Novita API key |
| `--deep` | Scan system services for extra gateway installs |
| `--fix` | Apply recommended repairs (alias for `--repair`) |
| `--force` | Apply aggressive repairs (overwrites custom service config) |
| `--generate-gateway-token` | Generate and configure a gateway token |
| `--no-workspace-suggestions` | Disable workspace memory system suggestions |
| `--repair` | Apply recommended repairs without prompting |
| `--yes` | Accept defaults without prompting |

## `gateway update`

Update OpenClaw to the latest version inside a sandbox.

```bash CLI icon="terminal" theme={"system"}
novitaclaw gateway update --api-key YOUR_API_KEY
```

| Option | Description |
| - | - |
| `--api-key` | Novita API key |
| `--restart` | Restart gateway after update |

## `gateway restart`

Restart the OpenClaw Gateway in a sandbox.

```bash CLI icon="terminal" theme={"system"}
novitaclaw gateway restart --api-key YOUR_API_KEY
```

## `services setup`

Install and start Web Terminal and File Manager on an existing sandbox. Use this to add services to older sandboxes that were launched before these services were included.

```bash CLI icon="terminal" theme={"system"}
novitaclaw services setup --api-key YOUR_API_KEY
```

## `pair list`

List pending pairing requests for a channel.

```bash CLI icon="terminal" theme={"system"}
novitaclaw pair list --channel CHANNEL --api-key YOUR_API_KEY
```

## `pair approve`

Approve a pairing request for a channel.

```bash CLI icon="terminal" theme={"system"}
novitaclaw pair approve --channel CHANNEL --code CODE --api-key YOUR_API_KEY
```

## `pair feishu`

Configure Feishu (Lark) as a messaging channel.

```bash CLI icon="terminal" theme={"system"}
novitaclaw pair feishu \
  --app-id cli_xxx \
  --app-secret secret_xxx \
  --mode webhook \
  --verification-token tok_xxx \
  --encrypt-key key_xxx
```

| Option | Description |
| - | - |
| `--app-id` | Feishu app ID |
| `--app-secret` | Feishu app secret |
| `--mode` | `event` (default) or `webhook` |
| `--verification-token` | Webhook verification token (webhook mode only) |
| `--encrypt-key` | Webhook encrypt key (webhook mode only) |
| `--webhook-host` | Webhook bind address (default: `0.0.0.0`) |
| `--webhook-port` | Webhook listen port (default: `3000`) |
| `--webhook-path` | Webhook URL path (default: `/feishu/events`) |

## `pair telegram`

Configure Telegram as a messaging channel.

```bash CLI icon="terminal" theme={"system"}
# Polling mode (default)
novitaclaw pair telegram --bot-token YOUR_BOT_TOKEN

# Webhook mode
novitaclaw pair telegram \
  --bot-token YOUR_BOT_TOKEN \
  --mode webhook \
  --webhook-url https://example.com/webhook/telegram \
  --webhook-secret YOUR_SECRET
```

| Option | Description |
| - | - |
| `--bot-token` | Telegram bot token from BotFather |
| `--mode` | `polling` (default) or `webhook` |
| `--webhook-url` | Public webhook URL (webhook mode only) |
| `--webhook-secret` | Webhook secret (webhook mode only) |
| `--webhook-host` | Webhook bind address (default: `0.0.0.0`) |
| `--webhook-port` | Webhook listen port (default: `8787`) |
| `--webhook-path` | Webhook URL path (default: `/webhook/telegram`) |
| `--dm-policy` | DM policy (default: `pairing`) |

## `pair slack`

Configure Slack as a messaging channel.

```bash CLI icon="terminal" theme={"system"}
# Socket mode (default)
novitaclaw pair slack --bot-token xoxb-... --app-token xapp-...

# HTTP mode
novitaclaw pair slack \
  --bot-token xoxb-... \
  --mode http \
  --signing-secret YOUR_SIGNING_SECRET
```

| Option | Description |
| - | - |
| `--bot-token` | Slack bot token (`xoxb-...`) |
| `--app-token` | Slack app token (`xapp-...`, socket mode only) |
| `--mode` | `socket` (default) or `http` |
| `--signing-secret` | Slack signing secret (HTTP mode only) |
| `--webhook-host` | Webhook bind address (default: `0.0.0.0`) |
| `--webhook-port` | Webhook listen port (default: `8788`) |
| `--webhook-path` | Webhook URL path (default: `/webhook/slack`) |

## `update`

Check for CLI updates and upgrade to the latest version.

```bash CLI icon="terminal" theme={"system"}
novitaclaw update
```

***

## Programmatic Usage

Use JSON output for automation:

```bash CLI icon="terminal" theme={"system"}
novitaclaw -j launch --api-key YOUR_API_KEY
```

Example response:

```json JSON icon="code" theme={"system"}
{
  "success": true,
  "data": {
    "sandbox_id": "...",
    "webui": "https://...",
    "gateway_ws": "wss://...",
    "gateway_token": "...",
    "terminal_url": "https://...",
    "filemanager_url": "https://...",
    "services_username": "admin",
    "services_password": "..."
  }
}
```

***

## Environment Variables

| Variable | Description |
| - | - |
| `NOVITA_API_KEY` | API key, eliminates the need for `--api-key` flag |
| `OPENCLAW_GATEWAY_TOKEN` | Preset gateway token |

***

## Troubleshooting

### Command not found

Try one of these:

```bash CLI icon="terminal" theme={"system"}
# Linux
~/.local/bin/novitaclaw launch

# macOS (typical path)
~/Library/Python/3.x/bin/novitaclaw launch
```

### Connection timeout

Increase launch timeout:

```bash CLI icon="terminal" theme={"system"}
novitaclaw launch --timeout 180 --api-key YOUR_API_KEY
```

***

## Frequently Asked Questions

| Problem | Why it happens | What to do |
| - | - | - |
| "Command not found" / "Not recognized" | Python PATH not configured during install | Reinstall Python and check "Add to PATH", or add the bin directory manually |
| "Permission Denied" | Insufficient permissions | Windows: Run Terminal as Administrator. Mac/Linux: prefix with `sudo` |
| "Invalid API Key" | Key copied incorrectly | Check for extra spaces around the `sk_` string, or generate a new key |
| Sandbox won't stop | Requires confirmation to prevent accidental deletion | Type `y` when prompted, or use `--yes` to skip confirmation |
| Mac: `pip` command not found | macOS uses `pip3` by default | Use `pip3 install novitaclaw` instead of `pip` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.