DigitalOcean doctl

doctl

doctl is a command-line interface (CLI) for the DigitalOcean API.

Usage:
  doctl [command]

Available Commands:
  1-click         Display commands that pertain to 1-click applications
  account         Display commands that retrieve account details
  apps            Display commands for working with apps
  auth            Display commands for authenticating doctl with an account
  balance         Display commands for retrieving your account balance
  billing-history Display commands for retrieving your billing history
  completion      Modify your shell so doctl commands autocomplete with TAB
  compute         Display commands that manage infrastructure
  databases       Display commands that manage databases
  help            Help about any command
  invoice         Display commands for retrieving invoices for your account
  kubernetes      Displays commands to manage Kubernetes clusters and configurations
  monitoring      [Beta] Display commands to manage monitoring
  projects        Manage projects and assign resources to them
  registry        Display commands for working with container registries
  version         Show the current version
  vpcs            Display commands that manage VPCs

Flags:
  -t, --access-token string   API V2 access token
  -u, --api-url string        Override default API endpoint
  -c, --config string         Specify a custom config file
      --context string        Specify a custom authentication context name
  -h, --help                  help for doctl
  -o, --output string         Desired output format [text|json] (default "text")
      --trace                 Show a log of network activity while performing a command
  -v, --verbose               Enable verbose output

Use "doctl [command] --help" for more information about a command.

有关每条可用命令的信息，请参阅完整参考文档。

• 安装 doctl
  • 使用包管理器（首选）
    • MacOS
    • 支持 Snap 的操作系统
      • 与 kubectl 搭配使用
      • 使用 doctl compute ssh
      • 与 Docker 搭配使用
    • Arch Linux
    • Fedora
    • 支持 Nix 的操作系统
  • Docker Hub
  • 从 GitHub 下载发行版
  • 安装 Beta 版本
  • 使用 Docker 构建
  • 从源代码构建开发版本
  • 依赖项
• 使用 DigitalOcean 进行身份验证
  • 使用浏览器登录
  • 使用 API 令牌
  • 登录多个 DigitalOcean 账户
• 配置默认值
  • 环境变量
• 启用 Shell 自动补全
  • Linux 自动补全
  • MacOS
• 卸载 doctl
  • 使用包管理器
    • 卸载 MacOS 版本
• 示例
• 教程

安装 doctl

使用包管理器（首选）

使用包管理器，只需几条命令即可安装 doctl 并及时获取新版本。 除了下方列出的官方支持的包管理器外，我们的社区还通过越来越多的包管理器分发 doctl；很可能已有适用于你平台的方案。

MacOS

使用 Homebrew 在 macOS 上安装 doctl：

brew install doctl

也可以通过 MacPorts 获取 doctl。请注意，该移植版本由社区维护，可能不是最新版本。

支持 Snap 的操作系统

在支持 Snap 的系统上使用 Snap 安装 doctl：

sudo snap install doctl

与 kubectl 搭配使用

使用 kubectl 需要为 doctl 配置 kube-config personal-files 连接：

sudo snap connect doctl:kube-config

使用 doctl compute ssh

使用 doctl compute ssh 需要核心 ssh-keys 接口：

sudo snap connect doctl:ssh-keys :ssh-keys

与 Docker 搭配使用

使用 doctl registry login 需要为 doctl 配置 dot-docker personal-files 连接：

sudo snap connect doctl:dot-docker

这样 doctl 就可以将 DigitalOcean 容器注册表凭据添加到 Docker 配置文件中。

Arch Linux

doctl 可在 Arch Linux 官方软件仓库中获取：

sudo pacman -S doctl

Fedora

doctl 可在 Fedora 官方软件仓库中获取：

sudo dnf install doctl

支持的 Nix 操作系统

NixOS 或其他受支持的 平台用户可以从 Nixpkgs 安装 doctl。请注意， 此软件包也由社区维护，版本可能不是最新版本。

Docker Hub

每个版本的容器都发布在 Docker Hub 上的 digitalocean 组织下。GitHub 发布页面中提供了容器链接。

从 GitHub 下载发布版本

访问 doctl GitHub 项目的发布 页面，找到适用于你的操作系统和架构的 压缩包。你可以通过浏览器下载压缩包，也可以复制其 URL，并使用 wget 或 curl 将其下载到主目录。

例如，使用 wget：

cd ~
wget https://github.com/digitalocean/doctl/releases/download/v<version>/doctl-<version>-linux-amd64.tar.gz

或者使用 curl：

cd ~
curl -OL https://github.com/digitalocean/doctl/releases/download/v<version>/doctl-<version>-linux-amd64.tar.gz

解压二进制文件：

tar xf ~/doctl-<version>-linux-amd64.tar.gz

也可以使用以下单行命令下载并解压：

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

其中，<version> 是完整的语义化版本号，例如 1.17.0。

在 Windows 系统上，双击 zip 压缩包即可解压 doctl 可执行文件。

将 doctl 二进制文件移到路径中的某个位置。例如，在 GNU/Linux 和 OS X 系统上：

sudo mv ~/doctl /usr/local/bin

Windows 用户可以按照如何：将工具位置添加到 PATH 环境变量中的说明，将 doctl 添加到 PATH。

安装 Beta 版本

有时，新功能会在正式发布（GA）之前通过 Beta 版本提前发布，以便用户尽早试用。Beta 版本的标签格式为 vX.Y.Z-beta.N，并发布在发布 页面上，标记为 “预发布”。

**注意：**上述软件包管理器（Homebrew、Snap、dnf）只会安装最新的 GA 版本，不会包含 Beta／预览功能。 要使用预览功能，请通过以下任一方法安装 Beta 版本。这是预期行为，并非错误。

使用 go install 安装 Beta 版本（最快）

如果你已配置 Go 环境，最快的方法是直接安装指定的 Beta 标签。查看发布 页面，找到最新的 -beta 标签，并将其代替 v<version>-beta.<n> 使用：

go install github.com/digitalocean/doctl/cmd/doctl@v<version>-beta.<n>

这会将 doctl 二进制文件放在 $(go env GOPATH)/bin 中；请确保该目录位于 PATH 中。

从源代码构建 Beta 版本

配置好 Go 环境后，直接从 Beta 标签（或功能分支）构建：

git clone https://github.com/digitalocean/doctl.git
cd doctl
git checkout v<version>-beta.<n>
go build -o doctl ./cmd/doctl
sudo mv ./doctl /usr/local/bin

从 GitHub 下载预构建的 Beta 版本（无需 Go）

如果你没有 Go 环境，请打开发布 页面，选择最新的 -beta 版本，并下载适用于你平台的压缩包。例如，在 GNU/Linux 上：

curl -sL https://github.com/digitalocean/doctl/releases/download/v<version>-beta.<n>/doctl-<version>-beta.<n>-linux-amd64.tar.gz | tar -xzv
sudo mv ./doctl /usr/local/bin

如果资源文件名格式不同，请从发布页面复制准确的下载 URL，而不要猜测。

验证已安装的版本

doctl version

显示的版本应与你安装的 -beta 标签一致。Beta 版本可能包含仍在变化的功能，通常不如 GA 版本稳定。

示例

例如，使用 go install 安装 v1.163.0-beta.2 标签：

go install github.com/digitalocean/doctl/cmd/[email protected]
doctl version
# doctl version 1.163.0-beta.2-...

使用 Docker 构建

如果你已配置 Docker，可以使用 doctl 的 Dockerfile 构建本地 Docker 镜像，并在容器中运行 doctl。

docker build --tag=doctl .

然后，你就可以在容器中运行它。

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

从源代码构建开发版本

如果你已配置好 Go 环境， 可以从命令行安装 doctl 的开发版本。

go install github.com/digitalocean/doctl/cmd/doctl@latest

开发版本可以让你提前了解 doctl 即将发布的新功能，但请注意，它可能存在错误。正式发布的版本通常会更加稳定。

依赖项

doctl 使用 Go 模块并采用 vendoring。

使用 DigitalOcean 进行身份验证

doctl 支持两种身份验证方式：使用 doctl auth login 通过浏览器登录，或使用 doctl auth init 粘贴 API 令牌。无论采用哪种方式，凭据都会保存到 doctl 配置文件中的一个身份验证上下文。

Docker 用户必须使用环境变量 DIGITALOCEAN_ACCESS_TOKEN 进行身份验证，具体说明请参阅本文档的安装部分。

使用浏览器登录

doctl auth login 无需创建或粘贴令牌即可登录。它使用 PKCE 的 OAuth 2.1 授权码流程，以 DigitalOcean 发布的 doctl 应用身份登录，因此无需提前注册。

doctl auth login

doctl 会打开浏览器，并等待你批准请求。授权链接有效期为 5 分钟；使用 --timeout 可更改此时长。如果浏览器没有打开，doctl 会打印链接，你可以自行访问。在没有浏览器的机器上，使用 --no-browser 可打印链接，而不打开浏览器。

默认情况下，你可以在授权页面选择要授予的权限。如需提前指定权限，请传入 --scopes：

doctl auth login --scopes "read write"

--scopes "read write" 会请求与具有完整权限的 API 令牌相同的访问权限。你也可以指定单项权限，例如 --scopes "droplet:read account:read"。添加 --save-scope 可在之后登录时重复使用这些权限；添加 --scopes "" --save-scope 可清除已保存的默认权限。

通过这种方式签发的访问令牌有效期较短。doctl 会将刷新令牌与访问令牌一同保存，并在你运行命令时自动续期，因此访问令牌过期后无需重新登录。若要更改授予的权限，或会话已被撤销，请重新登录。

如果不使用 --context，登录会替换 default 上下文中的凭据并选中该上下文。传入 --context <name> 可登录到指定名称的上下文，同时保持当前使用的上下文不变。

使用 API 令牌

若要改用 API 令牌进行身份验证，请在控制面板的 Applications & API 部分创建令牌。你可以参阅 DigitalOcean API 指南，了解如何生成令牌。

使用 auth init 命令进行身份验证。

doctl auth init

系统会提示你输入在 DigitalOcean 控制面板中生成的 DigitalOcean 访问令牌。

DigitalOcean access token: your_DO_token

输入令牌后，你会收到凭据已被接受的确认信息。如果令牌验证失败，请确认复制和粘贴无误。

Validating token: OK

这将创建必要的目录结构和配置文件，用于存储凭据。

登录多个 DigitalOcean 账户

doctl 支持同时登录多个 DigitalOcean 账户，并通过身份验证上下文轻松切换。

默认使用名为 default 的上下文。要创建新上下文，请运行 doctl auth login --context <new-context-name>，通过浏览器登录；也可以运行 doctl auth init --context <new-context-name>，然后按提示输入 API 令牌。你还可以通过 DIGITALOCEAN_CONTEXT 环境变量传入新上下文的名称。凭据会与新上下文关联，并且 doctl auth login 也会选中该上下文。

要使用非默认上下文，请将上下文名称传递给任意 doctl 命令。例如：

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

要设置新的默认上下文，请运行 doctl auth switch --context <new-context-name>。此命令会将当前上下文保存到配置文件中，并在未指定上下文时将其用于所有命令。要查看已有的上下文，请运行 doctl auth list；选中的上下文会标记为 (current)。

只有在使用 default 上下文时，才会识别 --access-token 标志或 DIGITALOCEAN_ACCESS_TOKEN 环境变量。否则，它们不会影响所使用的 API 访问令牌。如果默认上下文不是 default，但你想临时覆盖访问令牌，请使用 doctl --context default --access-token your_DO_token ...。

使用 default 上下文时，标志和环境变量的优先级高于配置文件中保存的令牌，并且只对你运行的命令生效：doctl 不会将它们写入文件。例外情况是 doctl auth init，它会保存经过验证的令牌，无论令牌来自何处，因为该命令的用途就是保存令牌。运行不带参数的 doctl，即可查看当前启用的账户，以及其令牌来自配置文件还是环境变量。

配置默认值

doctl 配置文件用于存储 API 访问令牌以及命令标志的默认值。如果你经常使用某些标志，可以更改其默认值，避免每次都输入。当你想更改用于 SSH 的用户名或端口时，这一功能就很有用。

在 OS X 上，doctl 会将配置保存为 ${HOME}/Library/Application Support/doctl/config.yaml。运行 doctl auth init 后，${HOME}/Library/Application Support/doctl/ 目录会自动创建。

在 Linux 上，如果设置了 ${XDG_CONFIG_HOME} 环境变量，doctl 会将配置保存为 ${XDG_CONFIG_HOME}/doctl/config.yaml；如果未设置，则保存为 ~/.config/doctl/config.yaml。在 Windows 上，配置文件位于 %APPDATA%\doctl\config.yaml。

首次通过 doctl 完成身份验证时会创建配置文件。该文件包含你的凭据，以及你选择设置的标志默认值。doctl 只会写入你要求保存的设置，因此要设置默认值，需要自行添加相应属性。属性格式为 category.command.sub-command.flag: value。例如，删除标签时 force 标志对应的属性为 tag.delete.force。

旧版 doctl 写入的配置文件包含大量预填充属性。这些属性仍然有效，且 doctl 不会修改它们；你可以删除任何未主动更改过的属性。

要更改使用 doctl 连接 Droplet 时默认的 SSH 用户，请添加 compute.ssh.ssh-user 属性，并将其设为所需的用户名。在此示例中，我们将其设为 sammy。

. . .
compute.ssh.ssh-user: sammy
. . .

保存并关闭文件。下次使用 doctl 时，设置的新默认值就会生效。在此示例中，这意味着下次登录 Droplet 时，将使用 sammy 用户进行 SSH 连接，而不是默认的 root 用户。

环境变量

除了使用 config.yaml 文件或程序参数指定配置外，也可以使用环境变量仅为当前会话覆盖值：

# Use instead of --context argument
DIGITALOCEAN_CONTEXT=my-context doctl auth list

# Use instead of --access-token argument
DIGITALOCEAN_ACCESS_TOKEN=my-do-token doctl

这些设置仅影响当前会话，doctl 不会将它们写入 config.yaml。doctl auth init 是个例外：它会保存通过验证的令牌，因此，运行时若设置了 DIGITALOCEAN_ACCESS_TOKEN，就会用环境变量中的令牌替换 default 上下文中保存的令牌。

不带参数运行 doctl 时，会简要显示版本和身份验证状态，并告知是否有更新版本可用：

Welcome to DigitalOcean
doctl is the command line interface for the DigitalOcean API.

  Version   1.146.0
  Account   ✔ [email protected]
  Team      Sharks
  Context   default

账户信息行反映了 API 对当前上下文令牌的反馈，因此可以区分可用令牌和已撤销令牌。如果无法连接到 API，令牌会被标记为未验证，而非被拒绝。如果令牌的作用范围限定为某个团队，则会显示 Team，因为同一登录账号可能属于多个团队。

版本检查每天最多联系 GitHub 一次，并且会在 CI 中自动跳过。在完成身份验证之前，doctl 完全不会发起网络请求。若要彻底关闭版本检查：

DOCTL_NO_UPDATE_CHECK=1 doctl

启用 Shell 自动补全

doctl 也支持自动补全。可以进行设置，让你在输入部分命令后按 TAB，自动补全命令的剩余部分。例如，启用自动补全后，输入 doctl comp<TAB><TAB> drop<TAB><TAB>，命令提示符中就会显示 doctl compute droplet。

注意： Windows 用户无法使用 Shell 自动补全。

启用自动补全的方法取决于你使用的操作系统。如果通过 Homebrew 安装了 doctl，自动补全会自动启用，但你可能需要配置本地环境才能使用。

doctl 可以通过 doctl completion your_shell_here 命令生成自动补全脚本。Shell 的有效参数为 Bash（bash）、ZSH（zsh）和 fish（fish）。默认情况下，脚本会输出到命令行。有关 completion 命令的更多用法示例，请使用 doctl completion --help。

Linux 自动补全

使用 completion 命令最常见的方式，是在本地配置文件中添加一行。在 ~/.profile 文件末尾添加以下内容：

source <(doctl completion your_shell_here)

如果使用 ZSH，请在 ~/.zshrc 文件中添加以下内容：

compdef _doctl doctl

然后刷新配置文件。

source ~/.profile

MacOS（bash）

macOS 用户需要安装 bash-completion 框架才能使用自动补全功能。

brew install bash-completion

安装完成后，在 .profile 或 .bashrc 文件中添加以下内容，以加载 bash_completion。

source $(brew --prefix)/etc/bash_completion

然后使用适用于 bash 配置文件的相应命令刷新配置文件。

source ~/.profile
source ~/.bashrc

MacOS（zsh）

在 ~/.zshrc 文件中添加以下内容：

autoload -U +X compinit; compinit

然后刷新配置文件。

卸载 doctl

使用包管理器

MacOS 卸载

使用 Homebrew 卸载 macOS 上所有当前和先前版本的 doctl formula：

brew uninstall -f doctl

若要彻底删除配置，还需删除以下目录：

rm -rf "$HOME/Library/Application Support/doctl"

示例

doctl 可与您的所有 DigitalOcean 资源交互。以下是一些常见用法示例。要了解更多可用功能，请参阅 DigitalOcean 社区网站上的完整教程。

• 列出您账户中的所有 Droplet：

doctl compute droplet list

• 创建 Droplet：

doctl compute droplet create <name> --region <region-slug> --image <image-slug> --size <size-slug>

• 为 Droplet 分配浮动 IP：

doctl compute floating-ip-action assign <ip-addr> <droplet-id>

• 为现有域名创建新的 A 记录：

doctl compute domain records create --record-type A --record-name www --record-data <ip-addr> <domain-name>

doctl 还简化了无需 API 端点的操作。例如，它允许您按名称通过 SSH 连接到 Droplet：

doctl compute ssh <droplet-name>

默认情况下，它会假设您使用的是 root 用户。如果您想以特定用户身份通过 SSH 连接，也可以这样做：

doctl compute ssh <user>@<droplet-name>

教程

• 如何使用官方 DigitalOcean 命令行客户端 Doctl
• 如何使用 Doctl 管理 DigitalOcean 负载均衡器
• 如何使用 Doctl 和 DigitalOcean 云防火墙保护 Web 服务器基础设施
• 如何使用 Doctl 管理 DigitalOcean 块存储