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.

If a running instance's shutdown behavior is terminate, down terminates (deletes) it instead of stopping it. EC2 applies that behavior only when the OS shuts down, not on an API stop, so down does this explicitly. An instance that is already stopped is left alone. If termination protection refuses the terminate, down stops the instance instead. When down --update-ssh terminates an instance, it removes the alias from ~/.ssh/config rather than commenting out its Hostname. delete --update-ssh likewise removes the alias of each deleted instance.

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