Command Reference

Global Flags

These flags are available on all commands:

Commands

tow init

Auto-detect project type and generate configuration.

tow init

Scans your project directory and detects:

• Language: Java, Node.js, Python, Go, Rust
• Framework: Spring Boot, NestJS, Express, FastAPI, Django, Flask, Next.js
• Build tool: Gradle, Maven, npm, yarn, pnpm, poetry, uv, cargo
• Monorepo modules: settings.gradle, pom.xml <modules>
• CI/CD: Dockerfile, docker-compose, GitHub Actions, GitLab CI, Jenkins

Generates:

• tow.yaml with detected module types and sensible defaults
• script/{module}/env.sh — environment variables for each module
• script/{module}/server — start/stop/status/restart control script

Note: Library modules (ending in -common, -core, -support, -lib, -shared, -util) are automatically excluded from deployment modules.

tow validate

Validate configuration file without connecting to servers.

tow validate
tow validate -c custom-config.yaml

Checks:

• Required fields (project.name, servers, modules)
• SSH key file existence
• Module type validity
• Health check configuration

tow deploy

Run the deploy pipeline: package → upload → install → stop → start.

tow deploy -e prod -m api-server
tow deploy -e prod -m api-server -s 1    # Deploy to server 1 only
tow deploy -e prod                        # Deploy all modules
tow deploy -e prod --dry-run              # Preview without executing

tow auto

Run the full pipeline: build → package → upload → install → stop → start.

tow auto -e dev -m api-server
tow auto -e prod -m api-server --dry-run

This is the most common command for end-to-end deployment from source code to running service.

tow start

Start a module on remote servers.

tow start -e prod -m api-server
tow start -e prod -m api-server -s 1

After starting, Tow runs health checks based on the module’s health_check configuration.

tow stop

Stop a module on remote servers.

tow stop -e prod -m api-server
tow stop -e prod -m api-server -s 2

tow restart

Stop then start a module.

tow restart -e prod -m api-server

tow status

Check the current status of a module.

tow status -e prod -m api-server

Shows:

• Process ID (PID)
• Uptime
• Memory usage
• Current deployment version (symlink target)

tow rollback

Switch to a previous deployment version.

# Roll back to the previous deployment
tow rollback -e prod -m api-server

# Roll back to a specific version
tow rollback -e prod -m api-server -t 20240626-101530

Rollback is instant — it switches the current symlink and restarts the service. No re-upload or re-build required.

tow logs

Stream remote log files from one or more servers.

tow logs -e prod -m api-server
tow logs -e prod -m api-server -f "ERROR"                 # Filter with grep
tow logs -e prod -m api-server -n 100                     # Last 100 lines
tow logs -e prod -m api-server -s kafka-1                 # Specific server
tow logs -e prod -m api-server -s kafka-1,kafka-3         # Multiple servers (comma-separated)
tow logs -e prod -m api-server --all                      # All servers simultaneously
tow logs -e prod -m api-server -F                         # Follow (live tail)

Log Presets

Save and reuse frequently used log queries:

tow logs -e prod -m api-server -f "ERROR" --save-preset error-logs
tow logs --preset error-logs                              # Replay saved query
tow logs --list-presets                                   # List all saved presets
tow logs --delete-preset error-logs                       # Remove a preset

Multi-Module Logs

Stream logs from multiple modules simultaneously:

tow logs -e prod -m kafka,zookeeper --all -n 5    # multiple modules
tow logs -e prod -m kafka,zookeeper --all -F      # stream multiple modules

Output is prefixed with [module/server] for each line.

tow ssh

Execute ad-hoc commands on remote servers over SSH without opening an interactive session.

tow ssh -e prod -m kafka --all -- "free -h"
tow ssh -e prod -m api-server -s 1 -- "df -h"
tow ssh -e prod -m kafka -s kafka-1,kafka-3 -- "cat /etc/os-release"

The command after -- is executed on every matched server. Output is prefixed with the server name for clarity.

tow diff

Compare deployed code on a remote server against the local build artifact or source.

tow diff -e prod -m api-server
tow diff -e prod -m api-server -s 1

Shows a summary of files that differ between the currently deployed version and the local artifact. Useful for verifying what will change before running tow deploy.

tow config

Manage servers, modules, and assignments in tow.yaml from the command line.

Server management

tow config server add -e prod --name api-3 --host 10.0.1.30
tow config server remove -e prod --name api-3
tow config server list -e prod

Module management

tow config module add --name payment-api --type springboot --port 8083
tow config module remove --name payment-api
tow config module list

Assign / unassign modules to servers

tow config assign -e prod --server api-3 --module payment-api
tow config unassign -e prod --server api-3 --module payment-api

tow setup

Initialize remote server directory structure.

tow setup -e dev
tow setup -e prod -m api-server

Creates on each server:

{base_dir}/{module}-{server_number}/
├── deploy/      # Deployment versions
├── upload/      # Upload staging
├── log/         # Persistent logs
├── conf/        # Persistent configuration
└── {data_dirs}  # Custom data directories

tow upload

Transfer a file to remote servers.

tow upload -e prod -m api-server
tow upload -e prod -m api-server path/to/file.tar.gz

tow install

Extract the uploaded package and update the current symlink.

tow install -e prod -m api-server

Creates a new timestamped directory in deploy/, updates the current symlink, and creates persistent symlinks:

• current/log → {baseDir}/log
• current/{data_dir} → {baseDir}/{data_dir} (for each entry in data_dirs)

This ensures logs and data survive across deployments without manual configuration.

After extract and symlink, the post_install hook runs if defined (e.g., create virtualenvs, run pip install, execute database migrations).

tow list

List configuration information.

tow list modules       # List all modules
tow list envs          # List all environments
tow list deployments -e prod -m api-server  # List deployment history

tow login

Open an interactive SSH session to a server.

tow login -e prod -m api-server -s 1

Tip: When multiple servers or modules match, Tow shows an interactive picker. Use -s to specify a server by name, or -m for a module. If only one is given, Tow lets you pick the other interactively.

tow unlock

Force release a deploy lock.

tow unlock -e prod -m api-server

Use this when a deploy was interrupted and the lock wasn’t cleaned up.

tow cleanup

Remove old deployment directories from remote servers.

tow cleanup -e prod -m api-server              # Keep default (from config or 5)
tow cleanup -e prod -m api-server --keep 3     # Keep only 3 most recent

The current active deployment is never removed. Configure automatic cleanup in tow.yaml:

retention:
  keep: 5
  auto_cleanup: true    # Clean up after every deploy/auto

tow download

Download files from a remote server to local.

tow download -e prod -m api-server logs/std.log
tow download -e prod -m api-server /var/log/syslog -d ./local-logs/

If the path is relative, it’s resolved against the module base directory.

tow provision

Provision a new server with basic requirements.

tow provision -e prod -m api-server --timezone Asia/Seoul --locale en_US.UTF-8 --jre --tools

This also runs tow setup to create the deployment directory structure.

tow threaddump

Trigger a thread dump on Java/Spring Boot modules for debugging.

tow threaddump -e prod -m api-server
tow threaddump -e prod -m api-server -s 1

Sends kill -3 to the JVM process. Thread dump output is written to the application’s log file.

Only available for modules with type springboot or java.

tow plugin

Manage infrastructure plugins.

# List all installed plugins (bundled + external)
tow plugin list

# Install bundled plugins to ~/.tow/plugins/ (for customization)
tow plugin install kafka redis
tow plugin install --all

# Add community plugins from GitHub or URL
tow plugin add someuser/tow-plugin-mssql
tow plugin add myorg/infra-plugins/oracle.yaml
tow plugin add https://example.com/my-plugin.yaml

# Remove
tow plugin remove mssql

35 plugins are bundled in the binary. Community plugins are installed to ~/.tow/plugins/.

See plugins/README.md for the full list and plugin authoring guide.

tow metrics

Show deployment statistics from audit log.

tow metrics                           # last 30 days, all modules
tow metrics -e prod                   # filter by environment
tow metrics -m api-server             # filter by module
tow metrics --days 7                  # last 7 days

Shows total deployments, breakdown by action (deploy/auto/rollback), by module (with bar chart), and by day of week.

tow doctor

Pre-flight diagnostics — checks config, SSH, remote directories, disk space, deploy locks, and server dependencies.

tow doctor -e prod -m api-server --insecure

  ✓ tow.yaml is valid
  ✓ Environment 'prod' exists
  ✓ SSH key exists
  ✓ Servers configured (22)
  ✓ SSH connection to 10.0.1.10
  ✓ Remote dir exists: /home/ec2-user/api-server-1
  ✓ Disk space — Available: 15GB
  ✓ Branch policy
  ✓ No active deploy lock
  ✓ Server dependencies OK

Server Dependency Checks

tow doctor verifies that required tools are available on each remote server:

Missing required tools are reported as errors with install guidance:

  ✗ Missing required: lsof
    → Install: sudo apt install lsof  (or: sudo yum install lsof)
    → Affects: tow status, tow stop, tow doctor
  ⚠ Missing recommended: nc
    → Install: sudo apt install netcat-openbsd  (or: sudo yum install nmap-ncat)
    → Affects: tow start (TCP health check)

Run without -m to check environment-level connectivity.

tow mcp-server

Start the MCP (Model Context Protocol) server for AI agent integration.

tow mcp-server
tow mcp-server -c /path/to/tow.yaml

This exposes Tow operations as tools for AI assistants (Claude, Cursor, Windsurf). See AI Agent Integration below.

Advanced Flags

Rolling Deployment

Deploy to one server at a time, verifying health before proceeding to the next:

tow deploy -e prod -m api-server --rolling
tow auto -e prod -m api-server --rolling
tow start -e prod -m api-server --rolling

Auto-Rollback

Automatically revert to the previous deployment if health check fails after start:

tow auto -e prod -m api-server --auto-rollback

Production Confirmation

Production environments (prod, production, live) require interactive confirmation:

⚠  WARNING: You are about to deploy api-server in PROD
  Type 'yes' to confirm:

Skip with -y / --yes flag (for CI/CD):

tow deploy -e prod -m api-server -y

JSON Output

Machine-readable output for CI/CD pipelines:

tow status -e prod -m api-server -o json
tow list deployments -e prod -m api-server -o json

AI Agent Integration

MCP Server

Configure in Claude Desktop, Cursor, or any MCP-compatible client:

{
  "mcpServers": {
    "tow": {
      "command": "tow",
      "args": ["mcp-server"],
      "env": { "TOW_CONFIG": "./tow.yaml" }
    }
  }
}

Available MCP tools:

Command Pipelines

Note: The install step runs the post_install hook after extraction and symlink creation. Use this for environment setup tasks like creating virtualenvs, running pip install, or executing database migrations.

Dry-Run Mode

Add --dry-run to any command to preview actions without executing:

tow auto -e prod -m api-server --dry-run

[1/6] Building api-server...
  → Would run: ./gradlew :api-server:bootJar
[2/6] Packaging api-server...
  → Would create: build/api-server.tar.gz
[3/6] Uploading to prod-1 (52.78.100.1)...
  → Would SCP: build/api-server.tar.gz → ~/upload/
[4/6] Installing on prod-1...
  → Would extract to: deploy/20240626-143022/
  → Would update symlink: current → deploy/20240626-143022
[5/6] Stopping api-server on prod-1...
  → Would run: bin/server stop
[6/6] Starting api-server on prod-1...
  → Would run: bin/server start