Common CLI Behavior¶
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
- The value of the
- The contents of a
.doapifile 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 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.
Changed in version 0.2.0:
--multiple now also matches by ID, slug, & fingerprint
--unique and the warnings in its absence
All commands take the following options in addition to those listed in their individual documentation:
<token>as an OAuth token for authentication with the API; mutually exclusive with
Use the contents of
<file>(after stripping leading & trailing whitespace) as an OAuth token for authentication with the API; mutually exclusive with
<URL>as the base URL for all API requests; default value:
https://api.digitalocean.com(the official DigitalOcean API endpoint)
Show command usage and exit
The maximum number of seconds to wait when attempting to connect to or read from the remote endpoint; default value: no timeout
Show doapi version and exit
Note that these options (other than
--help) cannot be attached to
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-time, as described below:
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-timeis exceeded. If this action is not specified, the subcommand will exit immediately after initiating the actions.
How often to poll the server for the actions’ current statuses; default value: 2 seconds
Changed in version 0.2.0: Default value changed from 5 seconds to 2 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.
--waitis specified but this option is not, the subcommand will wait indefinitely.