DigitalOcean provides an API as an alternative to its web-based cloud control panel. The official
doctl command-line client offers an intuitive wrapper around the API. You can administer your DigitalOcean resources using an easily scriptable programmatic interface.
Most Linux distributions include
doctl in their package repositories. It’s also offered as a Snap on distributions with Snap support. Using a package manager is the preferred installation mechanism as it will keep you updated with new releases.
DigitalOcean also provides official Docker containers on Docker Hub. These are ideal for one-time use within Docker-supported environments. Instructions on using the Docker image can be found on its Docker Hub page; in general, usage is identical to a direct installation.
Creating An Access Token
You need to connect
doctl to your DigitalOcean account before you start using the tool. Authentication is persistent once setup, so you won’t need to supply credentials with every command.
Begin by logging into your DigitalOcean account. Click the “API” link at the bottom of the sidebar. Under “Personal access tokens”, click the “Generate New Token” button. Give your token a name and enable both the read and write scopes.
After your token’s created, its value will be displayed within the control panel. Save this now as it won’t be possible to retrieve it later. You’ll need to create a new token if this one’s value is forgotten.
Connecting to Your Account
You can now return to your terminal. Use the generated access token to connect
doctl to your account:
doctl auth init
You’ll be prompted to enter the access token. Assuming validation is successful,
doctl will save your credentials. They’ll be sent automatically with subsequent commands. Configuration files are saved within the
.config/doctl directory in your home folder.
Testing Your Configuration
You should now be able to successfully interact with your DigitalOcean account.
doctl account get to check your account details can be retrieved.
Interacting With DigitalOcean Resources
doctl lets you interact with almost all the available DigitalOcean resources. There’s too many possibilities to cover exhaustively in one article, so we’ll stick to detailing a few commonly used commands.
doctl compute– High-level command for interacting with a variety of resource types. Includes droplets, domains, volumes, backups, snapshots, images, firewalls and load balancers.
doctl compute droplet– Enables you to interact with Droplets. Try
doctl compute droplet listto list all your droplets, or
doctl compute droplet create --image ubuntu-20-04-x64 --size s-1vcpu-1gb --region lon1 my-dropletto create a basic Ubuntu droplet in the LON1 datacentre. A variety of other sub-commands provide complete management options.
doctl databases db– Interact with databases within a database cluster. Use
doctl databases db listto retrieve existing databases and
doctl databases db create <id> <name>to create. Other related commands allow you to scale your database clusters.
doctl kubernetes– This command namespace lets you manage your Kubernetes clusters. A plethora of sub-commands let you configure nodes, node pools, cluster versions and container registry connections.
doctl registry– Manages your DigitalOcean Container Registry, including options to create, delete and list registries and containers. You can also invoke or cancel the garbage collection process to free up storage space.
There’s a lot of functionality available; it’s advisable you refer to the official documentation to obtain the complete list of commands and options. Generally, any DigitalOcean API endpoint has an equivalent
Exploring the available commands is made simple by extensive built-in documentation. Running a top-level command such as
doctl compute without any arguments will display a list of all available sub-commands. This enables quick feature discovery and means you don’t need to commit the whole list to memory.
doctl supports command auto completion within most popular shells. Adding
source <(doctl completion bash) to your
~/.profile file is usually sufficient to enable this. Substitute
bash for your own shell. Shell-specific guidance can be found in the
Using Multiple Accounts (Contexts)
doctl provides streamlined support for multiple DigitalOcean user accounts. You can define standalone authenticated “contexts” which you switch between using the
--context flag or the
DIGITALOCEAN_CONTEXT environment variable.
To add a context, use the following command:
doctl auth init --context my-context
This is the same authentication command we saw earlier, this time modified to use the
my-context context. The context is automatically created if it doesn’t already exist. When no context is specified, the
default context is used.
Setting Default Configuration Values
You can set default values for most options and flags using the configuration file. This usually resides at
To define a configuration value, add it to the file using the format
The above setting would default all droplet creations to a type of
Defaults can be overridden at any time by passing a new value to the command line flag as normal.
doctl usually emits output as human-readable tables and lists. If you plan to use the tool within scripts, or want more detailed information, you can pass
--output json to get the raw JSON from the DigitalOcean API.
You can tailor the fields which are returned in tables using the
--format flag. Run the original command and take note of the column names in its output. You can pass these as a comma-separated list to
--format, removing any spaces which occur in the presented names. Only the given fields will be included when you run the modified command.
doctl can save you time when managing resources in your DigitalOcean accounts. It simplifies scripting and gives you a starting point when building your own monitoring and alerting tools.
DigitalOcean updates the utility on a regular basis. It supports almost all API operations and resource types. A notable exception is Spaces object storage; as this is Amazon S3-compatible, DigitalOcean advise you use an S3-specific management utility instead.