alexxnica / doctl

A command line tool for DigitalOcean services

doctl

doctl is a command line interface for the DigitalOcean API.

Usage:
  doctl [command]

Available Commands:
  account     account commands
  auth        auth commands
  compute     compute commands
  version     show the current version

Flags:
  -t, --access-token string   DigitalOcean API V2 Access Token
  -h, --help                  help for doctl
  -o, --output string         output format [text|json] (default "text")
  -v, --verbose               verbose output

Use "doctl [command] --help" for more information about a command.

Installation

Option 1 - Use a Package Manager (preferred method)

OS X

You can use Homebrew to install doctl on Mac OS X by using the command below:

brew install doctl

Windows and GNU/Linux

Integrations with package managers for GNU/Linux and Windows are to come.

Option 2 – Download a Release from GitHub

Visit the Releases page for the doctl GitHub project, and find the appropriate archive for your operating system and architecture. (For OS X systems, remember to use the darwin archive.)

OS X and GNU/Linux

You can download the archive from your browser, or copy its URL and retrieve it to your home directory with wget or curl:

cd ~

# OS X
curl -L https://github.com/digitalocean/doctl/releases/download/v1.6.0/doctl-1.6.0-darwin-10.6-amd64.tar.gz | tar xz

# linux (with wget)
wget -qO- https://github.com/digitalocean/doctl/releases/download/v1.6.0/doctl-1.6.0-linux-amd64.tar.gz  | tar xz
# linux (with curl)
curl -L https://github.com/digitalocean/doctl/releases/download/v1.6.0/doctl-1.6.0-linux-amd64.tar.gz  | tar xz

Move the doctl binary to somewhere in your path. For example:

sudo mv ./doctl /usr/local/bin

Windows

On Windows systems, you should be able to download the Windows release, and then double-click the zip archive to extract the doctl.exe executable.

Option 3 – Build From Source

Alternatively, if you have a Go environment configured, you can install the development version of doctl from the command line like so:

go get github.com/digitalocean/doctl/cmd/doctl

Option 4 – Build with Docker

If you have Docker installed, you can build with the Dockerfile a Docker image and run doctl within a Docker container.

# build Docker image
docker build -t doctl .

# usage
docker run -e DIGITALOCEAN_ACCESS_TOKEN doctl <followed by doctl commands>

Initialization

To use doctl, a DigitalOcean access token is required. Generate a new token and run doctl auth init, or set the environment variable, DIGITALOCEAN_ACCESS_TOKEN, with your new token.

Configuration

By default, doctl will load a configuration file from $XDG_CONFIG_HOME/doctl/config.yaml if found. If the XDG_CONFIG_HOME environment variable is not, the path will default to $HOME/.config/doctl/config.yaml on Unix like systems, and %APPDATA%/doctl/config/config.yaml on Windows.

The configuration file has changed locations in recent versions, and a warning will be displayed if your configuration exists at the legacy location.

Configuration OPTIONS

• access-token - The DigitalOcean access token. You can generate a token in the Apps & API section of the DigitalOcean control panel and then use it with doctl auth init.
• output - Type of output to display results in. Choices are json or text. If not supplied, doctl will default to text.

Example:

access-token: MY_TOKEN
output: text

Examples

doctl is able to interact with all of your DigitalOcean resources. Below are a few common usage examples. To learn more about the features available, see the full tutorial on the DigitalOcean community site.

• List all Droplets on your account:

  doctl compute droplet list

• Create a Droplet:

  doctl compute droplet create <name> --region <region-slug> --image <image-slug> --size <size-slug>

• Assign a Floating IP to a Droplet:

  doctl compute floating-ip-action assign <ip-addr> <droplet-id>

• Create a new A record for an existing domain:

  doctl compute domain records create --record-type A --record-name www --record-data <ip-addr> <domain-name>

doctl also simplifies actions without an API endpoint. For instance, it allows you to SSH to your Droplet by name:

doctl compute ssh <droplet-name>

By default, it assumes you are using the root user. If you want to SSH as a specific user, you can do that as well:

doctl compute ssh <user>@<droplet-name>

Building and dependencies

doctl's dependencies are managed by gvt. To add dependencies, use gvt fetch.

Releasing

To build doctl for all its platforms, run script/build.sh <version>. To upload doctl to Github, run script/release.sh <version>. A valid GITHUB_TOKEN environment variable with access to the digitalocean/doctl repository is required.