Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 35 ยท Automation and Terraform

The doctl Command Line for DigitalOcean

Manage DigitalOcean from the terminal with doctl: authentication contexts, droplet, volume, firewall and domain commands, JSON output, format columns and scripting tips.

Clicking through a control panel is fine for a first server and painful for the tenth. doctl is DigitalOcean's official command-line client: everything the panel does (Droplets, volumes, firewalls, domains, Kubernetes, databases, Spaces keys) is a doctl command, which means you can put it in a script, a CI job or your shell history. It talks to the same public API (see the REST API lesson).

DigitalOcean is not available on this site, so commands are shown without output and the Python blocks are stand-ins that practise the output handling you will use in scripts.

Install and authenticate

Install it from your package manager or the official releases page (for example brew install doctl on macOS, snap install doctl on Ubuntu, scoop install doctl on Windows). Then create a personal access token in the control panel (API, Tokens) and run:

Terminal
doctl auth init --context personal
doctl auth list
doctl auth switch --context personal
doctl account get

A context is a named token. Keep one per account or team and switch between them, or pass --context work on one command. The token is stored in doctl's configuration file, so protect that file like a password. In CI use the DIGITALOCEAN_ACCESS_TOKEN environment variable instead of auth init, and give the token only the scopes the job needs.

The command shape

Commands follow doctl <area> <resource> <action>:

Terminal
doctl compute droplet list
doctl compute droplet create web-1 \
  --region nyc1 --size s-1vcpu-1gb --image ubuntu-24-04-x64 \
  --ssh-keys 12345678 --vpc-uuid YOUR_VPC_ID --tag-names web --wait
doctl compute droplet get web-1
doctl compute ssh web-1 --ssh-user deploy
doctl compute droplet delete web-1 --force
  • Find valid values with doctl compute region list, doctl compute size list, doctl compute image list-distribution, doctl compute ssh-key list.
  • --wait makes the command block until the Droplet is active.
  • delete asks for confirmation; --force skips it, so be careful in scripts.
  • doctl compute droplet delete --tag-name test deletes by tag, a powerful (and dangerous) feature.

Other frequently used commands:

Terminal
doctl compute volume create data-1 --region nyc1 --size 50GiB
doctl compute volume-action attach VOLUME_ID DROPLET_ID
doctl compute domain records create example.com --record-type A --record-name www --record-data 203.0.113.10 --record-ttl 300
doctl compute firewall list
doctl compute snapshot list
doctl compute reserved-ip list
doctl projects list
doctl balance get
doctl invoice list

Run doctl compute --help and doctl help for the full set; each command has --help with examples.

Output formats

By default doctl prints a table. Two options make it script-friendly:

Terminal
doctl compute droplet list --format ID,Name,PublicIPv4,Region,Status --no-header
doctl compute droplet list --output json
doctl compute droplet list --output json | jq -r '.[] | select(.status=="active") | .name'

--format picks columns (names are the capitalised field names, shown in --help), --no-header removes the heading, and --output json gives machine-readable output you can filter with jq. Never parse the default table with awk when JSON is available.

The first stand-in processes JSON shaped like a trimmed droplet list result (fabricated sample data, not real output).

Python Stand-in: filter droplet JSON like jq

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Scripting safely

A small script that finds every Droplet tagged web and prints SSH commands:

Terminal
#!/usr/bin/env bash
set -euo pipefail
for ip in $(doctl compute droplet list --tag-name web --format PublicIPv4 --no-header); do
  echo "ssh deploy@$ip"
done

Habits that prevent accidents:

  • Use set -euo pipefail so a failed command stops the script.
  • Always list before you delete, and print what a delete would affect.
  • Prefer tags for groups of resources; a typo in a name is harmless, a wrong tag is not.
  • Keep tokens out of scripts; read DIGITALOCEAN_ACCESS_TOKEN from the environment.
  • doctl respects the API rate limit; on 429 responses wait and retry.
  • For repeatable infrastructure use Terraform instead of long shell scripts: scripts create things, but they do not know what already exists.

The second stand-in builds the --format output from the same data, aligned like a table.

Python Stand-in: format selected columns

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a doctl context?

    Contexts let you keep tokens for several accounts or teams and switch with doctl auth switch.
  2. 2. Which flag makes doctl compute droplet create wait until the Droplet is active?

    --wait blocks until the resource is ready.
  3. 3. What is the safest way to extract fields in a script?

    JSON is stable and machine-readable; table layout is for humans.
  4. 4. Where should a CI job get its DigitalOcean token?

    CI secrets keep the token out of the repository and a narrow scope limits the damage.

Summary

  • doctl is the official CLI for the DigitalOcean API; authenticate with a token stored in a context or an environment variable.
  • Commands look like doctl compute droplet create; use --wait, --format, --no-header and --output json.
  • Filter JSON with jq or a JSON library, and always list before deleting.
  • Use Terraform when you need repeatable, tracked infrastructure.

Next: The DigitalOcean REST API and Automation