Quick Links
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.
Installation
Doctl is available on Windows, macOS and Linux systems. A variety of installation methods are supported depending on platform. All systems can download the latest release directly from GitHub.
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.
Try running
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
-
doctl compute droplet
doctl compute droplet list
doctl compute droplet create --image ubuntu-20-04-x64 --size s-1vcpu-1gb --region lon1 my-droplet
-
doctl databases db
doctl databases db list
doctl databases db create <id> <name>
-
doctl kubernetes
-
doctl registry
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 doctl
command.
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.
In addition, 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 doctl
docs.
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 ~/.config/doctl/config.yaml
.
To define a configuration value, add it to the file using the format category.command.subcommand.flag: value
.
compute.droplet.create.size: s-1vcpu-1gb
The above setting would default all droplet creations to a type of s-1vcpu-1gb
.
Defaults can be overridden at any time by passing a new value to the command line flag as normal.
Output Formats
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.
Conclusion
Learning 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.
You can find complete doctl
documentation over on DigitalOcean's docs site. The software is also open-source so you can contribute your own improvements to its GitHub repository.