DigitalOcean offers an API as an alternative to its web-based cloud control panel. The official
doctl command-line client provides an intuitive wrapper around the API. You can manage your DigitalOcean resources using an easily scriptable program interface.
Doctl is available on Windows, macOS and Linux systems. Different installation methods are supported depending on the platform. All systems can download the latest release directly from GitHub.
Most Linux distributions include
doctl in their package repositories. It is also offered as Snap-on distributions with Snap support. Using a package manager is the preferred installation mechanism as it notifies you of new releases.
DigitalOcean also offers official Docker containers on Docker Hub. These are ideal for single use in Docker supported environments. Instructions for using the Docker image can be found on the Docker Hub page; its use is generally identical to a direct installation.
Create an access token
You must connect
doctl to your DigitalOcean account before using the tool. Authentication is persistent after installation, so you don̵
Start by logging into your DigitalOcean account. Click on the “API” link at the bottom of the sidebar. Under “Personal Access Tokens”, click the “Generate New Token” button. Name your token and enable both read and write ranges.
After your token has been created, its value will be displayed in the control panel. Save this now as it will not be possible to retrieve it later. You must create a new token if its value has been 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 will be prompted to enter the access token. Assuming the validation is successful,
doctl stores your login details. They are automatically sent with subsequent orders. Configuration files are stored in the
.config/doctl directory in your home folder.
Test your configuration
You should now be able to communicate successfully with your DigitalOcean account.
Try to run
doctl account get to check whether your account information can be retrieved.
Interact with DigitalOcean sources
doctl lets you communicate with almost all available DigitalOcean sources. There are too many options to cover exhaustively in one article, so we’ll stick to a few commonly used commands.
doctl compute– High level command for interacting with different types of resources. Includes droplets, domains, volumes, backups, snapshots, images, firewalls, and load balancers.
doctl compute droplet– Allows you to interact with Droplets. To attempt
doctl compute droplet listto list all your drops, 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 data center. A variety of other subcommands provide full management options.
doctl databases db– Interaction with databases within a database cluster. Use
doctl databases db listto retrieve existing databases and
doctl databases db createto make. You can scale your database clusters with other related commands.
doctl kubernetes– This command namespace allows you to manage your Kubernetes clusters. A plethora of subcommands 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 view registries and containers. You can also call or cancel the garbage collection process to free up storage space.
A lot of functionality is available; It is advisable to consult the official documentation for the full list of commands and options. In general, every DigitalOcean API endpoint has an equivalent
Exploring the available commands is made easy by extensive built-in documentation. Run a top-level command, such as
doctl compute without arguments, a list of all available subcommands will be displayed. This allows quick detection of functions and means you don’t have to commit the entire list to memory.
doctl supports auto-completion of commands within the most popular shells. Add
source <(doctl completion bash) to your
~/.profile file is usually enough to make this possible. Deputy
bash for your own shell. Shell-specific guidelines can be found in the
Using multiple accounts (contexts)
doctl provides streamlined support for multiple DigitalOcean user accounts. You can define stand-alone authenticated "contexts" between which to switch with it
--context flag or the
DIGITALOCEAN_CONTEXT environment variable.
Use the following command to add context:
doctl auth init --context my-context
This is the same authentication command we saw earlier, this time modified every
my-context context. The context is automatically created if it does not already exist. If no context is specified, the
default context is used.
Set default configuration values
You can set default values for most options and flags using the configuration file. This is usually located on
To define a configuration value, add it to the file using the format
With the above setting, all drop creations will default to the type
Default values can be overridden at any time by passing a new value to the command line as normal.
doctl usually broadcasts output as human readable tables and lists. If you plan to use the tool within scripts, or want more detailed information, you can succeed
--output json to get the raw JSON from the DigitalOcean API.
You can customize the fields returned in tables with the
--format flag. Run the original command and note the column names in the output. You can pass this as a comma separated list to
--format, removing all spaces that appear in the presented names. Only the specified fields are included when you run the modified command.
doctl can save you time managing resources in your DigitalOcean accounts. It simplifies the use of scripts and gives you a starting point in building your own monitoring and alerting tools.
DigitalOcean regularly updates the utility. It supports almost all API operations and resource types. A notable exception is Spaces' object store; since this is compatible with Amazon S3, DigitalOcean recommends that you use an S3-specific management tool instead.
You can find complete
doctl documentation on the DigitalOcean docs site. The software is also open-source, so you can contribute your own enhancements to the GitHub repository.