Overcast is a CLI for managing and provisioning servers on DigitalOcean. It's a thin SSH-based layer that lets you spin up instances, organize them into clusters, and run commands or scripts across them, without installing agents or daemons on your servers.

What it's for

• Spinning up and managing DigitalOcean droplets from the command line
• Running shell commands and scripts across multiple servers (sequentially or in parallel)
• Organizing servers into named clusters for easy targeting
• Pushing and pulling files between your local machine and remote servers
• Quick SSH access to any server by name

What it's not

• A full configuration management system (no state tracking, no declarative configs)
• A replacement for Ansible, Terraform, or Kubernetes
• A process manager or monitoring solution

# Spin up a new Ubuntu 20.04 instance on DigitalOcean:
$ overcast digitalocean create db-01

# Perform a full system upgrade and then install Redis:
$ overcast run db-01 install/core install/redis

Run multiple commands or scripts on any instance over SSH, sequentially or in parallel.

# Create a LAMP stack using bundled install scripts:
$ overcast run lamp-01 install/core install/apache install/mysql install/php

# Run your own scripts using relative or absolute paths:
$ overcast run app-cluster ./my-app/my-install-script /path/to/another-script

# Run sequences of commands and scripts across multiple machines in parallel:
$ overcast run app-* ./script.sh uptime "free -m" "df -h" --parallel

Quickly SSH in to any instance by name.

$ overcast ssh app-01

Push and pull files between your local machine and any of your instances.

$ overcast push app-01 nginx/myapp.conf /etc/nginx/sites-enabled/myapp.conf
$ overcast pull app-01 /var/log/syslog ./my-local-syslog-copy

Overcast is a thin layer on top of your SSH client. It doesn't install or leave anything on the servers you communicate with, so Overcast itself has no real attack surface.

A library of scripts and recipes are bundled to make it easy to deploy a number of common software stacks and applications.

Installation (OS X/Linux)

1. Install Node.js if not already installed.

2. Install Overcast using npm.

sh $ npm -g install overcast

1. You can now use Overcast from any directory. Running any overcast command from anywhere will create the ~/.overcast config directory if it doesn't already exist. Add your API keys to ~/.overcast/variables.json to use their respective commands, either manually or using the var command:

sh $ overcast var set DIGITALOCEAN_API_TOKEN abc123

1. To make working with Overcast easier, you can add bash tab completion by adding the following to your .bash_profile:

sh # Overcast Tab completion _overcast_completions() { local cur=${COMP_WORDS[COMP_CWORD]} COMPREPLY=($(compgen -W "`overcast completions`" -- "$cur")) return 0 } complete -F _overcast_completions overcast

Installation (Windows)

Using Overcast on Windows is possible, but unsupported.

Uninstallation

Since Overcast is just a wrapper around SSH, there is nothing on your remote machines to uninstall. To uninstall Overcast from your local machine:

# To remove the Overcast package:
$ npm -g remove overcast
# Optionally delete your Overcast SSH keys and configuration files:
$ rm -rf ~/.overcast

Configuration

Overcast looks for an .overcast directory in the current directory, a parent directory, or ~/.overcast, in that order. This means you can have multiple configurations and treat your server infrastructure like source code.

The command overcast init will create a new configuration in the current directory. The config directory looks like this:

/.overcast
  /keys             # SSH keys, can be your own or auto-generated by overcast
    overcast.key
    overcast.key.pub
  clusters.json     # Cluster/instance definitions (see example.clusters.json)
  variables.json    # API keys, etc (see example.variables.json)

Secrets and Environment Variables

Overcast resolves variables (like API tokens) with this precedence:

1. Command-line arguments (e.g., --ssh-key /path/to/key)
2. Environment variables (e.g., DIGITALOCEAN_API_TOKEN)
3. Secret references in variables.json (see below)
4. Raw values in variables.json

Using Environment Variables (Recommended for CI/Production)

Environment variables are the simplest and most portable way to configure secrets:

# Set directly
export DIGITALOCEAN_API_TOKEN=your_token_here
overcast digitalocean create vm-01

# Or use with secret managers that inject env vars
doppler run -- overcast digitalocean create vm-01
vault exec -- overcast run app ./deploy.sh

The following environment variables are recognized:

Variable	Description
DIGITALOCEAN_API_TOKEN	DigitalOcean API token
SLACK_WEBHOOK_URL	Slack incoming webhook URL
OVERCAST_SSH_KEY	Default SSH private key path
OVERCAST_SSH_USER	Default SSH username

Secret References in variables.json

For local development, you can store values directly in variables.json, or use references that resolve at runtime:

{
  "DIGITALOCEAN_API_TOKEN": "env:DO_API_TOKEN",
  "SLACK_WEBHOOK_URL": "doppler:SLACK_WEBHOOK_URL",
  "DEPLOY_KEY": "cmd:cat ~/.secrets/deploy-key"
}

Supported reference prefixes:

Prefix	Description	Example
env:	Read from environment variable	env:MY_VAR
cmd:	Execute command, use stdout	cmd:cat /path/to/secret
doppler:	Fetch from Doppler CLI	doppler:SECRET_NAME
doppler:	Fetch with explicit config	doppler:project/config/SECRET_NAME

SSH Key Handling

If no SSH key is configured for an instance (via --ssh-key or instance.ssh_key), Overcast will not pass the -i flag to SSH. This allows OpenSSH to use its default key selection:

• Keys loaded in ssh-agent (including 1Password SSH Agent, Secretive, etc.)
• Keys configured in ~/.ssh/config
• Default keys like ~/.ssh/id_ed25519 or ~/.ssh/id_rsa

This makes Overcast work seamlessly with hardware security keys and SSH agent forwarding.

Design Goals

Overcast is intentionally minimal and boring. It wraps SSH and the DigitalOcean API without adding layers of abstraction. There's no agent to install, no state to manage, and no DSL to learn, just boring old shell commands and scripts.

Command Reference

overcast aliases

Usage:
  overcast aliases

Description:
  Return a list of bash aliases for SSHing to your instances.

  To use, add this to your .bash_profile:
    test -f $HOME/.overcast_aliases && source $HOME/.overcast_aliases

  And then create the .overcast_aliases file:
    overcast aliases > $HOME/.overcast_aliases

  Or to automatically refresh aliases in every new terminal window
  (which will add a couple hundred milliseconds to your startup time),
  add this to your .bash_profile:
    overcast aliases > $HOME/.overcast_aliases
    source $HOME/.overcast_aliases

overcast cluster count

Usage:
  overcast cluster count [name]

Description:
  Return the number of instances in a cluster.

Examples:
  $ overcast cluster count db
  > 0
  $ overcast instance create db.01 --cluster db
  > ...
  $ overcast cluster count db
  > 1

overcast cluster add

Usage:
  overcast cluster add [name]

Description:
  Adds a new cluster.

Examples:
  $ overcast cluster add db

overcast cluster rename

Usage:
  overcast cluster rename [name] [new-name]

Description:
  Renames a cluster.

Examples:
  $ overcast cluster rename app-cluster app-cluster-renamed

overcast cluster remove

Usage:
  overcast cluster remove [name]

Description:
  Removes a cluster from the index. If the cluster has any instances
  attached to it, they will be moved to an "orphaned" cluster.

Examples:
  $ overcast cluster remove db

overcast completions

Usage:
  overcast completions

Description:
  Return an array of commands, cluster names, and instance names for use
  in bash tab completion.

  To enable tab completion in bash, add this to your .bash_profile:

  _overcast_completions() {
    local cur=${COMP_WORDS[COMP_CWORD]}
    COMPREPLY=($(compgen -W "`overcast completions`" -- "$cur"))
    return 0
  }
  complete -F _overcast_completions overcast

overcast digitalocean boot

Usage:
  overcast digitalocean boot [name]

Description:
  Boot up an instance if powered off, otherwise do nothing.

overcast digitalocean create

Usage:
  overcast digitalocean create [name] [options...]

Description:
  Creates a new instance on DigitalOcean.

Options:                  Defaults:
  --cluster CLUSTER       default
  --ssh-port PORT         22
  --ssh-key PATH          overcast.key
  --ssh-pub-key PATH      overcast.key.pub
  --region REGION
  --image IMAGE
  --size SIZE
  --backups               false
  --monitoring            false
  --private-networking    false
  --vpc-uuid
  --with-droplet-agent    false

Examples:
  # Match using slugs:
  $ overcast digitalocean create vm-01 --size 2gb --region sfo1

  # Match using IDs or names:
  $ overcast digitalocean create vm-02 --region "London 1" --image 6374128

overcast digitalocean destroy

Usage:
  overcast digitalocean destroy [name] [options...]

Description:
  Destroys a DigitalOcean droplet and removes it from your account.
  Using --force overrides the confirm dialog.

Options:     Defaults:
  --force    false

Examples:
  $ overcast digitalocean destroy vm-01

overcast digitalocean images

Usage:
  overcast digitalocean images

Description:
  List all images, including snapshots.

overcast digitalocean instances

Usage:
  overcast digitalocean instances

Description:
  List all instances in your account.

overcast digitalocean reboot

Usage:
  overcast digitalocean reboot [name]

Description:
  Reboot an instance using the provider API.

overcast digitalocean regions

Usage:
  overcast digitalocean regions

Description:
  List all available regions.

overcast digitalocean rebuild

Usage:
  overcast digitalocean rebuild [name] [image]

Description:
  Rebuilds an existing instance on DigitalOcean, preserving the IP address.
  [image] can be image ID, name or slug.

Examples:
  # Rebuild an instance using a readymade image:
  $ overcast digitalocean rebuild vm-01 ubuntu-14-04-x64

  # Rebuild an instance using a snapshot:
  $ overcast digitalocean rebuild vm-01 "vm-01 backup"

overcast digitalocean resize

Usage:
  overcast digitalocean resize [name] [size] [options...]

Description:
  Shutdown, resize, and reboot a DigitalOcean instance.
  [size] must be a valid size slug.
  If the --skip-boot flag is used, the instance will stay powered off.

Options:         Defaults:
  --skip-boot    false

Examples:
  # Resize an instance to 2gb:
  $ overcast digitalocean resize vm-01 2gb

overcast digitalocean snapshot

Usage:
  overcast digitalocean snapshot [name] [snapshot-name]

Description:
  Creates a named snapshot of a droplet. This will reboot the instance.

Examples:
  $ overcast digitalocean snapshot vm-01 vm-01-snapshot

overcast digitalocean snapshots

Usage:
  overcast digitalocean snapshots

Description:
  List all available snapshots in your account.

overcast digitalocean destroy-snapshot

Usage:
  overcast digitalocean destroy-snapshot [snapshot-id] [options...]

Description:
  Destroys a DigitalOcean snapshot.
  Use "overcast digitalocean snapshots" to list available snapshots.
  Using --force overrides the confirm dialog.

Options:     Defaults:
  --force    false

Examples:
  $ overcast digitalocean destroy-snapshot 12345678

overcast digitalocean shutdown

Usage:
  overcast digitalocean shutdown [name]

Description:
  Shut down an instance using the provider API.

overcast digitalocean sizes

Usage:
  overcast digitalocean sizes

Description:
  List all available instance sizes.

overcast digitalocean sync

Usage:
  overcast digitalocean sync [name]

Description:
  Fetch and update instance metadata.

overcast expose

Usage:
  overcast expose [instance|cluster|all] [port...] [options]

Description:
  Reset the exposed ports on the instance or cluster using iptables.
  This will fail if you don't include the current SSH port.
  Specifying --allowlist will restrict all ports to the specified address(es).
  These can be individual IPs or CIDR ranges, such as "192.168.0.0/24".

  Expects an Ubuntu server, untested on other distributions.

Options:
  --user USERNAME
  --password PASSWORD
  --allowlist "IP|RANGE"
  --allowlist-PORT "IP|RANGE"

Examples:
  Allow SSH, HTTP and HTTPS connections from anywhere:
  $ overcast expose app 22 80 443

  Allow SSH from anywhere, only allow Redis connections from 1.2.3.4:
  $ overcast expose redis 22 6379 --allowlist-6379 "1.2.3.4"

  Only allow SSH and MySQL connections from 1.2.3.4 or from 5.6.7.xxx:
  $ overcast expose mysql 22 3306 --allowlist "1.2.3.4 5.6.7.0/24"

overcast exposed

Usage:
  overcast exposed [instance|cluster|all]

Description:
  List the exposed ports on the instance or cluster.
  Expects an Ubuntu server, untested on other distributions.

Options:
  --user USERNAME
  --password PASSWORD
  --machine-readable, --mr

overcast help

Usage:
  overcast help

Description:
  Provides help about Overcast and specific commands.

overcast info

``` Usage: overcast