doctl

To use doctl, you must provide a DigitalOcean access token.

Non-Docker users: Run the auth init command and follow the prompt to enter your token.

Docker users: Use the DIGITALOCEAN_ACCESS_TOKEN environment variable to authenticate.

doctl auth init

You can build a local Docker image from the repository's Dockerfile and run doctl within a container. To authenticate, pass your DigitalOcean access token via the DIGITALOCEAN_ACCESS_TOKEN environment variable.

1. Build the image: docker build --tag=doctl .

2. Run a command: docker run --rm --interactive --tty --env=DIGITALOCEAN_ACCESS_TOKEN="your_DO_token" doctl <command>

docker build --tag=doctl .

docker run --rm --interactive --tty --env=DIGITALOCEAN_ACCESS_TOKEN="your_DO_token" doctl any_doctl_command

You can download prebuilt binaries directly from the GitHub Releases page.

To download and extract a Linux amd64 release using a single command:

curl -sL https://github.com/digitalocean/doctl/releases/download/v<version>/doctl-<version>-linux-amd64.tar.gz | tar -xzv

After extraction, move the binary to your PATH (e.g., /usr/local/bin on Linux/macOS):

sudo mv ~/doctl /usr/local/bin

You can manage multiple accounts simultaneously using authentication contexts. By default, the context is named default.

• Create a new context: Use doctl auth init --context <new-context-name> or set the DIGITALOCEAN_CONTEXT environment variable.
• Switch the default context: Use doctl auth switch --context <new-context-name> to make a specific context the default for all future commands.
• Use a specific context for a single command: Pass the --context <name> flag to any command.

Note: The --access-token flag and DIGITALOCEAN_ACCESS_TOKEN environment variable are only acknowledged if the default context is being used. To override a non-default context with a specific token, use: doctl --context default --access-token <token> ....

doctl compute droplet list --context <new-context-name>

To build a snap package locally for testing purposes, you must first install snapcraft. Depending on your operating system, use the following commands:

Ubuntu:

sudo snap install snapcraft --classic

MacOS:

brew install snapcraft

Once snapcraft is installed, build the package by running make snap from the repository root.

You can install doctl using various package managers depending on your operating system:

• macOS: Use Homebrew: brew install doctl.
• Snap (Linux): Use Snap: sudo snap install doctl.
• Arch Linux: Use pacman: sudo pacman -S doctl.
• Fedora: Use dnf: sudo dnf install doctl.
• Nix: Install from Nixpkgs.

Auto-completion allows you to use TAB to complete commands. Note: Auto-completion is not available for Windows users.

To generate a script, use doctl completion <shell> where <shell> is bash, zsh, or fish.

Linux Setup

Add the following to your ~/.profile:

source <(doctl completion bash)

For ZSH, add this to ~/.zshrc:

compdef _doctl doctl

macOS Setup

Bash:

1. Install bash-completion via Homebrew: brew install bash-completion.
2. Add source $(brew --prefix)/etc/bash_completion to your .profile or .bashrc.

ZSH: Add this to your ~/.zshrc:

autoload -U +X compinit; compinit

If you installed doctl via Snap, you may need to manually connect interfaces to enable specific functionalities:

• Kubernetes: To use with kubectl, connect the kube-config interface: sudo snap connect doctl:kube-config
• SSH: To use doctl compute ssh, connect the ssh-keys interface: sudo snap connect doctl:ssh-keys :ssh-keys
• Docker: To use doctl registry login (which adds credentials to your Docker config), connect the dot-docker interface: sudo snap connect doctl:dot-docker

To uninstall doctl using Homebrew and remove all configuration files on macOS:

1. Uninstall the formula: brew uninstall -f doctl
2. Remove the configuration directory: rm -rf "$HOME/Library/Application Support/doctl"

The doctl compute certificate command allows you to store and manage SSL certificates and private keys. Once stored, certificates are assigned a unique ID for use in DigitalOcean workflows.

Available Subcommands

• get <id>: Retrieve details about a specific certificate.
• create: Create a new Let's Encrypt certificate or upload a custom certificate.
• list: Retrieve a list of all certificates associated with your account.
• delete <id>: Delete a specified certificate.

Certificate Details

When listing or getting certificates, the following information is available:

• Certificate ID
• Name
• DNS Names (comma-separated list)
• SHA-1 fingerprint
• Expiration date (ISO8601)
• Creation date (ISO8601)
• Type (custom or lets_encrypt)
• State (pending, verified, or error)