doapi
Document the plain doapi
command
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
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 default 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 there is not exactly one object with that name,doapi
will exit without taking any action; if the name is shared by multiple objects, the error message will include all of the objects' ID numbers.
For subcommands that operate on lists of objects, this behavior can be changed by passing the --multiple
option to the subcommand, causing any identifier shared by multiple objects of the relevant type (whether as ID, slug, fingerprint, and/or name) 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.
0.2.0 --multiple
now also matches by ID, slug, & fingerprint
Mention --unique and the warnings in its absence
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>
(after stripping leading & trailing whitespace) 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!
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:
-w, --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: 2 seconds
0.2.0 Default value changed from 5 seconds to 2 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.