How To Use Doctl, the Official DigitalOcean Command-Line Client
How To Use Doctl, the Official DigitalOcean Command-Line Client
We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

How To Use Doctl, the Official DigitalOcean Command-Line Client

PostedMarch 25, 2016 53.6k views DigitalOcean API Configuration Management


DigitalOcean's web based control panel provides a convenient, point-and-click interface for managing Droplets. There are, however, times when a command-line tool may be a preferable alternative: If you have many Droplets to manage, need to administer Droplets from the terminal without a graphical desktop available, or have tasks which would benefit from a scriptable interface.

Enter doctl, the official DigitalOcean command-line client, which leverages the DigitalOcean API to provide access to most account and Droplet features.

This tutorial assumes that you have access to a local client machine with a command-line environment, and an active account. It is intended as a quick guide to getting started with the tool, as well as a reference for most of its operations. Since doctl commands closely parallel the API, you may also benefit from reading the API documentation and How To Use the DigitalOcean API v2.


Option 1 – 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. You can download the archive from from your browser, or copy its URL and retrieve it to your home directory with wget or curl:

  • cd ~
  • wget


  • cd ~
  • curl -OL

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

  • tar xf ~/doctl-1.6.1-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

Option 2 – 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

Note: As with the development versions of most software, be aware that this one may contain bugs. Released versions will generally be more stable.

Authenticating with DigitalOcean

Before proceeding, you'll need to retrieve a DigitalOcean access token to be stored in the doctl configuration file. This can be done by visiting the Applications & API section of the Control Panel. You can learn how to generate a token by following the DigitalOcean API guide.

Once you have generated a token, return to your terminal. To set up doctl and authorize it to use your account, type:

  • doctl auth init

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

DigitalOcean access token: your_DO_token

After entering your token, you should receive confirmation that the credentials were accepted:

Validating token: OK

This will create the necessary directory structure and configuration file to store your credentials. On OS X and Linux, the 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 %APPDATA%/doctl/config/config.yaml.

Invoking Commands

The doctl command follows a common pattern in modern command-line interfaces. Individual features are invoked by giving the utility a command, one or more sub-commands, and sometimes one or more options specifying particular values.

Commands are grouped under three main headings: account for account-related information, auth for authenticating with DigitalOcean, and compute for managing infrastructure. Of these, you'll use compute most often.

In order to see an overview of commands, you can invoke doctl by itself:

  • doctl

To see available commands under a particular grouping, enter it by itself:

  • doctl compute

And to see a usage guide for a specific command, enter just the command without any parameters or options:

  • doctl compute droplet

Commands which read data are usually fairly concise. For example, to get a list of your Droplets:

  • doctl compute droplet list

More complex operations, such as creating a droplet, require longer commands with detailed parameters. In order to create a new 1 gigabyte Droplet named test in the NYC1 region, running a 64 bit Debian 8, with an SSH key installed for root access, and backups enabled, you would issue the following:

  • doctl compute droplet create test --size 1gb --image debian-8-x64 --region nyc1 --ssh-keys 4d:23:e6:e4:8c:17:d2:cf:89:47:36:b5:c7:33:40:4e --enable-backups
Sample Output
ID Name Public IPv4 Memory VCPUs Disk Region Image Status 11450164 test 1024 1 30 nyc1 Debian 8.3 x64 new

Finding Unique Identifiers for Droplets, Images, SSH Keys, Regions, etc.

You may notice that building a Droplet creation command requires you to specify a series of identifiers, like nyc1 for the NYC1 region, debian-8-x64 for the Debian image, and an SSH key fingerprint like 4d:23:e6:e4:8c:17:d2:cf:89:47:36:b5:c7:33:40:4e. Some of these can be relatively easily guessed, like 1gb for a 1 gigabyte Droplet, but others aren't nearly as obvious. A number of resources, such as Droplets and images, are identified by a value (often numeric) unique within DigitalOcean's database.

Fortunately, the required unique identifiers for most commands can be retrieved from the API:

Command Notes
doctl compute droplet list Your Droplets. Some commands also take the name; most require the numeric value from the "ID" column.
doctl compute ssh-key list The SSH keys associated with your account. For Droplet creation, you can specify either the numeric ID or fingerprint.
doctl compute region list Available regions. Use the string in the "Slug" column.
doctl compute image list Available images, including snapshots, backups, and base distribution images. Use the string in the "Slug" column for creating new Droplets.
doctl compute size list Available Droplet sizes. Use the string in the "Slug" column.

Creating, Deleting, and Inspecting Droplets

The doctl compute droplet command lets you create, delete, and inspect Droplets. Again, most commands for working with individual Droplets require the Droplet's unique ID, and these can be found in the output from doctl droplet list.

doctl compute droplet subcommand Notes
actions droplet_id Display a history of actions taken for a Droplet.
backups droplet_id List backups for a Droplet.
create name --size 1gb --image image_slug --region nyc1 --ssh-keys ssh_key_fingerprint Create a Droplet. Size, image, region, and an SSH key are all mandatory.
delete droplet_id Delete a Droplet by id or name.
get droplet_id Get details for a particular Droplet.
kernels droplet_id List kernels for a Droplet.
list List your current Droplets.
neighbors droplet_id List your Droplets running on the same physical hardware as a specific Droplet.
snapshots droplet_id List snapshots for a Droplet.

Initiating Droplet Actions

The doctl compute droplet-action command lets you trigger various actions for a Droplet, including power management actions and toggling features like backups and private networking.

doctl compute droplet-action subcommand Notes
disable-backups droplet_id Disable backups for a Droplet.
reboot droplet_id Reboot a Droplet.
power-cycle droplet_id Turn a Droplet off and back on again.
shutdown droplet_id Shut down a Droplet.
power-off droplet_id Power off a Droplet. The Droplet must be powered on. It's usually best to do this from the command line of the Droplet itself.
power-on droplet_id Power on a Droplet. The Droplet must be powered off.
power-reset droplet_id Power reset Droplet.
enable-ipv6 droplet_id Enable ipv6 for a Droplet.
enable-private-networking droplet_id Enable private networking for a Droplet.
restore droplet_id --image-id image_id Restore a Droplet to a specific backup image. The image_id must be a backup of the Droplet.
resize droplet_id --size 2gb --resize-disk Resize a Droplet. The Droplet must be powered off.
rebuild droplet_id --image-id image_id Rebuild a Droplet from a specific image.
rename droplet_id --droplet-name new_name Rename a Droplet to new_name.
change-kernel droplet_id --kernel-id kernel_id Change a Droplet's kernel to kernel_id.
snapshot droplet_id --snapshot-name snapshot_name Take a snapshot of a Droplet, naming it snapshot_name. The Droplet must be powered off.

Making SSH Connections

In order to connect to an individual Droplet with SSH, it's usually necessary to know either its IP address or fully-qualified domain name. You can instead use doctl to connect to a Droplet by its name or numeric ID:

  • doctl compute ssh droplet_name
  • doctl compute ssh droplet_id

Working with SSH Keys

You can manage the SSH public keys associated with your account with the doctl compute ssh-key command. Most commands which reference SSH keys accept either the numeric ID for the key or its fingerprint.

doctl compute ssh-key subcommand Notes
list List SSH keys associated with your account.
get ssh_key_id Get info on a specific key, by numeric ID. Identical to list output.
get ssh_key_fingerprint Get info on a specific key, by fingerprint.
create new_key_name --public-key "public_key" Associate a public key with your account by specifying its contents.
import new_key_name --public-key-file ~/.ssh/ Associate a public key with your account by specifying a source file.
delete ssh_key_id Delete a key from your account by numeric ID.
delete ssh_key_fingerprint Delete a key from your account by fingerprint.
update ssh_key_id --key-name new_key_name Change a key's name by numeric id.
update ssh_key_fingerprint --key-name new_key_name Change a key's name by fingerprint.

Working with Floating IPs

A Floating IP is a publicly-accessible static IP address that can be assigned to one of your Droplets. For a detailed description of the feature, you can read How To Use Floating IPs on DigitalOcean. You can manipulate floating IPs with doctl compute floating-ip.

doctl compute floating-ip subcommand Notes
create --region nyc1 Create a Floating IP in nyc1.
get floating_ip_address Get the details for a Floating IP address.
delete floating_ip_address Delete a floating IP address.
list List all Floating IP addresses.

Working with Domains

The doctl compute domain command allows for managing DNS records. See the An Introduction to Managing DNS series for a broad overview of the subject.

doctl compute domain subcommand Notes
create domain_name --ip-address droplet_ip_address Create domain records for dropletipaddress.
list List domains.
get domain_name Get domain record.
delete domain_name Delete domain.
records list --domain-name domain_name List domain records.

Creating, Deleting, and Inspecting Block Storage Volumes

The doctl compute volume command can be used to create, delete, or get information about DigitalOcean's Block Storage volumes. For more information about this feature, read our guide on How To Use Block Storage on DigitalOcean.

doctl compute volume subcommand Notes
create volume_name --region volume_region --size volume_size --desc volume_description Create a volume. The name, region, and size are mandatory.
list List volumes.
get volume_ID Get volume.
delete volume_ID Delete volume.

Initiating Volume Actions

The doctl compute volume-action command lets you trigger actions for a volume, including attaching volumes to and detaching volumes from Droplets.

doctl compute volume-action subcommand Notes
attach volume_id droplet_id Attach a volume to a Droplet.
detach volume_id Detach a volume from a Droplet.

Working with Load Balancers

The doctl compute load-balancer command can be used to create, delete, or get information about DigitalOcean's Load Balancers. For more information about this feature, read our Introduction to DigitalOcean Load Balancers.

doctl compute load_balancer subcommand Notes
create --name lb_name --region lb_region --tag-name tag_name --forwarding-rules forwarding_rule Create a load_balancer. The name, region, a tag or list of Droplet IDs, and at least one forwarding rule are mandatory.
list List load balancers.
get lb_ID Get a load balancer.
delete lb_ID Delete a load balancer.
add-droplets lb_ID --droplet-ids droplet_ID Add Droplets to a load balancer.
remove-droplets lb_ID --droplet-ids droplet_ID Remove Droplets from a load balancer.
add-forwarding-rules lb_ID --forwarding-rules forwarding_rule Add forwarding rules to a load balancer.
remove-forwarding-rules lb_ID --forwarding-rules forwarding_rule Remove forwarding rules from a load balancer.

When used as an argument to doctl, forwarding rules should be expressed like: entry_protocol:protocol,entry_port:port,target_protocol:protocol,target_port:port

Working with Cloud Firewalls

The doctl compute firewall command lets you create, list update, and delete DigitalOcean Cloud Firewalls, their rules, and the Droplets and Tags to which they apply. For more information about Cloud Firewalls, see An Introduction to DigitalOcean Cloud Firewalls. See more examples of doctl firewall commands on GitHub.

doctl compute firewall subcommand Notes
create --droplet-ids droplet_id --inbound-rules inbound_rule --name firewall_name --outbound-rules outbound_rule --tag-names tag_name Create a firewall.
get firewall_id Get firewalls.
update firewall_id --droplet-ids 123,345 --inbound-rules inbound_rule --name firewall_name --outbound-rules outbound_rule --tag-names tag_name Update a firewall.
list List firewalls.
list-by-droplet droplet_id List firewalls by Droplet ID.
delete firewall_id Delete a firewall.
add-droplets firewall_id --droplet-ids 123,345 Add Droplets to a firewall.
remove-droplets firewall_id --droplet-ids 123,345 Remove Droplets from a firewall.
add-tags firewall_id --tag-names tag_name1,tag_name2 Add tags to a firewall.
remove-tags firewall_id --tag-names tag_name1,tag_name2 Remove tags from a firewall.
add-rules firewall_id --inbound-rules "inbound_rule1 inbound_rule2" --outbound-rules outbound_rule Add inbound/outbound rules to a firewall. Quote multiple rules and separate them with a space.
remove-rules firewall_id --inbound-rules "inbound_rule1 inbound_rule2" --outbound-rules "outbound_rule1 outbound_rule2" Remove inbound/outbound rules from a firewall. Quote multiple rules and separate them with a space.

When used as an argument to doctl, Firewall rules are expressed as:

Inbound Rule: protocol:protocol,ports:ports,address:ip_address,load_balancer_uid:load_balancer_uid,droplet_id:droplet_id
Outbound Rule:

Reading History of Actions for Your Account

The DigitalOcean system logs a history of actions taken on your Droplets, Floating IPs, and other resources. You can access this data with the doctl compute action command:

  • doctl compute action list

You can see actions for a specific Droplet like so:

  • doctl compute droplet actions droplet_id

Retrieving Your Account Information

You can discover basic details about your account, such as configured e-mail address and Droplet limit:

  • doctl account get

Since API requests are rate-limited, it may be helpful to see how many requests you've made recently, and when the limit is due to reset:

  • doctl account ratelimit

Retrieving Data in JSON Format

In scripting environments, or when working on the command line with data-processing tools, it's often helpful to get machine-readable output from a command. In addition to its default columnar text format, doctl will produce detailed JSON output, if given the --output json option:

  • doctl compute droplet get droplet_id --output json
Sample Output
{ "id": droplet_id, "name": "droplet_name", "memory": 1024, "vcpus": 1, "disk": 30, "region": { "slug": "nyc3", "name": "New York 3", "sizes": [ ...

In addition to being a format readable with standard libraries in most programming languages, the JSON output contains a great deal more detail than the plain text output, and may allow for more fine-grained inspection of Droplets and other resources.


The doctl utility is a helpful tool for managing Droplets and other resources at the command line. It can greatly reduce the amount of manual interaction with web-based interfaces needed for daily development and administrative tasks.

In addition to learning about the underlying API, you may want to explore libraries which wrap the API for popular programming languages, and tools such as Ansible for automating system-level tasks.


Creative Commons License