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