djbingham/doctl repository overview

⁠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

⁠Linux

You can use snap⁠ to install doctl on Ubuntu and snap supported⁠ systems by using the command below:

snap install doctl

⁠Windows

Integrations with package managers for Windows are to come.

⁠Option 2 – Download a Release from GitHub

Visit the [Releases page][doctl-releases] 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.7.0/doctl-1.7.0-darwin-10.6-amd64.tar.gz | tar xz

# linux (with wget)
wget -qO- https://github.com/digitalocean/doctl/releases/download/v1.7.0/doctl-1.7.0-linux-amd64.tar.gz  | tar xz
# linux (with curl)
curl -L https://github.com/digitalocean/doctl/releases/download/v1.7.0/doctl-1.7.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][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][tutorial].

• 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

First, make sure the CHANGELOG⁠ contains all changes for the version you're going to release.

⁠Setup

To release doctl you need to install:

• xgo⁠
• github-release⁠

And make them available at your PATH. You can use go get -u for both of them and add your $GOPATH/bin to your PATH so your scripts will find them.

You will also need valid GITHUB_TOKEN environment variable with access to the digitalocean/doctl repo.

⁠Scripts

To build doctl for all it's platforms run script/stage.sh major minor patch (ie. script/stage.sh 1 5 0). This will place all files and it's checksums at builds/major.minor.patch/release.

Then mark the release on github with script/release.sh <version> (ie. script/release.sh 1.5.0).

Then upload using script/upload.sh <version> to mark it on github.

Now go to releases⁠ and update the release description to contain all changelog entries for this specific release.

⁠More info

• Tutorial⁠
• doctl Releases⁠
• windows Release⁠