doctl (digitalocean/doctl)

doctl

https://github.com/digitalocean/doctl
Admin
doctl is a command-line interface (CLI) for the DigitalOcean API, enabling users to manage...

Tokens:154,797
Snippets:1,440
Trust Score:8.9
Update:2 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# doctl - DigitalOcean Command Line Interface

doctl is the official command-line interface (CLI) for the DigitalOcean API. It provides a unified way to manage your DigitalOcean resources including Droplets (virtual machines), Kubernetes clusters, managed databases, App Platform applications, container registries, and more. Written in Go, doctl enables DevOps workflows, automation scripts, and infrastructure management directly from the terminal.

The CLI wraps the DigitalOcean API v2 and provides a consistent command structure following the pattern `doctl <resource> <action> [options]`. It supports both text and JSON output formats, making it suitable for interactive use as well as scripting and CI/CD pipelines. Authentication is handled via API tokens that can be configured globally or per-command.

## Authentication

### Initialize doctl with API token
```bash
# Interactive authentication setup
doctl auth init

# Output:
# DigitalOcean access token: your_DO_token
# Validating token: OK

# Use specific context for multiple accounts
doctl auth init --context work-account
```

### Environment variable authentication
```bash
# Set token via environment variable (useful for CI/CD)
export DIGITALOCEAN_ACCESS_TOKEN=dop_v1_your_api_token_here
doctl account get
```

## Droplet Management

### List all Droplets
```bash
# List all Droplets on your account
doctl compute droplet list

# Output:
# ID          Name              Public IPv4      Private IPv4    Public IPv6    Memory    VCPUs    Disk    Region    Image                  VPC UUID                                Status    Tags    Features                     Volumes
# 386734086   example-droplet   203.0.113.1      10.132.0.2                     1024      1        25      nyc1      ubuntu-20-04-x64       12345678-1234-1234-1234-123456789abc   active    web     droplet_agent,backups

# Filter by region
doctl compute droplet list --region nyc1

# Return specific columns
doctl compute droplet list --format ID,Name,PublicIPv4,Status
```

### Create a new Droplet
```bash
# Create a basic Droplet
doctl compute droplet create example-droplet \
  --size s-2vcpu-2gb \
  --image ubuntu-20-04-x64 \
  --region nyc1

# Create with SSH keys and user-data script
doctl compute droplet create web-server \
  --size s-2vcpu-4gb \
  --image ubuntu-22-04-x64 \
  --region sfo3 \
  --ssh-keys 12345678,87654321 \
  --user-data '#!/bin/bash
touch /root/provisioned.txt
apt update && apt install -y nginx' \
  --tag-names web,production \
  --enable-backups \
  --wait

# Output:
# ID          Name         Public IPv4    Status    Tags
# 123456789   web-server   203.0.113.5    active    web,production
```

### Manage Droplet lifecycle
```bash
# Get Droplet details
doctl compute droplet get 386734086 --format Name,ID,PublicIPv4,Region.Name

# Delete a Droplet (by ID or name)
doctl compute droplet delete 386734086 --force

# Tag a Droplet
doctl compute droplet tag 386734086 --tag-name production

# SSH into a Droplet by name
doctl compute ssh web-server

# SSH as specific user
doctl compute ssh admin@web-server
```

## Kubernetes Cluster Management

### List Kubernetes clusters
```bash
# List all clusters
doctl kubernetes cluster list

# Output:
# ID                                      Name              Region    Version          Auto Upgrade    Status     Node Pools
# abc12345-1234-5678-9012-abcdef123456    production-k8s    nyc1      1.28.2-do.0      false           running    default-pool

# Get detailed cluster info
doctl kubernetes cluster get production-k8s --format ID,Name,Endpoint,Status
```

### Create a Kubernetes cluster
```bash
# Create cluster with default settings (3 nodes, nyc1, latest version)
doctl kubernetes cluster create my-cluster

# Create cluster with custom configuration
doctl kubernetes cluster create production-cluster \
  --region nyc1 \
  --version 1.28.2-do.0 \
  --node-pool "name=worker-pool;size=s-4vcpu-8gb;count=3;auto-scale=true;min-nodes=2;max-nodes=5;label=env=production;taint=dedicated=app:NoSchedule" \
  --ha \
  --auto-upgrade \
  --maintenance-window saturday=02:00 \
  --wait

# Output:
# Notice: Cluster is provisioning, waiting for cluster to be running
# Notice: Cluster created, fetching credentials
# Notice: Adding cluster credentials to kubeconfig file found in "/home/user/.kube/config"
# ID                                      Name                Region    Version         Status
# def45678-5678-9012-3456-ghijkl456789    production-cluster  nyc1      1.28.2-do.0     running
```

### Manage kubeconfig
```bash
# Save cluster credentials to local kubeconfig
doctl kubernetes cluster kubeconfig save production-cluster

# Show kubeconfig YAML
doctl kubernetes cluster kubeconfig show production-cluster

# Remove cluster from kubeconfig
doctl kubernetes cluster kubeconfig remove production-cluster
```

### Manage node pools
```bash
# List node pools in a cluster
doctl kubernetes cluster node-pool list production-cluster

# Create a new node pool
doctl kubernetes cluster node-pool create production-cluster \
  --name gpu-pool \
  --size g-4vcpu-16gb \
  --count 2 \
  --auto-scale \
  --min-nodes 1 \
  --max-nodes 4 \
  --label workload=ml \
  --taint "gpu=true:NoSchedule"

# Update node pool
doctl kubernetes cluster node-pool update production-cluster worker-pool --count 5

# Delete node pool
doctl kubernetes cluster node-pool delete production-cluster gpu-pool --force
```

## App Platform

### List and manage apps
```bash
# List all apps
doctl apps list --format ID,Spec.Name,DefaultIngress,Created

# Get app details
doctl apps get f81d4fae-7dec-11d0-a765-00a0c91e6bf6

# Output (JSON format):
# doctl apps get f81d4fae-7dec-11d0-a765-00a0c91e6bf6 -o json
```

### Create an app from spec file
```yaml
# app-spec.yaml
name: sample-nodejs
region: nyc
services:
  - name: web
    github:
      repo: digitalocean/sample-nodejs
      branch: main
    instance_count: 1
    instance_size_slug: basic-xxs
    http_port: 8080
    routes:
      - path: /
```

```bash
# Create app from spec
doctl apps create --spec app-spec.yaml --wait

# Output:
# ID                                      Spec.Name       DefaultIngress                            Created
# f81d4fae-7dec-11d0-a765-00a0c91e6bf6    sample-nodejs   https://sample-nodejs-abc123.ondigitalocean.app   2024-01-15T10:30:00Z

# Update existing app
doctl apps update f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --spec updated-spec.yaml --wait
```

### Deployments and logs
```bash
# Create new deployment
doctl apps create-deployment f81d4fae-7dec-11d0-a765-00a0c91e6bf6 --wait

# List deployments
doctl apps list-deployments f81d4fae-7dec-11d0-a765-00a0c91e6bf6

# Get deployment logs
doctl apps logs f81d4fae-7dec-11d0-a765-00a0c91e6bf6 web --type build
doctl apps logs f81d4fae-7dec-11d0-a765-00a0c91e6bf6 web --type run --follow --tail 100

# Open console session
doctl apps console f81d4fae-7dec-11d0-a765-00a0c91e6bf6 web
```

## Managed Databases

### List and create databases
```bash
# List all database clusters
doctl databases list --format ID,Name,Engine,Version,Status,Region

# Output:
# ID                                      Name         Engine    Version    Status    Region
# ca9f591d-1234-5678-9abc-def012345678    mydb-pg      pg        14         online    nyc1

# Create a PostgreSQL database cluster
doctl databases create production-db \
  --engine pg \
  --version 15 \
  --region nyc1 \
  --size db-s-2vcpu-4gb \
  --num-nodes 2 \
  --wait

# Create a MySQL database
doctl databases create mysql-cluster \
  --engine mysql \
  --version 8 \
  --region sfo2 \
  --size db-s-1vcpu-1gb \
  --num-nodes 1
```

### Database connection and management
```bash
# Get connection details
doctl databases connection ca9f591d-1234-5678-9abc-def012345678

# Output:
# Host                                              Port    User     Password    Database    SSL Required
# db-postgresql-nyc1-12345-do-user.db.ondigitalocean.com    25060   doadmin  secretpwd   defaultdb   true

# Get private network connection
doctl databases connection ca9f591d-1234-5678-9abc-def012345678 --private

# List backups
doctl databases backups ca9f591d-1234-5678-9abc-def012345678

# Resize database cluster
doctl databases resize ca9f591d-1234-5678-9abc-def012345678 \
  --num-nodes 3 \
  --size db-s-4vcpu-8gb \
  --wait
```

### Database users and pools
```bash
# List database users
doctl databases user list ca9f591d-1234-5678-9abc-def012345678

# Create a new user
doctl databases user create ca9f591d-1234-5678-9abc-def012345678 app-user

# Create connection pool (PostgreSQL only)
doctl databases pool create ca9f591d-1234-5678-9abc-def012345678 \
  --db defaultdb \
  --user app-user \
  --size 10 \
  --mode transaction \
  app-pool
```

## Container Registry

### Create and manage registry
```bash
# Create a container registry
doctl registry create example-registry --subscription-tier basic --region nyc3

# Get registry details
doctl registry get

# Output:
# Name               Endpoint
# example-registry   registry.digitalocean.com/example-registry

# Log Docker into registry
doctl registry login

# Log in with read-only credentials
doctl registry login --read-only

# Generate Docker config for CI/CD
doctl registry docker-config --read-write --expiry-seconds 86400
```

### Manage repositories and images
```bash
# List repositories
doctl registry repository list-v2

# List tags for a repository
doctl registry repository list-tags my-app

# Output:
# Tag       CompressedSizeBytes    UpdatedAt
# v1.0.0    52428800               2024-01-15T10:00:00Z
# latest    52428800               2024-01-15T10:00:00Z

# Delete a tag
doctl registry repository delete-tag my-app v1.0.0 --force

# Run garbage collection
doctl registry garbage-collection start --include-untagged-manifests --force
```

### Kubernetes integration
```bash
# Generate Kubernetes secret manifest for registry access
doctl registry kubernetes-manifest | kubectl apply -f -

# Add registry to Kubernetes cluster
doctl kubernetes cluster registry add my-cluster
```

## VPC and Networking

### VPC management
```bash
# List VPCs
doctl vpcs list

# Create a VPC
doctl vpcs create \
  --name production-vpc \
  --region nyc1 \
  --ip-range 10.10.10.0/24

# Get VPC details
doctl vpcs get vpc-uuid-here
```

### Load Balancers
```bash
# Create a load balancer
doctl compute load-balancer create \
  --name web-lb \
  --region nyc1 \
  --forwarding-rules "entry_protocol:http,entry_port:80,target_protocol:http,target_port:8080" \
  --droplet-ids 123456,234567

# List load balancers
doctl compute load-balancer list
```

## Volumes and Block Storage

### Manage volumes
```bash
# List volumes
doctl compute volume list

# Create a volume
doctl compute volume create data-volume \
  --region nyc1 \
  --size 100GiB \
  --desc "Database storage volume"

# Attach volume to Droplet
doctl compute volume-action attach data-volume 386734086 --wait

# Create snapshot
doctl compute volume snapshot data-volume --name data-backup-2024
```

## Projects and Organization

### Project management
```bash
# List projects
doctl projects list

# Create a project
doctl projects create \
  --name "Production Environment" \
  --purpose "Production services" \
  --environment Production

# Assign resources to project
doctl projects resources assign project-uuid \
  --resource "do:droplet:386734086" \
  --resource "do:kubernetes:cluster-uuid"
```

## Output Formats and Scripting

### JSON output for automation
```bash
# Get Droplet info as JSON
doctl compute droplet get 386734086 -o json | jq '.id, .name, .networks.v4[0].ip_address'

# List clusters as JSON for scripting
cluster_id=$(doctl kubernetes cluster list -o json | jq -r '.[0].id')
echo "First cluster ID: $cluster_id"
```

### Custom format output
```bash
# Use template for specific fields
doctl compute droplet get 386734086 --template "{{.ID}}: {{.Name}} ({{.Region.Name}})"

# Output: 386734086: example-droplet (New York 1)
```

## Summary

doctl provides comprehensive command-line access to all DigitalOcean services, enabling infrastructure-as-code workflows and automation. The CLI follows consistent patterns across resource types: `list` for viewing resources, `create`/`delete` for lifecycle management, and `get` for detailed information. Commands support `--wait` flags for synchronous operations, `--force` for non-interactive scripting, and `--format`/`-o json` for customizable output.

Common integration patterns include: using environment variables (`DIGITALOCEAN_ACCESS_TOKEN`) for CI/CD authentication, piping JSON output to `jq` for data extraction, combining with `kubectl` for Kubernetes workflows, and leveraging `--wait` flags in deployment scripts. The tool supports multiple authentication contexts for managing different accounts or environments, making it ideal for teams managing multiple DigitalOcean projects.