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 対応 OS
      • kubectl との併用
      • doctl compute ssh の使用
      • Docker との併用
    • Arch Linux
    • Fedora
    • Nix 対応 OS
  • Docker Hub
  • GitHub からリリースをダウンロードする
  • ベータ版リリースのインストール
  • Docker でビルドする
  • 開発版をソースからビルドする
  • 依存関係
• DigitalOcean での認証
  • ブラウザーでサインインする
  • API トークンを使用する
  • 複数の DigitalOcean アカウントにログインする
• デフォルト値の設定
  • 環境変数
• シェルの自動補完を有効にする
  • Linux の自動補完
  • MacOS
• doctl のアンインストール
  • パッケージマネージャーを使用する
    • MacOS でのアンインストール
• 例
• チュートリアル

doctl のインストール

パッケージマネージャーを使用する（推奨）

パッケージマネージャーを使うと、わずかなコマンドで doctl をインストールし、新しいバージョンに更新できます。 以下に記載した公式サポート対象に加え、コミュニティでは増え続ける複数のパッケージマネージャーを通じて doctl を配布しています。お使いのプラットフォームに対応した方法が見つかる可能性は高いでしょう。

MacOS

Homebrew を使って macOS に doctl をインストールします。

brew install doctl

doctl は MacPorts からも入手できます。このポートはコミュニティによって保守されているため、最新バージョンではない場合があります。

Snap 対応 OS

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 対応 OS

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 に追加できます。

ベータ版のインストール

新機能は、一般提供（GA）リリースに先立ってベータ版として提供され、早期に試せることがあります。ベータ版には vX.Y.Z-beta.N のタグが付けられ、リリース ページで**「プレリリース」**として公開されます。

注： 上記のパッケージマネージャー（Homebrew、Snap、dnf）でインストールされるのは最新の GA リリースのみです。ベータ版やプレビュー機能は含まれません。プレビュー機能を使用するには、以下のいずれかの方法でベータ版ビルドをインストールしてください。これは想定された動作であり、バグではありません。

go install でベータ版をインストールする（最速）

Go 環境を設定済みの場合、特定のベータタグを直接インストールするのが最速の方法です。リリース ページで最新の -beta タグを確認し、v<version>-beta.<n> の代わりに使用してください：

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

これにより、doctl バイナリが $(go env GOPATH)/bin に配置されます。このディレクトリに PATH が通っていることを確認してください。

ソースからベータ版をビルドする

Go 環境を設定済みの場合、ベータタグ（または機能ブランチ）から直接ビルドします：

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 からビルド済みベータ版をダウンロードする（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 タグと一致している必要があります。ベータ版ビルドには、まだ変更される可能性のある機能が含まれる場合があり、一般に 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 は vendoring を使用する Go モジュールを利用しています。

DigitalOcean の認証

doctl は、doctl auth login でブラウザーからサインインする方法と、doctl auth init で API トークンを貼り付ける方法の 2 通りで認証できます。どちらの場合も、認証情報は 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 トークンで認証するには、Control Panel の 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) と表示されます。

--access-token フラグまたは DIGITALOCEAN_ACCESS_TOKEN 環境変数が認識されるのは、default コンテキストが使用されている場合のみです。それ以外の場合、API アクセストークンの使用先には影響しません。別のコンテキストがデフォルトに設定されているときにアクセストークンを一時的に上書きするには、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 に保存します。${HOME}/Library/Application Support/doctl/ ディレクトリは、doctl auth init を実行すると作成されます。

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 にログインするときに、デフォルトの root ユーザーではなく sammy ユーザーで SSH 接続します。

環境変数

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 が表示されます。

リリースの確認では、1 日に最大 1 回 GitHub に接続し、CI では自動的にスキップされます。認証するまでは、doctl はネットワークリクエストを一切行いません。確認を完全に無効にするには、次のようにします。

DOCTL_NO_UPDATE_CHECK=1 doctl

シェルの自動補完を有効にする

doctl は自動補完にも対応しています。コマンドの一部を入力して TAB を押すと、残りのコマンドが自動的に補完されるように設定できます。たとえば、自動補完を有効にして doctl comp<TAB><TAB> drop<TAB><TAB> と入力すると、コマンドプロンプトに doctl compute droplet と表示されます。

注： Windows ユーザーはシェルの自動補完を利用できません。

自動補完を有効にする方法は、使用しているオペレーティングシステムによって異なります。doctl を Homebrew でインストールした場合、自動補完は自動的に有効になりますが、利用するにはローカル環境の設定が必要な場合があります。

doctl は doctl completion your_shell_here コマンドで自動補完スクリプトを生成できます。シェルの有効な引数は 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 でのアンインストール

macOS 上の doctl の現行バージョンと以前のすべてのバージョンをアンインストールするには、Homebrew を使用します。

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にFloating 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エンドポイントのない操作も簡単に実行できます。たとえば、名前を指定してDropletにSSH接続できます：

doctl compute ssh <droplet-name>

デフォルトでは、rootユーザーを使用するものとして動作します。特定のユーザーとしてSSH接続することもできます：

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

チュートリアル

• Doctlの使い方：DigitalOcean公式コマンドラインクライアント
• Doctlを使用してDigitalOcean Load Balancerを操作する方法
• Doctlを使用してDigitalOcean Cloud FirewallでWebサーバーインフラストラクチャを保護する方法
• Doctlを使用してDigitalOcean Block Storageを操作する方法