Command-Line Programs¶
Todo
Document the plain doapi command
Common CLI Behavior¶
API Authentication¶
In order to perform API requests, an OAuth token must be supplied to doapi so that it can authenticate with the DigitalOcean server. You can generate an OAuth token for your account via the “Apps & API” section of your DigitalOcean account’s control panel.
The doapi commands will look for an OAuth token in the following locations, in order:
- Specified on the command line with
--api-token token
or--api-token-file file
- The value of the
DO_API_TOKEN
environment variable - The contents of a
.doapi
file in your home directory
Handling Non-Uniqueness of Identifiers¶
Most resources in the API are referred to by only a single identifier each, but droplets, images, and SSH keys can be referred to by either a unique ID number, a unique slug (for certain images), a unique fingerprint (for SSH keys), or a (potentially) non-unique name.
When the user specifies an object identifier that could be an ID, slug, fingerprint, or name, the order of resolution is as follows:
- If the identifier is an integer and there is an object of the relevant type with that integer as its ID number, doapi uses that object.
- For images, if there is an image whose slug equals the identifier, doapi uses that image.
- For SSH keys, if the identifier is in the form of an SSH public key fingerprint (16 colon-separated two-digit hexadecimal integers) and there is an SSH key with that fingerprint registered with the user’s DigitalOcean account, doapi uses that SSH key.
- Otherwise, the identifier is assumed to be a name, and if there exists
exactly one object of the relevant type with that name, doapi
uses that object. If the name is shared by multiple objects, by default
doapi will exit without taking any action, displaying an error
message that includes the ID numbers of all of the objects with that name.
For subcommands that operate on lists of objects, this behavior can be
changed by passing the
--multiple
option to the subcommand, causing any names that refer to more than one object to be interpreted as a list of all of those objects in unspecified order.
In all cases, if the same object is specified more than once on the command line, all occurrences after the first are ignored with a warning.
Universal Options¶
All commands take the following options in addition to those listed in their individual documentation:
-
--api-token
<token>
¶ Use
<token>
as an OAuth token for authentication with the API; mutually exclusive with--api-token-file
-
--api-token-file
<file>
¶ Use the contents of
<file>
as an OAuth token for authentication with the API; mutually exclusive with--api-token
-
--endpoint
<URL>
¶ Use
<URL>
as the base URL for all API requests; default value:https://api.digitalocean.com
(the official DigitalOcean API endpoint)
-
--help
¶
Show command usage and exit
-
--timeout
<seconds>
¶ The maximum number of seconds to wait when attempting to connect to or read from the remote endpoint; default value: no timeout
-
--version
¶
Show doapi version and exit
Note that these options (other than --help
) cannot be attached to
subcommands:
doapi-droplet --timeout 1000 show # Good
doapi --timeout 1000 droplet show # Good
doapi-droplet show --timeout 1000 # Bad!
Waiting Options¶
By default, all subcommands that perform non-atomic actions return immediately
after initiating the action, without waiting for it to complete. They can be
made to instead wait until completion with the --wait
option, which
can be configured further with --wait-interval
and
--wait-time
, as described below:
-
--wait
¶
Periodically poll the server for the current status of all actions until they all complete or error out or until the time limit specified by
--wait-time
is exceeded. If this action is not specified, the subcommand will exit immediately after initiating the actions.
-
--wait-interval
<seconds>
¶ How often to poll the server for the actions’ current statuses; default value: 5 seconds
-
--wait-time
<seconds>
¶ The maximum number of seconds to wait for all actions to complete. After this much time has passed since program invocation, any remaining in-progress actions will be output immediately without waiting for them to finish.
If
--wait
is specified but this option is not, the subcommand will wait indefinitely.