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

UpdatedJanuary 8, 2018 78.1k views DigitalOcean API Configuration Management

An earlier version of this tutorial was written by Brennen Bearnes.

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:

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 set of fields from output. To do this, you can use the --format flag, which takes list of fields by its name. For example, if you want to 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.

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

  • 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 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 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.

Some identifiers are guessable, 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.

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.
doctl compute tag list Available Tags. Use the string in the Name column.

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.

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 Create a Droplet. Size, image and region are all mandatory.
delete droplet_id_or_name 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.
tag droplet_id/droplet_name Tag a Droplet.
untag droplet_id/droplet_name Untag 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
get droplet_id --action-id action_id Get details about action on a Droplet.
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 in order to prevent data loss.
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.
upgrade droplet_id Upgrade 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 a Droplet. The Droplet must be powered off. By default, disk is not resized, which allows Droplet to be downgraded. You can resize disk using the --resize-disk flag.
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.

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:

Flag Description
--ssh-user string User name to use for the SSH session.
--ssh-port int The port for the SSH session.
--ssh-key-path string Path to SSH key.
--ssh-agent-forwarding Enable agent forwarding.

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.

doctl compute ssh-key subcommand Notes
list List SSH keys associated with your account.
`get <^>sshkeyid sshkeyfingerprint<^>`
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/id_rsa.pub Associate a public key with your account by specifying a source file.
delete ssh_key_id_or_fingerprint Delete a key from your account by numeric ID or fingerprint.
update ssh_key_id_or_fingerprint --key-name new_key_name Change a key's name by numeric ID or 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
list List all Floating IP addresses.
get floating_ip_address Get the details for a Floating IP address.
create --region nyc1 Create a Floating IP in nyc1 region.
delete floating_ip_address Delete a floating IP address.

Assigning Floating IPs to Droplets

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

doctl compute floating-ip-action subcommand Notes
assign floating_ip droplet_id Assign a Floating IP to the Droplet by its numeric ID.
unassign floating_ip Unassign a Floating IP.
get floating_ip action_id Get details about a Floating IP action by its numeric ID.

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.

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

Managing Domain Records

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

doctl compute domain records subcommand Notes
list domain_name List records for given domain.
create domain_name --record-type record_type Create an record for domain.
delete domain_name record_id Delete record by numeric ID.
update domain_name --record-id record_id Update record by numeric ID.

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.

doctl compute volume subcommand Notes
list List volumes.
create volume_name --region volume_region --size volume_size Create a volume. The name, region, and size are mandatory.
get volume_ID Get volume by numeric ID.
delete volume_ID Delete volume.
snapshot volume_ID Snapshot 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 droplet_id Detach a volume from a Droplet.
resize volume_id --region volume_region --size new_size Resize a volume.

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
list List load balancers.
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.
update --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.
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.

Managing Certificates

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

doctl compute certificate subcommand Notes
list List all Certificates.
get certificate_id Get a Certificate by ID.
create --name certificate_name --leaf-certificate-path leaf_certificate_path Create a Certificate. Name and Leaf Certificate Path are mandatory.
delete certificate_id Delete a Certificate by ID.

Working with Snapshots

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

doctl compute snapshot subcommand Notes
list List all Snapshots.
get snapshot_ID Get a Snapshot.
delete snapshot_ID Delete a Snapshot.

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.

doctl compute image subcommand Notes
list --public List all images.
list-distribution --public List all available distribution images.
list-application --public List all available One-Click Applications.
list-user List all user-created images.
get image_id Get an Image by ID.
update image_id --name image_name Update Image's name. Name is mandatory.
delete image_id Delete an Image by ID.

Invoking Image Actions

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

doctl compute image-action subcommand Notes
get image_id --action-id action_id Get an Action for Image by its ID. Action ID is mandatory.
transfer image_id --region region Transfer an Image to the another region. Image ID and region are mandatory.

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.

doctl compute firewall command Notes
list List all Firewalls.
list-by-droplet droplet_id List all Firewalls by Droplet's numeric ID.
create --name firewall_name --inbound-rules inbound_rules --outbound-rules outbound_rules Create a Firewall. The name and at least an inbound or outbound rule are mandatory.
update firewall_id --name firewall_name --inbound-rules inbound_rules --outbound-rules outbound_rules Update a Firewall. The numeric ID, name and at least an inbound or outbound rule are mandatory.
get firewall_id Get a Firewall by its numeric ID.
delete firewall_id Delete a Firewall by numeric ID.
add-droplets firewall_id --droplet-ids droplet_IDs Add Droplets by their numeric ID to the Firewall.
remove-droplets firewall_id --droplet-ids droplet_IDs Remove Droplets from the Firewall by their numeric IDs.
add-tags firewall_id --tag-names tags Add Tags to the Firewall.
remove-tags firewall_id --tag-names tags Remove Tags from the Firewall.
add-rules firewall_id --inbound-rules inbound_rules --outbound-rules outbound_rules Add inbound or outbound rules to the Firewall.
remove-rules firewall_id --inbound-rules inbound_rules --outbound-rules outbound_rules Remove inbound or outbound rules to the Firewall.

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.

doctl compute tag subcommand Notes
create tag_name Create a Tag.
get tag_name Get a Tag by name.
list List all Tags.
delete tag_name Delete a Tag by name.

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.

16 Comments

Creative Commons License