Package: linode-cli-testrelease
The Linode Command Line InterfaceInstallationFrom pypi:pip3 install linode-cliFrom source:git clone git@github.com:linode/linode-cli.git
cd linode-cli
make installThis will need to be repeated on each pull.  For a build to succeed, seeBuilding from Sourcebelow.Docker HubThe Linode CLI can also be downloaded and run using the image available onDocker Hub.Using a Linode API Token:docker run --rm -it -e LINODE_CLI_TOKEN=$LINODE_TOKEN linode/cli:latest linodes listUsing an existing config file:docker run --rm -it -v $HOME/.config/linode-cli:/home/cli/.config/linode-cli linode/cli:latest linodes listUpgradingTo upgrade to the latest version of the Linode CLI:pip3 install linode-cli --upgradeCommunity DistributionsThe Linode CLI is also available through the following unofficial channels thanks
to our awesome community!  Please note that these distributions are not included
in our release testing.HomebrewInstallation:brew install linode-cliUpgrading:brew upgrade linode-cliUsageThe Linode CLI is invoked with thelinode-cli.  The CLI accepts two primary
arguments,commandandaction:linode-cli <command> <action>commandis the part of the CLI you are interacting with, for example “linodes”.
You can see a list of all available commands by using–help:linode-cli --helpactionis the action you want to perform on a given command, for example “list”.
You can see a list of all available actions for a command with the–helpfor
that command:linode-cli linodes --helpSome actions don’t require any parameters, but many do.  To see details on how
to invoke a specific action, use–helpfor that action:linode-cli linodes create --helpThe first time you invoke the CLI, you will be asked to configure (see
“Configuration” below for details), and optionally select some default values
for “region,” “image,” and “type.” If you configure these defaults, you may
omit them as parameters to actions and the default value will be used.Common OperationsList Linodes:linode-cli linodes listList Linodes in a Region:linode-cli linodes list --region us-eastMake a Linode:linode-cli linodes create --type g5-standard-2 --region us-east --image linode/debian9 --label cli-1 --root_passMake a Linode using Default Settings:linode-cli linodes create --label cli-2 --root_passReboot a Linode:linode-cli linodes reboot 12345View available Linode types:linode-cli linodes typesView your Volumes:linode-cli volumes listView your Domains:linode-cli domains listView records for a single Domain:linode-cli domains records-list 12345View your user:linode-cli profile viewConfigurationThe first time the CLI runs, it will prompt you to configure it.  The CLI defaults
to using web-based configuration, which is fast and convenient for users who
have access to a browser.To manually configure the CLI or reconfigure it if your token expires, you can
run theconfigurecommand:linode-cli configureIf you prefer to provide a token directly through the terminal, possibly because
you don’t have access to a browser where you’re configuring the CLI, pass the--tokenflag to the configure command as shown:linode-cli configure --tokenWhen configuring multiple users using web-based configuration, you may need to
log out of cloud.linode.com before configuring a second user.Specifying List ArgumentsWhen running certain commands, you may need to specify multiple values for a list
argument. This can be done by specifying the argument multiple times for each
value in the list. For example, to create a Linode with multipletagsyou can execute the following:linode-cli linodes create --region us-east --type g6-nanode-1 --tags tag1 --tags tag2Specifying Nested ArgumentsWhen running certain commands, you may need to specify an argument that is nested
in another field. These arguments can be specified using a.delimited path to
the argument. For example, to create a firewall with an inbound policy ofDROPand an outbound policy ofACCEPT, you can execute the following:linode-cli firewalls create --label example-firewall --rules.outbound_policy ACCEPT --rules.inbound_policy DROPSuppressing DefaultsIf you configured default values forimage,authorized_users,region,
and Linodetype, they will be sent for all requests that accept them if you
do not specify a different value.  If you want to send a requestwithoutthese
arguments, you must invoke the CLI with the--no-defaultsoption.For example, to create a Linode with noimageafter a default Image has been
configured, you would do this:linode-cli linodes create --region us-east --type g5-standard-2 --no-defaultsSuppressing WarningsIn some situations, like when the CLI is out of date, it will generate a warning
in addition to its normal output.  If these warnings can interfere with your
scripts or you otherwise want them disabled, simply add the--suppress-warningsflag to prevent them from being emitted.Shell CompletionTo generate a completion file for a given shell type, use thecompletioncommand;
for example to generate completions for bash run:linode-cli completion bashThe output of this command is suitable to be included in the relevant completion
files to enable command completion on your shell.This command currently supports completions bash and fish shells.Usebashcompiniton zsh with the bash completions for support on zsh shells.Environment VariablesIf you prefer, you may store your token in an environment variable namedLINODE_CLI_TOKENinstead of using the configuration file.  Doing so allows you
to bypass the initial configuration, and subsequent calls tolinode-cliconfigurewill allow you to set defaults without having to set a token.  Be aware that if
the environment variable should be unset, the Linode CLI will stop working until
it is set again or the CLI is reconfigured with a token.You may also use environment variables to store your Object Storage Keys for
theobjplugin that ships with the CLI.  To do so, simply setLINODE_CLI_OBJ_ACCESS_KEYandLINODE_CLI_OBJ_SECRET_KEYto the
appropriate values.  This allows using Linode Object Storage through the CLI
without having a configuration file, which is desirable in some situations.Configurable API URLIn some cases you may want to run linode-cli against a non-default Linode API URL.
This can be done using the following environment variables to override certain segments of the target API URL.LINODE_CLI_API_HOST- The host of the Linode API instance (e.g.api.linode.com)LINODE_CLI_API_VERSION- The Linode API version to use (e.g.v4beta)LINODE_CLI_API_SCHEME- The request scheme to use (e.g.https)Multiple UsersIf you use the Linode CLI to manage multiple Linode accounts, you may configure
additional users using thelinode-cliconfigurecommand.  The CLI will automatically
detect that a new user is being configured based on the token given.Displaying Configured UsersTo see what users are configured, simply run the following:linode-cli show-usersThe user who is currently active will be indicated by an asterisk.Changing the Active UserYou may change the active user for all requests as follows:linode-cli set-user USERNAMESubsequent CLI commands will be executed as that user by default.Should you wish to execute a single request as a different user, you can supply
the--as-userargument to specify the username you wish to act as for that
command.  Thiswill notchange the active user.Removing Configured UsersTo remove a user from you previously configured, run:linode-cli remove-user USERNAMEOnce a user is removed, they will need to be reconfigured if you wish to use the
CLI for them again.Customizing OutputChanging Output FieldsBy default, the CLI displays on some pre-selected fields for a given type of
response.  If you want to see everything, just ask:linode-cli linodes list --allUsing–allwill cause the CLI to display all returned columns of output.
Note that this will probably be hard to read on normal-sized screens for most
actions.If you want even finer control over your output, you can request specific columns
be displayed:linode-cli linodes list --format 'id,region,status,disk,memory,vcpus,transfer'This will show some identifying information about your Linode as well as the
resources it has access to.  Some of these fields would be hidden by default -
that’s ok.  If you ask for a field, it’ll be displayed.Output FormattingWhile the CLI by default outputs human-readable tables of data, you can use the
CLI to generate output that is easier to process.Machine Readable OutputTo get more machine-readable output, simply request it:linode-cli linodes list --textIf a tab is a bad delimiter, you can configure that as well:linode-cli linodes list --text --delimiter ';'You may also disable header rows (in any output format):linode-cli linodes list --no-headers --textJSON OutputTo get JSON output from the CLI, simple request it:linode-cli linodes list --json --allWhile the–allis optional, you probably want to see all output fields in
your JSON output.  If you want your JSON pretty-printed, we can do that too:linode-cli linodes list --json --pretty --allPluginsThe Linode CLI allows its features to be expanded with plugins.  Some official
plugins come bundled with the CLI and are documented above.  Additionally, anyone
can write and distribute plugins for the CLI - these are called Third Party Plugins.To register a Third Party Plugin, use the following command:linode-cli register-plugin PLUGIN_MODULE_NAMEPlugins should give the exact command required to register them.Once registered, the command to invoke the Third Party Plugin will be printed, and
it will appear in the plugin list when invokinglinode-cli--help.To remove a previously registered plugin, use the following command:linode-cli remove-plugin PLUGIN_NAMEThis command accepts the name used to invoke the plugin in the CLI as it appears
inlinode-cli--help, which may not be the same as the module name used to
register it.Developing PluginsFor information on how To write your own Third Party Plugin, see thePlugins documentation.Building from SourceIn order to successfully build the CLI, your system will require the following:Themakecommandpython3pip3(to installrequirements.txt)Before attempting a build, install python dependencies like this:make requirementsOnce everything is set up, you can initiate a build like so:make buildIf desired, you may pass inSPEC=/path/to/openapi-specwhen runningbuildorinstall.  This can be a URL or a path to a local spec, and that spec will
be used when generating the CLI.  A yaml or json file is accepted.To install the package as part of the build process, use this command:make installTestingWARNING!Running the CLI tests will remove all linodes and data associated
with the account. It is only recommended to run these tests if you are an advanced
user.InstallationThe CLI uses the Bash Automated Testing System (BATS) for testing. To install run the following:OSX users:brew install bats-coreInstalling Bats from sourceCheck out a copy of the Bats repository. Then, either add the Bats bin directory to your
$PATH, or run the provided install.sh command with the location to the prefix in which you
want to install Bats. For example, to install Bats into /usr/local:git clone https://github.com/bats-core/bats-core.git
cd bats-core
./install.sh /usr/localRunning the TestsRunning the tests is simple. The only requirements are that you have a .linode-cli in your user folder containing your test user token:./test/test-runner.shRunning Tests via DockerThe openapi spec must first be saved to the base of the linode-cli project:curl -o ./openapi.yamlhttps://www.linode.com/docs/api/openapi.yamlRun the following command to build the tests container:docker build -f Dockerfile-bats -t linode-cli-tests .Run the following command to run the testdocker run -e TOKEN_1=$INSERT_YOUR_TOKEN_HERE -e TOKEN_2=$INSERT_YOUR_TOKEN_HERE –rm linode-cli-testsContributingThis CLI is generated based on the OpenAPI specification for Linode’s API.  As
such, many changes are made directly to the spec.Please follow theContributing Guidelineswhen making a contribution.Specification ExtensionsIn order to be more useful, the followingSpecification Extensionshave been
added to Linode’s OpenAPI spec:AttributeLocationPurposex-linode-cli-actionmethodThe action name for operations under this path. If not present, operationId is used.x-linode-cli-colorpropertyIf present, defines key-value pairs of property value: color.  Colors must be one of
“red”, “green”, “yellow”, “white”, and “black”.  Must include a default.x-linode-cli-commandpathThe command name for operations under this path. If not present, “default” is used.x-linode-cli-displaypropertyIf truthy, displays this as a column in output.  If a number, determines the ordering
(left to right).x-linode-cli-formatpropertyOverrides the “format” given in this property for the CLI only.  Valid values arefileandjson.x-linode-cli-skippathIf present and truthy, this method will not be available in the CLI.x-linode-cli-allowed-defaultsrequestBodyTells the CLI what configured defaults apply to this request. Valid defaults are “region”,
“image”, “authorized_users”, and “type”.x-linode-cli-nested-listcontent-typeTells the CLI to flatten a single object into multiple table rows based on the keys
included in this value.  Values should be comma-delimited JSON paths, and must all be
present on response objects.When used, a new key_splitis added to each flattened object whose value is the last
segment of the JSON path used to generate the flattened object from the source.x-linode-cli-use-schemacontent-typeOverrides the normal schema for the object and uses this instead.  Especially useful when
paired withx-linode-cli-nested-list, allowing a schema to describe the flattened
object instead of the original object.