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

Introduction

DigitalOcean’s web-based control panel provides a point-and-click interface for managing Droplets. However, you may prefer a command-line tool 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.

doctl is the official DigitalOcean command-line client. It uses the DigitalOcean API to provide access to most account and Droplet features.

Prerequisites

To follow this tutorial, you will need:

• A local computer with doctl installed by following the project’s installation and configuration instructions.

This tutorial is intended as a reference for most of doctl’s operations. Because doctl commands closely parallel the API, it may also be helpful to read the API documentation and How To Use the DigitalOcean API v2.

Generic doctl Usage

Invoking Commands

In doctl, 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 categories:

• account for account-related information
• auth for authenticating with DigitalOcean
• compute for managing infrastructure

To see an overview of all commands, you can invoke doctl by itself. To see all available commands under one of the three main categories, you can use doctl category, like doctl compute. For a usage guide on a specific command, enter the command with the --help flag, as in doctl compute droplet --help.

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.

By default, doctl formats its output in columns of human-readable text, but can produce detailed JSON output using 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 may allow more fine-grained inspection of Droplets and other resources.

Formatting

It’s often useful to obtain only a set of fields from output. To do this, you can use the --format flag followed by a list of your desired fields. For example, if you want to obtain only the ID, name, and IP address of your Droplets, you can use the following command:

doctl compute droplet list --format "ID,Name,PublicIPv4"

Sample output
ID          Name       Public IPv4
50513569    doctl-1    67.205.152.65
50513570    test       67.205.148.128
50513571    node-1     67.205.131.88

Templates

The doctl compute droplet get command supports output templating, which lets you customize the format of the output. To use this feature, specify the Go-formatted template via the --template flag.

For example, if you want to get a Droplet’s name in the format droplet_name: droplet_name, you would use the following get command:

doctl compute droplet get 12345678 --template "droplet_name: {{ .Name}}

Output
droplet_name: ubuntu-1gb-nyc3-01

Working with Resources

Listing Resources

To get a list of resources, like Droplets, you can use the list command with no parameters.

doctl compute droplet list

Sample output for list command
ID          Name       Public IPv4       Private IPv4    Public IPv6    Memory    VCPUs    Disk    Region    Image                 Status    Tags
50513569    test-1     67.205.152.65                                    512       1        20      nyc1      Ubuntu 16.04.2 x64    active
50513571    test-2      67.205.131.88                                    512       1        20      nyc1      Ubuntu 16.04.2 x64    active
50513570    site       67.205.148.128                                   512       1        20      nyc1      Ubuntu 16.04.2 x64    active

The list command supports a glob as an optional parameter. A glob represents pattern with wildcard characters which can be used to filter specific resources by name. For example, to get a list of Droplets whose names start with test, you can use the following command:

doctl compute droplet list 'test*'

Sample output for list command with 'doctl-' as glob
ID          Name       Public IPv4       Private IPv4    Public IPv6    Memory    VCPUs    Disk    Region    Image                 Status    Tags
50513569    test-1     67.205.152.65                                    512       1        20      nyc1      Ubuntu 16.04.2 x64    active
50513571    test-2      67.205.131.88                                    512       1        20      nyc1      Ubuntu 16.04.2 x64    active

Creating Resources

Creating a resource requires longer commands with more detailed parameters. To create a Droplet, you’ll need to specify the image you want to use, the datacenter region, and the kind of Droplet you want by using its associated slug. See New Size Slugs for Droplet Plan Changes to find the slug you want to use. Alternatively, run the doctl compute size list command.

For example, the following command creates a 64-bit Debian 8 Droplet named test with 1GB of memory, one CPU, an SSH key, and backups enabled.

doctl compute droplet create test --size s-1vcpu-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

You’ll see this output:

Sample Droplet creation output
ID              Name    Public IPv4     Memory  VCPUs   Disk    Region  Image           Status
11450164        test                    1024    1       30      nyc1    Debian 8.3 x64  new

Deleting a resource requires a resource ID as an argument, or a resource name in the event that an ID doesn’t exist for given resource (e.g. tags). To confirm your intentions, you need to confirm all delete actions by answering the confirmation question with y or yes.

doctl compute droplet delete 123456

Output
Warning: Are you sure you want to delete droplet(s) (y/N) ?

Not providing an answer or providing an answer different from y or yes will cancel the action without deleting the resource. You can make doctl assume an affirmative answer without explicitly providing it, using --f (--force) flag:

doctl compute droplet delete -f 123456

Finding Unique Identifiers for Resources

The Droplet creation command requires 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.

A number of resources, such as Droplets and images, are identified by a value (often numeric) unique within DigitalOcean’s database.

You can get the required unique identifiers for most commands from the API:

Working with Droplets

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.

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.

Working with SSH

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, numeric ID or Private IP:

doctl compute ssh droplet_name

doctl compute ssh droplet_id

doctl compute ssh --ssh-private-ip droplet_private_ip

Also, you can provide a command to execute once the SSH connection is established using the --ssh-command flag. This will run the command, the output of which will be printed on your local terminal, and then the SSH session will close.

doctl compute ssh --ssh-command command

Note: SSH command forwarding is currently not available on Windows.

The default SSH user name is root (core for CoreOS) and the default port is 22. You can use flags to set non-default values and enable other features:

You can also change the default configuration values in a configuration file. The project’s README file has more detail on how to do this.

Using SSH Keys

You can manage the SSH public keys associated with your account using the doctl compute ssh-key command. Most commands which reference SSH keys accept either the numeric ID for the key or its 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.

Assigning Floating IPs to Droplets

The doctl compute floating-ip-action command is used to assign or unassign a Floating IP from a Droplet.

Working with Domains

The doctl compute domain command is used to manage domains. See our Introduction to Managing DNS series for a broad overview of the subject.

Managing Domain Records

The doctl compute domain records command can be used to create, delete, update or get information about domain’s DNS records.

Working with Block Storage Volumes

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.

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.

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.

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.

Managing Certificates

The doctl compute certificate subcommand allows you to upload and manage SSL certificates, private keys, and certificate chains.

Working with Snapshots

The doctl compute snapshot command can be used to list, delete, or get information about Droplet and Volume Snapshots.

To create a new Snapshot, you need to use the appropriate command under the relevant resource command tree. For example:

• doctl compute droplet-action snapshot droplet_ID creates a Snapshot from a Droplet.
• doctl compute volume snapshot volume_ID creates a Snapshot from a Volume.

Working with Images

The doctl compute image command allows you to manage all images, including distribution images, application images, and user-created images such as backups and snapshots. We recommend using the snapshot command for managing snapshots because it provides more detail, has delete functionality, and supports Block Storage snapshots.

Invoking Image Actions

The doctl compute image-action command allows you to transfer images and get details about actions invoked on images.

Working with Firewalls

The doctl compute firewall command lets you create and manage Firewalls, including creating and maintaining rules. For more about information about administering Firewalls using doctl, check out the How To Secure Web Server Infrastructure With DigitalOcean Cloud Firewalls Using Doctl tutorial.

When used as an argument to doctl, inbound or outbound rules should be expressed like: protocol:protocol,ports:ports,droplet_id:droplet-id.

Working with Tags

Tags are used to apply custom labels to resources, allowing you to easily filter them. You can learn more about Tags in the How To Tag DigitalOcean Droplets tutorial.

Working with Your Account

Reading History of Actions for Your Account

The DigitalOcean system logs a history of the 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 your configured e-mail address and Droplet limit:

doctl account get

Because 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

Conclusion

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.