# Tugboat CLI Command Reference ## Global Options | Flag | Description | |------|-------------| | `-V`, `--version` | Output the version number | | `-u`, `--api-url ` | The URL to the Tugboat API. Default: `https://api.tugboatqa.com` | | `-p`, `--proxy ` | HTTP/HTTPS proxy URL for API connections | | `-t`, `--api-token ` | Access token for the Tugboat API | | `-k`, `--no-check-certificate` | Skip API certificate verification | | `-q`, `--quiet` | No output, just return object ID or status code | | `-v`, `--verbose` | Verbose output (ignored if `--quiet`) | | `-j`, `--json` | Raw JSON output (ignored if `--quiet` or `--verbose`) | | `-w`, `--write [path]` | Write output to file (overrides `--quiet`, `--verbose`, `--json`) | | `--debug` | Debug output (not applied if `--quiet`) | | `-f`, `--force` | Force an operation to execute | | `--no-color` | Disable color output | | `-b`, `--browser [browser]` | Open preview URL in default browser | | `--tree` | Show output in a tree | ## Commands ### list|ls List or show details of Tugboat resources. ```bash tugboat ls # List all of a resource type tugboat ls # Show details of a specific resource tugboat ls previews repo= # Filter previews by repo tugboat ls services preview= # List services in a preview tugboat ls pulls # List pull requests for a repo tugboat ls jobs # List jobs for a resource tugboat ls branches # List branches for a repo tugboat ls keys # List API keys tugboat ls mail # List captured mail tugboat ls projects # List all projects tugboat ls repos # List all repositories ``` Listable resource types: `agents`, `keys`, `lighthouse`, `mail`, `previews`, `projects`, `repos`, `screenshots`, `services`, `visualdiffs` Filter arguments per resource type: - **previews**: `preview`, `repo`, `project`, `anchor` - **services**: `service`, `preview`, `repo`, `project` - **repos**: `repo`, `project` - **screenshots**: `screenshot`, `service`, `preview`, `repo`, `project`, `data`, `crop`, `scale` - **visualdiffs**: `visualdiff`, `screenshot`, `service`, `preview`, `repo`, `project`, `data`, `crop`, `scale` - **pulls**: `state` (GitHub: open/closed/all; GitLab: opened/closed/merged; Bitbucket: OPEN/DECLINED/MERGED/ALL) ### create Create Tugboat resources. ```bash # Create a preview tugboat create preview repo= tugboat create preview main repo= anchor=true tugboat create preview feature-branch repo= base=false tugboat create preview pr-123 repo= type=pullrequest tugboat create preview main repo= expires=2024-12-31 name="My Preview" # Create other resources tugboat create key tugboat create lighthouse [url=/path] [screen=desktop|mobile] tugboat create screenshot [url=/path] [screen=desktop|tablet|mobile] tugboat create visualdiff base= tugboat create repo project= tugboat create registry username= password= ``` Preview create arguments: - `repo=` (required) - Repository to build from - `type=branch|tag|commit|pullrequest|mergerequest` - Ref type disambiguation - `base=|false` - Base preview to clone from, or `false` to skip - `name=` - Friendly name - `config=` - Local YAML config file override - `expires=` - Auto-delete date (ISO 8601) - `anchor=true` - Anchor as default base preview - `anchor_type=repo|preview` - Anchor scope ### update Update Tugboat resource properties. ```bash tugboat update anchor=true # Set as base preview tugboat update anchor=false # Remove base preview status ``` ### delete|rm Delete a Tugboat resource. ```bash tugboat delete tugboat delete -f # Force delete without confirmation ``` ### Preview Lifecycle Commands ```bash tugboat rebuild # Full rebuild (pulls images, runs init+update+build) tugboat rebuild base= # Rebuild with different base tugboat refresh # Pull latest code, run update+build (skip init) tugboat redeploy # Redeploy code on a preview tugboat reset # Reset to post-build snapshot tugboat reset -f # Force reset a stuck preview tugboat start # Start a stopped/suspended preview tugboat stop # Stop a running preview tugboat suspend # Suspend a preview (save resources) tugboat cancel # Cancel a currently building preview tugboat clone # Clone a preview ``` ### log View logs for a preview or service. ```bash tugboat log # View build logs tugboat log -a # Attach and watch for new entries tugboat log --attach # Same as -a ``` ### shell Open a shell session in a preview or service. ```bash tugboat shell # Interactive shell on default service tugboat shell # Shell into specific service tugboat shell command="cmd" # Execute a command tugboat shell command='["script.sh", "--opt", "arg"]' # Array form ``` ### Other Commands ```bash tugboat find # Find a resource by ID tugboat grant # Grant access to a resource tugboat revoke # Revoke access from a resource tugboat rekey # Rekey a preview tugboat validate [ref] # Validate a config.yml tugboat version # Show client/server versions tugboat output # View output of a service tugboat statistics # Get historical statistics ``` ## Configuration File (.tugboat/config.yml) The repository config file defines preview infrastructure. ### Service Properties ```yaml services: service-name: image: tugboatqa/httpd:2.4 # Docker image default: true # Default service (gets preview URL) checkout: true # Clone git repo into this service checkout_path: /var/lib/tugboat # Where to clone expose: 80 # Port exposed to Tugboat proxy http: false # Allow HTTP https: true # Allow HTTPS depends: - mysql # Service dependencies aliases: - foo - bar.example.com alias_type: default|domain subpath: false domain: tugboatqa.com urls: - / - /about screenshot: enabled: true fullPage: true timeout: 30 visualdiff: enabled: true threshold: 0 lighthouse: enabled: true screen: - desktop - mobile environment: VAR_NAME: value commands: init: [] # Fresh builds only - install packages update: [] # Fresh builds + refreshes - import data build: [] # Every build/refresh/rebuild - compile, clear caches ready: [] # After build - health checks online: [] # After preview is live - one-time tasks start: [] # Every time preview starts - start daemons clone: [] # When cloning from base - adjust settings ``` ### Lifecycle Phases | Phase | Runs when | Purpose | |-------|-----------|---------| | `init` | Fresh builds only | Install packages, configure infrastructure | | `update` | Fresh builds + refreshes | Import databases, assets | | `build` | Every build/refresh/rebuild | Compile code, run DB updates, clear caches | | `ready` | After build completes | Health checks (e.g., wait for TCP port) | | `online` | After preview is live | One-time post-launch tasks | | `start` | Every time preview starts | Start daemons, background processes | | `clone` | Cloning from base preview | Adjust cloned preview settings | ## Environment Variables (Inside Preview Containers) | Variable | Description | |----------|-------------| | `$TUGBOAT_PREVIEW_ID` | Current preview ID | | `$TUGBOAT_PREVIEW` | Preview ref name (e.g., `pr381`) | | `$TUGBOAT_PREVIEW_SHA` | Git SHA used for the build | | `$TUGBOAT_REPO` | Repository name | | `$TUGBOAT_REPO_ID` | Repository ID | | `$TUGBOAT_SERVICE` | Current service name | | `$TUGBOAT_SERVICE_ID` | Current service ID | | `$TUGBOAT_ROOT` | Git clone location (`/var/lib/tugboat`) | | `$TUGBOAT_DEFAULT_SERVICE_URL` | Full URL of default service | | `$TUGBOAT_DEFAULT_SERVICE_URL_HOST` | Hostname of default service | | `$TUGBOAT_DEFAULT_SERVICE_URL_PROTOCOL` | Protocol (http/https) | | `$TUGBOAT_DEFAULT_SERVICE_TOKEN` | Auth token for service | | `$TUGBOAT_SMTP` | SMTP server for email capture | | `$TUGBOAT_PROJECT_ID` | Project ID | | `$TUGBOAT_GITHUB_OWNER` | GitHub repo owner | | `$TUGBOAT_GITHUB_REPO` | GitHub repo name | | `$TUGBOAT_GITHUB_PR` | GitHub PR number | | `$DOCROOT` | Web document root path | ## Authentication ### Access Token Setup 1. Generate at https://dashboard.tugboatqa.com/access-tokens 2. Configure via: first run prompt, `~/.tugboat.yml`, `-t` flag, or `TUGBOAT_API_TOKEN` env var ### Config File (~/.tugboat.yml) Stores the API token after first configuration. ## API Reference Full API docs: https://api.tugboatqa.com/v3