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 – 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 list to list all your droplets, or doctl compute droplet create –image ubuntu-20-04-x64 –size s-1vcpu-1gb –region lon1 my-droplet to 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 list to retrieve existing databases and doctl databases db create
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:
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.
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.
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.
