cloudvm

A command-line tool for managing cloud development instances. AWS EC2 is currently supported.

cloudvm streamlines the daily routine of working with a development EC2 instance: it refreshes the AWS SSO token only when expired, starts the instance, waits for its public IP to be assigned, and reports it. A list subcommand surveys instances across regions to see what is still running.

Install

pipx install cloudvm

Or, if pipx is not available:

pip install cloudvm

Requires Python 3.9 or newer and a configured aws CLI (SSO or static credentials).

Usage

# Start an instance by its Name tag
cloudvm up --name my-dev-box

# Stop an instance — returns once the stop has been triggered
cloudvm down --name my-dev-box

# List instances across regions
cloudvm list --region 'eu-central-*,us-*' --name 'my-*'

All subcommands accept --region / -r and --name / -n, and honor the usual AWS environment variables (AWS_REGION, AWS_PROFILE, ...).

Pass --update-ssh to up to point the matching ~/.ssh/config host alias at the new IP.

When EC2 has no capacity for the instance type (InsufficientInstanceCapacity), pass --retry DURATION (e.g. 30m, 2h, 1h30m) or --retry forever to up to keep trying with backoff. If the start succeeds only after retrying, up rings the terminal bell and asks the terminal to post a desktop notification (OSC 9; supported by e.g. Ghostty, iTerm2 and WezTerm). It does the same when it gives up.

Shell completion

To enable tab-completion, add this to your ~/.bashrc (or ~/.zshrc, after compinit):

# This spawns cloudvm once for every new shell. See below for optimized
# alternative.
eval "$(cloudvm --print-completion bash)"   # or: zsh / tcsh / fish

Then open a new shell, or source the rc file. cloudvm <TAB> will now complete subcommands and flags.

To skip the per-shell cloudvm spawn, use a lazy stub instead — it loads the real completion on first use.

bash (~/.bashrc):

_cloudvm_lazy_complete() {
    eval "$(cloudvm --print-completion bash)"
    return 124
}
complete -F _cloudvm_lazy_complete cloudvm

zsh (~/.zshrc, after compinit):

_cloudvm_lazy_complete() {
    unfunction _cloudvm_lazy_complete
    eval "$(cloudvm --print-completion zsh)"
    "${_comps[cloudvm]}" "$@"
}
compdef _cloudvm_lazy_complete cloudvm

License

Apache License 2.0