doctl

package module
v1.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 1, 2018 License: Apache-2.0 Imports: 18 Imported by: 0

README

doctl Build Status GoDoc Go Report Card

doctl is a command line interface for the DigitalOcean API.

Usage:
  doctl [command]

Available Commands:
  account     account commands
  auth        auth commands
  completion  completion commands
  compute     compute commands
  version     show the current version

Flags:
  -t, --access-token string   API V2 Access Token
  -u, --api-url string        Override default API V2 endpoint
  -c, --config string         config file (default is $HOME/.config/doctl/config.yaml)
      --context string        authentication context name
  -h, --help                  help for doctl
  -o, --output string         output format [text|json] (default "text")
      --trace                 trace api access
  -v, --verbose               verbose output

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

Installing doctl

There are four ways to install doctl: using a package manager, downloading a GitHub release, building a development version from source, or building it with Docker.

Option 1 – Using a Package Manager (Preferred)

A package manager allows you to install and keep up with new doctl versions using only a few commands. Currently, doctl is available as part of Homebrew for macOS users and Snap for GNU/Linux users.

You can use Homebrew to install doctl on macOS with this command:

brew install doctl

You can use Snap on Snap-supported systems to install doctl with this command:

sudo snap install doctl
Arch Linux

Arch users not using snaps can install from the AUR.

Support for Windows package managers is on the way.

Option 2 — Downloading a Release from GitHub

Visit the Releases page for the doctl GitHub project, and find the appropriate archive for your operating system and architecture. You can download the archive from from your browser, or copy its URL and retrieve it to your home directory with wget or curl.

For example, with wget:

cd ~
wget https://github.com/digitalocean/doctl/releases/download/v1.10.0/doctl-1.10.0-linux-amd64.tar.gz

Or with curl:

cd ~
curl -OL https://github.com/digitalocean/doctl/releases/download/v1.10.0/doctl-1.10.0-linux-amd64.tar.gz

Extract the binary. On GNU/Linux or OS X systems, you can use tar.

tar xf ~/doctl-1.10.0-linux-amd64.tar.gz

Or download and extract with this oneliner:

curl -sL https://github.com/digitalocean/doctl/releases/download/v1.10.0/doctl-1.10.0-linux-amd64.tar.gz | tar -xzv

On Windows systems, you should be able to double-click the zip archive to extract the doctl executable.

Move the doctl binary to somewhere in your path. For example, on GNU/Linux and OS X systems:

sudo mv ~/doctl /usr/local/bin

Windows users can follow How to: Add Tool Locations to the PATH Environment Variable in order to add doctl to their PATH.

Option 3 — Building the Development Version from Source

If you have a Go environment configured, you can install the development version of doctl from the command line.

go get -u github.com/digitalocean/doctl/cmd/doctl

While the development version is a good way to take a peek at doctl's latest features before they get released, be aware that it may have bugs. Officially released versions will generally be more stable.

Option 4 — Building with Docker

If you have Docker configured, you can build a Docker image using doctl's Dockerfile and run doctl within a container.

docker build -t doctl .

Then you can run it within a container.

docker run --rm -e DIGITALOCEAN_ACCESS_TOKEN="your_DO_token" doctl any_doctl_command

Authenticating with DigitalOcean

In order to use doctl, you need to authenticate with DigitalOcean by providing an access token, which can be created from the Applications & API section of the Control Panel. You can learn how to generate a token by following the DigitalOcean API guide.

Docker users will have to use the DIGITALOCEAN_ACCESS_TOKEN environmental variable to authenticate, as explained in the Installation section of this document.

If you're not using Docker to run doctl, authenticate with the auth init command.

doctl auth init

You will be prompted to enter the DigitalOcean access token that you generated in the DigitalOcean control panel.

DigitalOcean access token: your_DO_token

After entering your token, you will receive confirmation that the credentials were accepted. If the token doesn't validate, make sure you copied and pasted it correctly.

Validating token: OK

This will create the necessary directory structure and configuration file to store your credentials.

Logging in to multiple DigitalOcean accounts

doctl allows you to log in to multiple DigitalOcean accounts at the same time and easily switch between them with the use of authentication contexts.

By default, a context named default is used. To create a new context, run doctl auth init --context new-context-name. You may also pass the new context's name using the DIGITALOCEAN_CONTEXT variable. You will be prompted for your API access token which will be associated with the new context.

To use a non-default context, pass the context name as described above to any doctl command. To set a new default context, run doctl auth switch. This command will save the current context to the config file and use it for all commands by default if a context is not specified.

The --access-token flag or DIGITALOCEAN_ACCESS_TOKEN variable are acknowledged only if the default context is used. Otherwise, they will have no effect on what API access token is used. To temporarily override the access token if a different context is set as default, use doctl --context default --access-token your_DO_token ....

Configuring Default Values

The doctl configuration file is used to store your API Access Token as well as the defaults for command flags. If you find yourself using certain flags frequently, you can change their default values to avoid typing them every time. This can be useful when, for example, you want to change the username or port used for SSH.

On OS X and Linux, doctl's configuration file can be found at ${XDG_CONFIG_HOME}/doctl/config.yaml if the ${XDG_CONFIG_HOME} environmental variable is set. Otherwise, the config will be written to ~/.config/doctl/config.yaml. For Windows users, the config will be available at %LOCALAPPDATA%/doctl/config/config.yaml.

The configuration file was automatically created and populated with default properties when you authenticated with doctl for the first time. The typical format for a property is category.command.sub-command.flag: value. For example, the property for the force flag with tag deletion is tag.delete.force.

To change the default SSH user used when connecting to a Droplet with doctl, look for the compute.ssh.ssh-user property and change the value after the colon. In this example, we changed it to the username sammy.

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

Save and close the file. The next time you use doctl, the new default values you set will be in effect. In this example, that means that it will SSH as the sammy user (instead of the default root user) next time you log into a Droplet.

Enabling Shell Auto-Completion

doctl also has auto-completion support. It can be set up so that if you partially type a command and then press TAB, the rest of the command is automatically filled in. For example, if you type doctl comp<TAB><TAB> drop<TAB><TAB> with auto-completion enabled, you'll see doctl compute droplet appear on your command prompt.

Note: Shell auto-completion is not available for Windows users.

How you enable auto-completion depends on which operating system you're using. If you installed doctl via Homebrew or Snap, auto-completion is activated automatically, though you may need to configure your local environment to enable it.

doctl can generate an auto-completion script with the doctl completion your_shell_here command. Valid arguments for the shell are Bash (bash) and ZSH (zsh). By default, the script will be printed to the command line output. For more usage examples for the completion command, use doctl completion --help.

Linux

The most common way to use the completion command is by adding a line to your local profile configuration. At the end of your ~/.profile file, add this line:

source <(doctl completion your_shell_here)

Then refresh your profile.

source ~/.profile
macOS

macOS users will have to install the bash-completion framework to use the auto-completion feature.

brew install bash-completion

After it's installed, load bash_completion by adding following line to your .profile or .bashrc/.zshrc file.

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

Examples

doctl is able to interact with all of your DigitalOcean resources. Below are a few common usage examples. To learn more about the features available, see the full tutorial on the DigitalOcean community site.

  • List all Droplets on your account:
doctl compute droplet list
  • Create a Droplet:
doctl compute droplet create <name> --region <region-slug> --image <image-slug> --size <size-slug>
  • Assign a Floating IP to a Droplet:
doctl compute floating-ip-action assign <ip-addr> <droplet-id>
  • Create a new A record for an existing domain:
doctl compute domain records create --record-type A --record-name www --record-data <ip-addr> <domain-name>

doctl also simplifies actions without an API endpoint. For instance, it allows you to SSH to your Droplet by name:

doctl compute ssh <droplet-name>

By default, it assumes you are using the root user. If you want to SSH as a specific user, you can do that as well:

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

Building and dependencies

doctl's dependencies are managed with dep. To add dependencies, use dep ensure -add github.com/foo/bar

More info

Documentation

Index

Constants

View Source 
const (
	// ArgAccessToken is the access token to be used for the operations
	ArgAccessToken = "access-token"
	// ArgContext is the name of the auth context to use
	ArgContext = "context"
	// ArgActionID is an action id argument.
	ArgActionID = "action-id"
	// ArgActionAfter is an action after argument.
	ArgActionAfter = "after"
	// ArgActionBefore is an action before argument.
	ArgActionBefore = "before"
	// ArgActionResourceType is an action resource type argument.
	ArgActionResourceType = "resource-type"
	// ArgActionRegion is an action region argument.
	ArgActionRegion = "region"
	// ArgActionStatus is an action status argument.
	ArgActionStatus = "status"
	// ArgActionType is an action type argument.
	ArgActionType = "action-type"
	// ArgCommandWait is a wait for a droplet to be created argument.
	ArgCommandWait = "wait"
	// ArgDropletID is a droplet id argument.
	ArgDropletID = "droplet-id"
	// ArgDropletIDs is a list of droplet IDs.
	ArgDropletIDs = "droplet-ids"
	// ArgKernelID is a ekrnel id argument.
	ArgKernelID = "kernel-id"
	// ArgImage is an image argument.
	ArgImage = "image"
	// ArgImageID is an image id argument.
	ArgImageID = "image-id"
	// ArgImagePublic is a public image argument.
	ArgImagePublic = "public"
	// ArgImageSlug is an image slug argment.
	ArgImageSlug = "image-slug"
	// ArgIPAddress is an IP address argument.
	ArgIPAddress = "ip-address"
	// ArgDropletName is a droplet name argument.
	ArgDropletName = "droplet-name"
	// ArgResizeDisk is a resize disk argument.
	ArgResizeDisk = "resize-disk"
	// ArgSnapshotName is a snapshot name arugment.
	ArgSnapshotName = "snapshot-name"
	// ArgSnapshotDesc is the description for volume snapshot.
	ArgSnapshotDesc = "snapshot-desc"
	// ArgResourceType is the resource type for snapshot.
	ArgResourceType = "resource"
	// ArgBackups is an enable backups argument.
	ArgBackups = "enable-backups"
	// ArgIPv6 is an enable IPv6 argument.
	ArgIPv6 = "enable-ipv6"
	// ArgPrivateNetworking is an enable private networking argument.
	ArgPrivateNetworking = "enable-private-networking"
	// ArgMonitoring is an enable monitoring argument.
	ArgMonitoring = "enable-monitoring"
	// ArgRecordData is a record data argument.
	ArgRecordData = "record-data"
	// ArgRecordID is a record id argument.
	ArgRecordID = "record-id"
	// ArgRecordName is a record name argument.
	ArgRecordName = "record-name"
	// ArgRecordPort is a record port argument.
	ArgRecordPort = "record-port"
	// ArgRecordPriority is a record priority argument.
	ArgRecordPriority = "record-priority"
	// ArgRecordType is a record type argument.
	ArgRecordType = "record-type"
	// ArgRecordTTL is a record ttl argument.
	ArgRecordTTL = "record-ttl"
	// ArgRecordWeight is a record weight argument.
	ArgRecordWeight = "record-weight"
	// ArgRecordFlags is a record flags argument.
	ArgRecordFlags = "record-flags"
	// ArgRecordTag is a record tag argument.
	ArgRecordTag = "record-tag"
	// ArgRegionSlug is a region slug argument.
	ArgRegionSlug = "region"
	// ArgSizeSlug is a size slug argument.
	ArgSizeSlug = "size"
	// ArgsSSHKeyPath is a ssh argument.
	ArgsSSHKeyPath = "ssh-key-path"
	// ArgSSHKeys is a ssh key argument.
	ArgSSHKeys = "ssh-keys"
	// ArgsSSHPort is a ssh argument.
	ArgsSSHPort = "ssh-port"
	// ArgsSSHAgentForwarding is a ssh argument.
	ArgsSSHAgentForwarding = "ssh-agent-forwarding"
	// ArgsSSHPrivateIP is a ssh argument.
	ArgsSSHPrivateIP = "ssh-private-ip"
	// ArgSSHCommand is a ssh argument.
	ArgSSHCommand = "ssh-command"
	// ArgUserData is a user data argument.
	ArgUserData = "user-data"
	// ArgUserDataFile is a user data file location argument.
	ArgUserDataFile = "user-data-file"
	// ArgImageName name is an image name argument.
	ArgImageName = "image-name"
	// ArgKey is a key argument.
	ArgKey = "key"
	// ArgKeyName is a key name argument.
	ArgKeyName = "key-name"
	// ArgKeyPublicKey is a public key argument.
	ArgKeyPublicKey = "public-key"
	// ArgKeyPublicKeyFile is a public key file argument.
	ArgKeyPublicKeyFile = "public-key-file"
	// ArgSSHUser is a SSH user argument.
	ArgSSHUser = "ssh-user"
	// ArgFormat is columns to include in output argment.
	ArgFormat = "format"
	// ArgNoHeader hides the output header.
	ArgNoHeader = "no-header"
	// ArgPollTime is how long before the next poll argument.
	ArgPollTime = "poll-timeout"
	// ArgTagName is a tag name
	ArgTagName = "tag-name"
	// ArgTagNames is a slice of possible tag names
	ArgTagNames = "tag-names"
	//ArgTemplate is template format
	ArgTemplate = "template"

	// ArgOutput is an output type argument.
	ArgOutput = "output"

	// ArgVolumeSize is the size of a volume.
	ArgVolumeSize = "size"
	// ArgVolumeDesc is the description of a volume.
	ArgVolumeDesc = "desc"
	// ArgVolumeRegion is the region of a volume.
	ArgVolumeRegion = "region"
	// ArgVolumeFilesystemType is the filesystem type for a volume.
	ArgVolumeFilesystemType = "fs-type"
	// ArgVolumeFilesystemLabel is the filesystem label for a volume.
	ArgVolumeFilesystemLabel = "fs-label"
	// ArgVolumeList is the IDs of many volumes.
	ArgVolumeList = "volumes"

	// ArgCDNTTL is a cdn ttl argument
	ArgCDNTTL = "ttl"
	// ArgCDNFiles is a cdn files argument
	ArgCDNFiles = "files"

	// ArgCertificateName is a name of the certificate.
	ArgCertificateName = "name"
	// ArgCertificateDNSNames is a list of DNS names.
	ArgCertificateDNSNames = "dns-names"
	// ArgPrivateKeyPath is a path to a private key for the certificate.
	ArgPrivateKeyPath = "private-key-path"
	// ArgLeafCertificatePath is a path to a certificate leaf.
	ArgLeafCertificatePath = "leaf-certificate-path"
	// ArgCertificateChainPath is a path to a certificate chain.
	ArgCertificateChainPath = "certificate-chain-path"
	// ArgCertificateType is a certificate type.
	ArgCertificateType = "type"

	// ArgLoadBalancerName is a name of the load balancer.
	ArgLoadBalancerName = "name"
	// ArgLoadBalancerAlgorithm is a load balancing algorithm.
	ArgLoadBalancerAlgorithm = "algorithm"
	// ArgRedirectHttptoHttps is a flag that indicates whether HTTP requests to the load balancer on port 80 should be redirected to HTTPS on port 443.
	ArgRedirectHttpToHttps = "redirect-http-to-https"
	// ArgStickySessions is a list of sticky sessions settings for the load balancer.
	ArgStickySessions = "sticky-sessions"
	// ArgHealthCheck is a list of health check settings for the load balancer.
	ArgHealthCheck = "health-check"
	// ArgForwardingRules is a list of forwarding rules for the load balancer.
	ArgForwardingRules = "forwarding-rules"

	// ArgFirewallName is a name of the firewall.
	ArgFirewallName = "name"
	// ArgInboundRules is a list of inbound rules for the firewall.
	ArgInboundRules = "inbound-rules"
	// ArgOutboundRules is a list of outbound rules for the firewall.
	ArgOutboundRules = "outbound-rules"

	// ArgForce forces confirmation on actions
	ArgForce = "force"
)
View Source 
const (
	// NSRoot is a configuration key that signifies this value is at the root.
	NSRoot = "doctl"

	// LatestReleaseURL is the latest release URL endpoint.
	LatestReleaseURL = "https://api.github.com/repos/digitalocean/doctl/releases/latest"
)
View Source 
const (
	// ArgShortForce forces confirmation on actions
	ArgShortForce = "f"
)

Variables

View Source 
var (
	// DoitConfig holds the app's current configuration.
	DoitConfig Config = &LiveConfig{}

	// DoitVersion is doit's version.
	DoitVersion = Version{
		Major: 1,
		Minor: 9,
		Patch: 0,
		Label: "dev",
	}

	// Build is doit's build tag.
	Build string

	// Major is doctl's major version.
	Major string

	// Minor is doctl's minor version.
	Minor string

	// Patch is doctl's patch version.
	Patch string

	// Label is doctl's label.
	Label string

	// TraceHTTP traces http connections.
	TraceHTTP bool
)

Functions

This section is empty.

Types

type Command added in v0.5.0 

type Command interface {
	Run(args ...string) ([]byte, error)
	Start(args ...string) error
	Stop() error
}

Command runs commands.

type Config 

type Config interface {
	GetGodoClient(trace bool, accessToken string) (*godo.Client, error)
	SSH(user, host, keyPath string, port int, opts ssh.Options) runner.Runner
	Set(ns, key string, val interface{})
	GetString(ns, key string) (string, error)
	GetBool(ns, key string) (bool, error)
	GetInt(ns, key string) (int, error)
	GetStringSlice(ns, key string) ([]string, error)
}

Config is an interface that represent doit's config.

type GithubLatestVersioner added in v1.0.0 

type GithubLatestVersioner struct{}

GithubLatestVersioner retrieves the latest version from Github.

func (*GithubLatestVersioner) LatestVersion added in v1.0.0 

func (glv *GithubLatestVersioner) LatestVersion() (string, error)

LatestVersion retrieves the latest version from Github or returns an error.

type LatestVersioner added in v1.0.0 

type LatestVersioner interface {
	LatestVersion() (string, error)
}

LatestVersioner an interface for detecting the latest version.

type LiveCommand added in v0.5.0 

type LiveCommand struct {
	// contains filtered or unexported fields
}

LiveCommand is a live implementation of Command.

func NewLiveCommand added in v0.5.0 

func NewLiveCommand(path string) *LiveCommand

NewLiveCommand creates a LiveCommand.

func (*LiveCommand) Run added in v0.5.0 

func (c *LiveCommand) Run(args ...string) ([]byte, error)

Run runs a LiveCommand with args and returns stdout and an error if there was one.

func (*LiveCommand) Start added in v0.5.0 

func (c *LiveCommand) Start(args ...string) error

Start runs a LiveCommand with args and starts it. This would most likely block, so you should call it in a goroutine.

func (*LiveCommand) Stop added in v0.5.0 

func (c *LiveCommand) Stop() error

Stop stops an existing LiveCommand.

type LiveConfig 

type LiveConfig struct {
	// contains filtered or unexported fields
}

LiveConfig is an implementation of Config for live values.

func (*LiveConfig) GetBool added in v0.5.0 

func (c *LiveConfig) GetBool(ns, key string) (bool, error)

GetBool returns a config value as a bool.

func (*LiveConfig) GetGodoClient added in v0.5.0 

func (c *LiveConfig) GetGodoClient(trace bool, accessToken string) (*godo.Client, error)

GetGodoClient returns a GodoClient.

func (*LiveConfig) GetInt added in v0.5.0 

func (c *LiveConfig) GetInt(ns, key string) (int, error)

GetInt returns a config value as an int.

func (*LiveConfig) GetString added in v0.5.0 

func (c *LiveConfig) GetString(ns, key string) (string, error)

GetString returns a config value as a string.

func (*LiveConfig) GetStringSlice added in v0.5.0 

func (c *LiveConfig) GetStringSlice(ns, key string) ([]string, error)

GetStringSlice returns a config value as a string slice.

func (*LiveConfig) SSH 

func (c *LiveConfig) SSH(user, host, keyPath string, port int, opts ssh.Options) runner.Runner

SSH creates a ssh connection to a host.

func (*LiveConfig) Set added in v0.5.0 

func (c *LiveConfig) Set(ns, key string, val interface{})

Set sets a config key.

type MissingArgsErr added in v0.5.0 

type MissingArgsErr struct {
	Command string
}

MissingArgsErr is an error returned when their are too few arguments for a command.

func NewMissingArgsErr added in v0.5.0 

func NewMissingArgsErr(cmd string) *MissingArgsErr

NewMissingArgsErr creates a MissingArgsErr instance.

func (*MissingArgsErr) Error added in v0.5.0 

func (e *MissingArgsErr) Error() string

type MockCommand added in v0.5.0 

type MockCommand struct {
	// contains filtered or unexported fields
}

MockCommand is a mock command implementation. It allows you simulate running an external command.

func NewMockCommand added in v0.5.0 

func NewMockCommand(path string) *MockCommand

NewMockCommand createsd a MockCommand.

func (*MockCommand) Run added in v0.5.0 

func (c *MockCommand) Run(args ...string) ([]byte, error)

Run simulates the running of a command.

func (*MockCommand) Start added in v0.5.0 

func (c *MockCommand) Start(args ...string) error

Start simulates starting a command.

func (*MockCommand) Stop added in v0.5.0 

func (c *MockCommand) Stop() error

Stop simulates stoping a command.

type MockRunner added in v0.5.0 

type MockRunner struct {
	Err error
}

MockRunner is an implemenation of Runner for mocking.

func (*MockRunner) Run added in v0.5.0 

func (tr *MockRunner) Run() error

Run mock runs things.

type Version added in v1.0.0 

type Version struct {
	Major, Minor, Patch int
	Name, Build, Label  string
}

Version is the version info for doit.

func (Version) Complete added in v1.0.0 

func (v Version) Complete(lv LatestVersioner) string

Complete is the complete version for doit.

func (Version) String added in v1.0.0 

func (v Version) String() string

Source Files

View all Source files

Directories

Path Synopsis
cmd
doctl
doctl-gen-doc
install-doctl
release-doctl
do
mocks
pkg
runner
runner/mocks
ssh
system
units
Package units provides helper function to parse and print size and time units in human-readable format.
 Package units provides helper function to parse and print size and time units in human-readable format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.