Global Options - ClawControl

ClawControl supports several command-line flags for version information, help, and launching modes.

Command-Line Flags

Version

Display the ClawControl version:

clawcontrol --version
clawcontrol -v

Output:

clawcontrol v0.2.3

Use this to:

Verify installation
Check for updates
Report bugs (include version in issue reports)

Help

Display command-line help:

clawcontrol --help
clawcontrol -h

Output:

clawcontrol v0.2.3
CLI tool for deploying and managing OpenClaw instances on VPS providers

Usage:
  clawcontrol            Launch the interactive TUI
  clawcontrol --help     Show this help message
  clawcontrol --version  Show the version number
  clawcontrol --update   Update to the latest version

Options:
  -h, --help     Show this help message
  -v, --version  Show the version number
  -u, --update   Update clawcontrol to the latest version

Environment:
  CLAWCONTROL_SKIP_UPDATE=1   Skip the automatic update check on startup

Documentation & source:
  https://github.com/ipenywis/clawcontrol

Update

Update ClawControl to the latest version:

clawcontrol --update
clawcontrol -u

Example output:

[update] Checking for updates...
[update] New version available: v0.2.3 -> v0.2.4
[update] Updating clawcontrol...
[update] Updated to v0.2.4

This command:

Fetches the latest version from npm registry
Updates via bun add -g clawcontrol@latest
Shows progress and success/failure messages
Requires Bun to be installed

ClawControl automatically checks for updates on startup and updates itself unless CLAWCONTROL_SKIP_UPDATE=1 is set.

Interactive TUI (Default)

Launch the interactive text user interface:

clawcontrol

This is the default mode - you don’t need any flags.

Launch Modes

ClawControl has one primary mode:

Interactive TUI Mode (Default)

clawcontrol

Features:

Full-screen terminal interface
Command-based navigation
Real-time feedback
Keyboard-driven
Mouse support (scroll, select)

Requirements:

Terminal with ANSI color support
Minimum 80x24 terminal size
True color support recommended

Configuration

ClawControl stores configuration in:

~/.clawcontrol/
├── deployments/          # Deployment configs
│   ├── prod/
│   │   ├── config.json
│   │   ├── state.json
│   │   └── ssh_key.pem
│   └── staging/
├── templates/            # Templates
│   ├── my-template.json
│   └── ...
├── secrets/              # Saved API keys/tokens
│   ├── hetzner_key1.json
│   ├── anthropic_key1.json
│   └── ...
└── debug.log            # Debug log (if enabled)

Configuration Files

No global configuration file exists. All settings are per-deployment.

Environment Variables

ClawControl supports the following environment variable:

CLAWCONTROL_SKIP_UPDATE

Skip the automatic update check on startup:

CLAWCONTROL_SKIP_UPDATE=1 clawcontrol

Use this when:

You want to stay on a specific version
You’re running in CI/CD pipelines
You’re developing locally and don’t want interruptions
You have network restrictions

The automatic update check runs on every launch (unless skipped) and updates ClawControl if a newer version is available on npm.

Terminal Compatibility

ClawControl works best with modern terminals:

Fully Supported

macOS:

iTerm2 ✓
Warp ✓
Kitty ✓
Alacritty ✓
WezTerm ✓
Terminal.app (macOS 26+) ✓

Linux:

GNOME Terminal ✓
Konsole ✓
Kitty ✓
Alacritty ✓
WezTerm ✓
Terminator ✓

Windows:

Windows Terminal ✓
WSL2 + any Linux terminal ✓

Partial Support

macOS:

Terminal.app (macOS 25 and earlier) - Colors may look wrong

Linux:

xterm - Basic colors only
rxvt - Basic colors only

Not Supported

Windows Command Prompt (cmd.exe)
Windows PowerShell (non-Terminal)
Very old terminals without ANSI support

If you see a yellow warning bar about true color support, consider upgrading your terminal or using an alternative like iTerm2, Kitty, or Windows Terminal.

Color Support

True Color (24-bit)

Recommended for best experience:

# Most modern terminals support this automatically
clawcontrol

Fallback Colors

If your terminal doesn’t support true color:

⚠ Your terminal does not support true color. Colors may look wrong.
For full color support, use Ghostty, iTerm2, Kitty, or WezTerm — or
upgrade to macOS 26+ for Terminal.app true color support.

ClawControl still works, but colors may appear different.

Mouse Support

ClawControl supports mouse interactions:

Click - Select items in lists
Scroll - Scroll through logs and content
Drag - Select text for copying

Keyboard navigation is still recommended for speed.

Text Selection and Copy

Select text with mouse:

Click and drag to select text
Text is automatically copied to clipboard (via OSC 52)
Paste anywhere (Cmd+V / Ctrl+V)

ClawControl uses OSC 52 escape sequences to copy to clipboard. This works over SSH and in tmux/screen.

Performance

System Requirements

Minimum:

512MB RAM
Any modern CPU
50MB disk space

Recommended:

1GB RAM
Multi-core CPU
100MB disk space

Network Requirements

Internet connection required
Outbound HTTPS (443) for API calls
Outbound SSH (22) for server access

Debug Mode

ClawControl logs debug information to:

~/.clawcontrol/debug.log

View logs:

tail -f ~/.clawcontrol/debug.log

Logs include:

API requests/responses
SSH connection attempts
Deployment progress
Error details

Debug logs may contain sensitive information (API keys, tokens). Don’t share logs publicly without redacting secrets.

Exit Codes

ClawControl uses standard exit codes:

0 - Success
1 - General error
2 - Configuration error

Check exit code:

clawcontrol --version
echo $?
# Output: 0

Updates

Automatic Updates

ClawControl automatically checks for updates on every launch and updates itself:

clawcontrol
# If update available:
# [update] New version available: v0.2.3 -> v0.2.4
# [update] Updating clawcontrol...
# [update] Updated to v0.2.4
# [update] Restarting with updated version...

To skip automatic updates:

CLAWCONTROL_SKIP_UPDATE=1 clawcontrol

Manual Update

Force an update check and install:

clawcontrol --update

Check Current Version

clawcontrol --version

Update via Package Manager

You can also update manually via npm/pnpm/bun:

npm install -g clawcontrol@latest
# or
pnpm add -g clawcontrol@latest
# or
bun add -g clawcontrol@latest

Uninstall

Remove ClawControl:

npm uninstall -g clawcontrol

Remove configuration:

rm -rf ~/.clawcontrol/

Removing ~/.clawcontrol/ deletes all deployments, templates, and saved secrets. Back up first if needed.

Node.js Requirements

ClawControl requires Node.js 20.0.0 or higher:

node --version
# Should be v20.0.0 or higher

Install Node.js:

macOS: brew install node
Linux: Use nvm or package manager
Windows: Download from nodejs.org

Package Manager

ClawControl is distributed via npm:

# Install
npm install -g clawcontrol

# Update  
npm update -g clawcontrol

# Uninstall
npm uninstall -g clawcontrol

No other package managers (yarn, pnpm) are officially tested.

Example Usage

Basic Workflow

# Check version
clawcontrol --version

# Launch TUI
clawcontrol

# Inside TUI:
> /new
> /deploy
> /status

Quick Version Check

clawcontrol -v

Get Help

# Command-line help
clawcontrol --help

# In-app help
clawcontrol
> /help

Tips

Add an alias to your shell profile for quick access:

alias cc="clawcontrol"

Then use: cc instead of clawcontrol

Use a terminal multiplexer (tmux/screen) to keep ClawControl running in the background while deployments complete.

Troubleshooting

Command Not Found

clawcontrol: command not found

Solution:

npm install -g clawcontrol

Permission Errors

ERROR: permission denied

Solution:

# Don't use sudo! Fix npm permissions:
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
npm install -g clawcontrol

Old Node.js Version

ERROR: Node.js 20.0.0 or higher is required

Solution:

# Install latest Node.js
nvm install 20
nvm use 20

Colors Look Wrong

See yellow warning bar: Solution:

Use a modern terminal (iTerm2, Kitty, Windows Terminal)
Or upgrade to macOS 26+ for Terminal.app support

Next Steps

Overview

Back to CLI overview

Quick Start

Create your first deployment

Help Command

In-app help reference

Templates

Reusable configurations

Commands

Options

​Command-Line Flags

​Version

​Help

​Update

​Interactive TUI (Default)

​Launch Modes

​Interactive TUI Mode (Default)

​Configuration

​Configuration Files

​Environment Variables

​CLAWCONTROL_SKIP_UPDATE

​Terminal Compatibility

​Fully Supported

​Partial Support

​Not Supported

​Color Support

​True Color (24-bit)

​Fallback Colors

​Mouse Support

​Text Selection and Copy

​Performance

​System Requirements

​Network Requirements

​Debug Mode

​Exit Codes

​Updates

​Automatic Updates

​Manual Update

​Check Current Version

​Update via Package Manager

​Uninstall

​Node.js Requirements

​Package Manager

​Example Usage

​Basic Workflow

​Quick Version Check

​Get Help

​Tips

​Troubleshooting

​Command Not Found

​Permission Errors

​Old Node.js Version

​Colors Look Wrong

​Next Steps

Overview

Quick Start

Help Command

Templates

Build docs developers (and LLMs) love

Command-Line Flags

Version

Help

Update

Interactive TUI (Default)

Launch Modes

Interactive TUI Mode (Default)

Configuration

Configuration Files

Environment Variables

CLAWCONTROL_SKIP_UPDATE

Terminal Compatibility

Fully Supported

Partial Support

Not Supported

Color Support

True Color (24-bit)

Fallback Colors

Mouse Support

Text Selection and Copy

Performance

System Requirements

Network Requirements

Debug Mode

Exit Codes

Updates

Automatic Updates

Manual Update

Check Current Version

Update via Package Manager

Uninstall

Node.js Requirements

Package Manager

Example Usage

Basic Workflow

Quick Version Check

Get Help

Tips

Troubleshooting

Command Not Found

Permission Errors

Old Node.js Version

Colors Look Wrong

Next Steps