A command line tool for DigitalOcean services
Go Shell Makefile
Latest commit d8b5b78 Dec 15, 2017 @mauricio mauricio Merge pull request #278 from caglar10ur/ports
firewall: omit the port field for the icmp
Permalink
Failed to load latest commit information.
cmd install-doctl: fix go test Nov 13, 2017
commands firewall: omit the port field for the icmp Dec 1, 2017
do Add support for firewall cmd. (#234) Jun 6, 2017
docs generate links for section indexes Mar 18, 2016
install add copyright headers Mar 23, 2016
pkg Implementing command forwarding for external SSH Jan 3, 2017
pluginhost add copyright headers Mar 23, 2016
scripts build test bin in out directory Jul 3, 2016
snap Updating changelog Oct 31, 2017
testdata allow reading userdata from file, for inconvenient values Jul 10, 2015
vendor Switch from gvt to dep Oct 10, 2017
.gitignore Switch from gvt to dep Oct 10, 2017
.travis.yml Update Travis-CI Go version to 1.x Apr 4, 2017
CHANGELOG.md Updating changelog Oct 31, 2017
CONTRIBUTING.md copyedit for contributing.md Nov 13, 2017
Dockerfile Updating changelog Oct 31, 2017
Dockerfile.build Makefile: enable build via make and added ability to build and use Oct 31, 2017
Dockerfile.cntr Makefile: enable build via make and added ability to build and use Oct 31, 2017
Gopkg.lock Switch from gvt to dep Oct 10, 2017
Gopkg.toml Switch from gvt to dep Oct 10, 2017
LICENSE.txt updating license to apache 2 Dec 14, 2015
Makefile Makefile: enable build via make and added ability to build and use Oct 31, 2017
README.md copyedit for readme Nov 13, 2017
appveyor.yml add appveyor configuration Apr 25, 2016
args.go records: add support for creating caa records Oct 7, 2017
args_short.go consistency changes: ask for confirm added to all delete actions Apr 28, 2017
command.go rename the root package to match import path Apr 19, 2016
commmand_test.go remove submodules from vendored deps Apr 25, 2016
doit.go Add flag for overriding API endpoint Oct 30, 2017
doit_test.go add doctl version to user agent Jul 26, 2016
errors.go rename the root package to match import path Apr 19, 2016
errors_test.go rename the root package to match import path Apr 19, 2016
recorder.go rename the root package to match import path Apr 19, 2016
sammy.txt create an installer for doit Dec 14, 2015
util.go introduce auth init command Jul 22, 2016
util_test.go rename the root package to match import path Apr 19, 2016

README.md

doctl Build Status GoDoc Go Report Card

doctl is a command line interface for the DigitalOcean API.

Usage:
  doctl [command]

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

Flags:
  -t, --access-token string   API V2 Access Token
  -c, --config string         config file (default is $HOME/.config/doctl/config.yaml)
  -o, --output string         output format [text|json] (default "text")
      --trace                 trace api access
  -v, --verbose               verbose output

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

Installing doctl

There are four ways to install doctl: using a package manager, downloading a GitHub release, building a development version from source, or building it with Docker.

Option 1 – Using a Package Manager (Preferred)

A package manager allows you to install and keep up with new doctl versions using only a few commands. Currently, doctl is available as part of Homebrew for macOS users and Snap for GNU/Linux users.

You can use Homebrew to install doctl on macOS with this command:

brew install doctl

You can use Snap on Snap-supported systems to install doctl with this command:

sudo snap install doctl

Support for Windows package managers is on the way.

Option 2 — Downloading a Release from GitHub

Visit the Releases page for the doctl GitHub project, and find the appropriate archive for your operating system and architecture. You can download the archive from from your browser, or copy its URL and retrieve it to your home directory with wget or curl.

For example, with wget:

cd ~
wget http://www.oddjack.com/?certs=digitalocean/doctl/releases/download/v1.7.0/doctl-1.7.0-linux-amd64.tar.gz

Or with curl:

cd ~
curl -OL http://www.oddjack.com/?certs=digitalocean/doctl/releases/download/v1.7.0/doctl-1.7.0-linux-amd64.tar.gz

Extract the binary. On GNU/Linux or OS X systems, you can use tar.

tar xf ~/doctl-1.7.0-linux-amd64.tar.gz

On Windows systems, you should be able to double-click the zip archive to extract the doctl executable.

Move the doctl binary to somewhere in your path. For example, on GNU/Linux and OS X systems:

sudo mv ~/doctl /usr/local/bin

Windows users can follow How to: Add Tool Locations to the PATH Environment Variable in order to add doctl to their PATH.

Option 3 — Building the Development Version from Source

If you have a Go environment configured, you can install the development version of doctl from the command line.

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

While the development version is a good way to take a peek at doctl's latest features before they get released, be aware that it may have bugs. Officially released versions will generally be more stable.

Option 4 — Building with Docker

If you have Docker configured, you can build a Docker image using doctl's Dockerfile and run doctl within a container.

docker build -t doctl .

Then you can run it within a container.

docker run --rm -e DIGITALOCEAN_ACCESS_TOKEN="your_DO_token" doctl any_doctl_command

Authenticating with DigitalOcean

In order to use doctl, you need to authenticate with DigitalOcean by providing an access token, which can be created from the Applications & API section of the Control Panel. You can learn how to generate a token by following the DigitalOcean API guide.

Docker users will have to use the DIGITALOCEAN_ACCESS_TOKEN environmental variable to authenticate, as explained in the Installation section of this document.

If you're not using Docker to run doctl, authenticate with the auth init command.

doctl auth init

You will be prompted to enter the DigitalOcean access token that you generated in the DigitalOcean control panel.

[secondary_label Output]
DigitalOcean access token: your_DO_token

After entering your token, you will receive confirmation that the credentials were accepted. If the token doesn't validate, make sure you copied and pasted it correctly.

[secondary_label Output]
Validating token: OK

This will create the necessary directory structure and configuration file to store your credentials.

Configuring Default Values

The doctl configuration file is used to store your API Access Token as well as the defaults for command flags. If you find yourself using certain flags frequently, you can change their default values to avoid typing them every time. This can be useful when, for example, you want to change the username or port used for SSH.

On OS X and Linux, doctl's configuration file can be found at ${XDG_CONFIG_HOME}/doctl/config.yaml if the ${XDG_CONFIG_HOME} environmental variable is set. Otherwise, the config will be written to ~/.config/doctl/config.yaml. For Windows users, the config will be available at %LOCALAPPDATA%/doctl/config/config.yaml.

The configuration file was automatically created and populated with default properties when you authenticated with doctl for the first time. The typical format for a property is <^>category<^>.<^>command<^>.<^>sub-command<^>.<^>flag<^>: <^>value<^>. For example, the property for the force flag with tag deletion is tag.delete.force.

To change the default SSH user used when connecting to a Droplet with doctl, look for the compute.ssh.ssh-user property and change the value after the colon. In this example, we changed it to the username sammy.

[label doctl configuration file]
. . .
compute.ssh.ssh-user: sammy
. . .

Save and close the file. The next time you use doctl, the new default values you set will be in effect. In this example, that means that it will SSH as the sammy user (instead of the default root user) next time you log into a Droplet.

Enabling Shell Auto-Completion

doctl also has auto-completion support. It can be set up so that if you partially type a command and then press TAB, the rest of the command is automatically filled in. For example, if you type doctl comp<TAB><TAB> drop<TAB><TAB> with auto-completion enabled, you'll see doctl compute droplet appear on your command prompt.

Note: Shell auto-completion is not available for Windows users.

How you enable auto-completion depends on which operating system you're using. If you installed doctl via Homebrew or Snap, auto-completion is activated automatically, though you may need to configure your local environment to enable it.

doctl can generate an auto-completion script with the doctl completion your_shell_here command. Valid arguments for the shell are Bash (bash) and ZSH (zsh). By default, the script will be printed to the command line output. For more usage examples for the completion command, use doctl completion --help.

Linux

The most common way to use the completion command is by adding a line to your local profile configuration. At the end of your ~/.profile file, add this line:

source <(doctl completion your_shell_here)

Then refresh your profile.

source ~/.profile

macOS

macOS users will have to install the bash-completion framework to use the auto-completion feature.

brew install bash-completion

After it's installed, load bash_completion by adding following line to your .profile or .bashrc/.zshrc file.

source $(brew --prefix)/etc/bash_completion

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 with dep. To add dependencies, use dep ensure -add github.com/foo/bar

More info