linode-cli
==========
The Linode Command Line Interface
.. image:: https://raw.githubusercontent.com/linode/linode-cli/main/demo.gif
Installation
------------
From pypi::
pip3 install linode-cli
From source::
git clone git@github.com:linode/linode-cli.git
cd linode-cli
make install
This will need to be repeated on each pull. For a build to succeed, see
`Building from Source`_ below.
.. _Building from Source: #building-from-source
Docker Hub
^^^^^^^^^^
The Linode CLI can also be downloaded and run using the image available on `Docker Hub`_.
.. _Docker Hub: https://hub.docker.com/r/linode/cli
Using a Linode API Token::
docker run --rm -it -e LINODE_CLI_TOKEN=$LINODE_TOKEN linode/cli:latest linodes list
Using an existing config file::
docker run --rm -it -v $HOME/.config/linode-cli:/home/cli/.config/linode-cli linode/cli:latest linodes list
Upgrading
---------
To upgrade to the latest version of the Linode CLI::
pip3 install linode-cli --upgrade
Community Distributions
-----------------------
The 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.
Homebrew
^^^^^^^^
Installation::
brew install linode-cli
Upgrading::
brew upgrade linode-cli
Usage
-----
The Linode CLI is invoked with the `linode-cli`. The CLI accepts two primary
arguments, *command* and *action*::
linode-cli <command> <action>
*command* is 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 --help
*action* is 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 `--help` for
that command::
linode-cli linodes --help
Some actions don't require any parameters, but many do. To see details on how
to invoke a specific action, use `--help` for that action::
linode-cli linodes create --help
The 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 Operations
^^^^^^^^^^^^^^^^^
List Linodes::
linode-cli linodes list
List Linodes in a Region::
linode-cli linodes list --region us-east
Make a Linode::
linode-cli linodes create --type g5-standard-2 --region us-east --image linode/debian9 --label cli-1 --root_pass
Make a Linode using Default Settings::
linode-cli linodes create --label cli-2 --root_pass
Reboot a Linode::
linode-cli linodes reboot 12345
View available Linode types::
linode-cli linodes types
View your Volumes::
linode-cli volumes list
View your Domains::
linode-cli domains list
View records for a single Domain::
linode-cli domains records-list 12345
View your user::
linode-cli profile view
Configuration
"""""""""""""
The 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 the ``configure`` command::
linode-cli configure
If 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
``--token`` flag to the configure command as shown::
linode-cli configure --token
When configuring multiple users using web-based configuration, you may need to
log out of cloud.linode.com before configuring a second user.
Specifying List Arguments
"""""""""""""""""""""""""
When 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 multiple ``tags``
you can execute the following::
linode-cli linodes create --region us-east --type g6-nanode-1 --tags tag1 --tags tag2
Specifying Nested Arguments
"""""""""""""""""""""""""""
When 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 of ``DROP``
and an outbound policy of ``ACCEPT``, you can execute the following::
linode-cli firewalls create --label example-firewall --rules.outbound_policy ACCEPT --rules.inbound_policy DROP
Suppressing Defaults
""""""""""""""""""""
If you configured default values for ``image``, ``authorized_users``, ``region``,
and Linode ``type``, they will be sent for all requests that accept them if you
do not specify a different value. If you want to send a request *without* these
arguments, you must invoke the CLI with the ``--no-defaults`` option.
For example, to create a Linode with no ``image`` after a default Image has been
configured, you would do this::
linode-cli linodes create --region us-east --type g5-standard-2 --no-defaults
Suppressing Warnings
""""""""""""""""""""
In 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-warnings``
flag to prevent them from being emitted.
Shell Completion
""""""""""""""""
To generate a completion file for a given shell type, use the ``completion`` command;
for example to generate completions for bash run::
linode-cli completion bash
The 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.
Use ``bashcompinit`` on zsh with the bash completions for support on zsh shells.
Environment Variables
"""""""""""""""""""""
If you prefer, you may store your token in an environment variable named
``LINODE_CLI_TOKEN`` instead of using the configuration file. Doing so allows you
to bypass the initial configuration, and subsequent calls to ``linode-cli configure``
will 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
the ``obj`` plugin that ships with the CLI. To do so, simply set
``LINODE_CLI_OBJ_ACCESS_KEY`` and ``LINODE_CLI_OBJ_SECRET_KEY`` to 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 URL
""""""""""""""""""""
In 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 Users
^^^^^^^^^^^^^^
If you use the Linode CLI to manage multiple Linode accounts, you may configure
additional users using the ``linode-cli configure`` command. The CLI will automatically
detect that a new user is being configured based on the token given.
Displaying Configured Users
"""""""""""""""""""""""""""
To see what users are configured, simply run the following::
linode-cli show-users
The user who is currently active will be indicated by an asterisk.
Changing the Active User
""""""""""""""""""""""""
You may change the active user for all requests as follows::
linode-cli set-user USERNAME
Subsequent 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-user`` argument to specify the username you wish to act as for that
command. This *will not* change the active user.
Removing Configured Users
"""""""""""""""""""""""""
To remove a user from you previously configured, run::
linode-cli remove-user USERNAME
Once a user is removed, they will need to be reconfigured if you wish to use the
CLI for them again.
Customizing Output
------------------
Changing Output Fields
^^^^^^^^^^^^^^^^^^^^^^
By 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 --all
Using `--all` will 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 Formatting
^^^^^^^^^^^^^^^^^
While 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 Output
"""""""""""""""""""""""
To get more machine-readable output, simply request it::
linode-cli linodes list --text
If 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 --text
JSON Output
"""""""""""
To get JSON output from the CLI, simple request it::
linode-cli linodes list --json --all
While the `--all` is 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 --all
Plugins
-------
The 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_NAME
Plugins 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 invoking ``linode-cli --help``.
To remove a previously registered plugin, use the following command::
linode-cli remove-plugin PLUGIN_NAME
This command accepts the name used to invoke the plugin in the CLI as it appears
in ``linode-cli --help``, which may not be the same as the module name used to
register it.
Developing Plugins
^^^^^^^^^^^^^^^^^^
For information on how To write your own Third Party Plugin, see the `Plugins documentation`_.
.. _Plugins documentation: https://github.com/linode/linode-cli/blob/main/linodecli/plugins/README.md
Building from Source
--------------------
In order to successfully build the CLI, your system will require the following:
* The ``make`` command
* ``python3``
* ``pip3`` (to install ``requirements.txt``)
Before attempting a build, install python dependencies like this::
make requirements
Once everything is set up, you can initiate a build like so::
make build
If desired, you may pass in ``SPEC=/path/to/openapi-spec`` when running ``build``
or ``install``. 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 install
Testing
-------
**WARNING!** 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.
Installation
^^^^^^^^^^^^
The CLI uses the Bash Automated Testing System (BATS) for testing. To install run the following:
**OSX users**::
brew install bats-core
**Installing Bats from source**
Check 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/local
Running the Tests
^^^^^^^^^^^^^^^^^
Running 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.sh
**Running Tests via Docker**
The openapi spec must first be saved to the base of the linode-cli project:
curl -o ./openapi.yaml https://www.linode.com/docs/api/openapi.yaml
Run the following command to build the tests container:
docker build -f Dockerfile-bats -t linode-cli-tests .
Run the following command to run the test
docker run -e TOKEN_1=$INSERT_YOUR_TOKEN_HERE -e TOKEN_2=$INSERT_YOUR_TOKEN_HERE --rm linode-cli-tests
Contributing
------------
This CLI is generated based on the OpenAPI specification for Linode's API. As
such, many changes are made directly to the spec.
Please follow the `Contributing Guidelines`_ when making a contribution.
.. _Contributing Guidelines: https://github.com/linode/linode-cli/blob/main/CONTRIBUTING.md
Specification Extensions
^^^^^^^^^^^^^^^^^^^^^^^^
In order to be more useful, the following `Specification Extensions`_ have been
added to Linode's OpenAPI spec:
+-----------------------------+-------------+-------------------------------------------------------------------------------------------+
|Attribute | Location | Purpose |
+-----------------------------+-------------+-------------------------------------------------------------------------------------------+
|x-linode-cli-action | method | The action name for operations under this path. If not present, operationId is used. |
+-----------------------------+-------------+-------------------------------------------------------------------------------------------+
|x-linode-cli-color | property | If 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-command | path | The command name for operations under this path. If not present, "default" is used. |
+-----------------------------+-------------+-------------------------------------------------------------------------------------------+
|x-linode-cli-display | property | If truthy, displays this as a column in output. If a number, determines the ordering |
| | | (left to right). |
+-----------------------------+-------------+-------------------------------------------------------------------------------------------+
|x-linode-cli-format | property | Overrides the "format" given in this property for the CLI only. Valid values are `file` |
| | | and `json`. |
+-----------------------------+-------------+-------------------------------------------------------------------------------------------+
|x-linode-cli-skip | path | If present and truthy, this method will not be available in the CLI. |
+-----------------------------+-------------+-------------------------------------------------------------------------------------------+
+x-linode-cli-allowed-defaults| requestBody | Tells the CLI what configured defaults apply to this request. Valid defaults are "region",|
+ | | "image", "authorized_users", and "type". |
+-----------------------------+-------------+-------------------------------------------------------------------------------------------+
+x-linode-cli-nested-list | content-type| Tells 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 ``_split`` is 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-schema | content-type| Overrides the normal schema for the object and uses this instead. Especially useful when |
| | | paired with ``x-linode-cli-nested-list``, allowing a schema to describe the flattened |
| | | object instead of the original object. |
+-----------------------------+-------------+-------------------------------------------------------------------------------------------+
.. _Specification Extensions: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#specificationExtensions
Raw data
{
"_id": null,
"home_page": "https://www.linode.com/docs/api/",
"name": "linode-cli-testrelease",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Linode",
"author_email": "developers@linode.com",
"download_url": "https://files.pythonhosted.org/packages/d2/81/3c62b00e0a0ec1191467b71d78c88949dbbfa35b16eeebd90b0763ecbc23/linode-cli-testrelease-5.24.0.tar.gz",
"platform": null,
"description": "linode-cli\n==========\n\nThe Linode Command Line Interface\n\n.. image:: https://raw.githubusercontent.com/linode/linode-cli/main/demo.gif\n\nInstallation\n------------\n\nFrom pypi::\n\n pip3 install linode-cli\n\nFrom source::\n\n git clone git@github.com:linode/linode-cli.git\n cd linode-cli\n make install\n\nThis will need to be repeated on each pull. For a build to succeed, see\n`Building from Source`_ below.\n\n.. _Building from Source: #building-from-source\n\nDocker Hub\n^^^^^^^^^^\n\nThe Linode CLI can also be downloaded and run using the image available on `Docker Hub`_.\n\n.. _Docker Hub: https://hub.docker.com/r/linode/cli\n\nUsing a Linode API Token::\n\n docker run --rm -it -e LINODE_CLI_TOKEN=$LINODE_TOKEN linode/cli:latest linodes list\n\nUsing an existing config file::\n\n docker run --rm -it -v $HOME/.config/linode-cli:/home/cli/.config/linode-cli linode/cli:latest linodes list\n\nUpgrading\n---------\n\nTo upgrade to the latest version of the Linode CLI::\n\n pip3 install linode-cli --upgrade\n\nCommunity Distributions\n-----------------------\n\nThe Linode CLI is also available through the following unofficial channels thanks\nto our awesome community! Please note that these distributions are not included\nin our release testing.\n\nHomebrew\n^^^^^^^^\n\nInstallation::\n\n brew install linode-cli\n\nUpgrading::\n\n brew upgrade linode-cli\n\nUsage\n-----\n\nThe Linode CLI is invoked with the `linode-cli`. The CLI accepts two primary\narguments, *command* and *action*::\n\n linode-cli <command> <action>\n\n*command* is the part of the CLI you are interacting with, for example \"linodes\".\nYou can see a list of all available commands by using `--help`::\n\n linode-cli --help\n\n*action* is the action you want to perform on a given command, for example \"list\".\nYou can see a list of all available actions for a command with the `--help` for\nthat command::\n\n linode-cli linodes --help\n\nSome actions don't require any parameters, but many do. To see details on how\nto invoke a specific action, use `--help` for that action::\n\n linode-cli linodes create --help\n\nThe first time you invoke the CLI, you will be asked to configure (see\n\"Configuration\" below for details), and optionally select some default values\nfor \"region,\" \"image,\" and \"type.\" If you configure these defaults, you may\nomit them as parameters to actions and the default value will be used.\n\nCommon Operations\n^^^^^^^^^^^^^^^^^\n\nList Linodes::\n\n linode-cli linodes list\n\nList Linodes in a Region::\n\n linode-cli linodes list --region us-east\n\nMake a Linode::\n\n linode-cli linodes create --type g5-standard-2 --region us-east --image linode/debian9 --label cli-1 --root_pass\n\nMake a Linode using Default Settings::\n\n linode-cli linodes create --label cli-2 --root_pass\n\nReboot a Linode::\n\n linode-cli linodes reboot 12345\n\nView available Linode types::\n\n linode-cli linodes types\n\nView your Volumes::\n\n linode-cli volumes list\n\nView your Domains::\n\n linode-cli domains list\n\nView records for a single Domain::\n\n linode-cli domains records-list 12345\n\nView your user::\n\n linode-cli profile view\n\nConfiguration\n\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nThe first time the CLI runs, it will prompt you to configure it. The CLI defaults\nto using web-based configuration, which is fast and convenient for users who\nhave access to a browser.\n\nTo manually configure the CLI or reconfigure it if your token expires, you can\nrun the ``configure`` command::\n\n linode-cli configure\n\nIf you prefer to provide a token directly through the terminal, possibly because\nyou don't have access to a browser where you're configuring the CLI, pass the\n``--token`` flag to the configure command as shown::\n\n linode-cli configure --token\n\nWhen configuring multiple users using web-based configuration, you may need to\nlog out of cloud.linode.com before configuring a second user.\n\nSpecifying List Arguments\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nWhen running certain commands, you may need to specify multiple values for a list\nargument. This can be done by specifying the argument multiple times for each\nvalue in the list. For example, to create a Linode with multiple ``tags``\nyou can execute the following::\n\n linode-cli linodes create --region us-east --type g6-nanode-1 --tags tag1 --tags tag2\n\nSpecifying Nested Arguments\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nWhen running certain commands, you may need to specify an argument that is nested\nin another field. These arguments can be specified using a ``.`` delimited path to\nthe argument. For example, to create a firewall with an inbound policy of ``DROP``\nand an outbound policy of ``ACCEPT``, you can execute the following::\n\n linode-cli firewalls create --label example-firewall --rules.outbound_policy ACCEPT --rules.inbound_policy DROP\n\nSuppressing Defaults\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nIf you configured default values for ``image``, ``authorized_users``, ``region``,\nand Linode ``type``, they will be sent for all requests that accept them if you\ndo not specify a different value. If you want to send a request *without* these\narguments, you must invoke the CLI with the ``--no-defaults`` option.\n\nFor example, to create a Linode with no ``image`` after a default Image has been\nconfigured, you would do this::\n\n linode-cli linodes create --region us-east --type g5-standard-2 --no-defaults\n\nSuppressing Warnings\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nIn some situations, like when the CLI is out of date, it will generate a warning\nin addition to its normal output. If these warnings can interfere with your\nscripts or you otherwise want them disabled, simply add the ``--suppress-warnings``\nflag to prevent them from being emitted.\n\nShell Completion\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nTo generate a completion file for a given shell type, use the ``completion`` command;\nfor example to generate completions for bash run::\n\n linode-cli completion bash\n\nThe output of this command is suitable to be included in the relevant completion\nfiles to enable command completion on your shell.\n\nThis command currently supports completions bash and fish shells.\n\nUse ``bashcompinit`` on zsh with the bash completions for support on zsh shells.\n\nEnvironment Variables\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nIf you prefer, you may store your token in an environment variable named\n``LINODE_CLI_TOKEN`` instead of using the configuration file. Doing so allows you\nto bypass the initial configuration, and subsequent calls to ``linode-cli configure``\nwill allow you to set defaults without having to set a token. Be aware that if\nthe environment variable should be unset, the Linode CLI will stop working until\nit is set again or the CLI is reconfigured with a token.\n\nYou may also use environment variables to store your Object Storage Keys for\nthe ``obj`` plugin that ships with the CLI. To do so, simply set\n``LINODE_CLI_OBJ_ACCESS_KEY`` and ``LINODE_CLI_OBJ_SECRET_KEY`` to the\nappropriate values. This allows using Linode Object Storage through the CLI\nwithout having a configuration file, which is desirable in some situations.\n\nConfigurable API URL\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nIn some cases you may want to run linode-cli against a non-default Linode API URL.\nThis can be done using the following environment variables to override certain segments of the target API URL.\n\n* ``LINODE_CLI_API_HOST`` - The host of the Linode API instance (e.g. ``api.linode.com``)\n\n* ``LINODE_CLI_API_VERSION`` - The Linode API version to use (e.g. ``v4beta``)\n\n* ``LINODE_CLI_API_SCHEME`` - The request scheme to use (e.g. ``https``)\n\nMultiple Users\n^^^^^^^^^^^^^^\n\nIf you use the Linode CLI to manage multiple Linode accounts, you may configure\nadditional users using the ``linode-cli configure`` command. The CLI will automatically\ndetect that a new user is being configured based on the token given.\n\nDisplaying Configured Users\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nTo see what users are configured, simply run the following::\n\n linode-cli show-users\n\nThe user who is currently active will be indicated by an asterisk.\n\nChanging the Active User\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nYou may change the active user for all requests as follows::\n\n linode-cli set-user USERNAME\n\nSubsequent CLI commands will be executed as that user by default.\n\nShould you wish to execute a single request as a different user, you can supply\nthe ``--as-user`` argument to specify the username you wish to act as for that\ncommand. This *will not* change the active user.\n\nRemoving Configured Users\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nTo remove a user from you previously configured, run::\n\n linode-cli remove-user USERNAME\n\nOnce a user is removed, they will need to be reconfigured if you wish to use the\nCLI for them again.\n\nCustomizing Output\n------------------\n\nChanging Output Fields\n^^^^^^^^^^^^^^^^^^^^^^\n\nBy default, the CLI displays on some pre-selected fields for a given type of\nresponse. If you want to see everything, just ask::\n\n linode-cli linodes list --all\n\nUsing `--all` will cause the CLI to display all returned columns of output.\nNote that this will probably be hard to read on normal-sized screens for most\nactions.\n\nIf you want even finer control over your output, you can request specific columns\nbe displayed::\n\n linode-cli linodes list --format 'id,region,status,disk,memory,vcpus,transfer'\n\nThis will show some identifying information about your Linode as well as the\nresources it has access to. Some of these fields would be hidden by default -\nthat's ok. If you ask for a field, it'll be displayed.\n\nOutput Formatting\n^^^^^^^^^^^^^^^^^\n\nWhile the CLI by default outputs human-readable tables of data, you can use the\nCLI to generate output that is easier to process.\n\nMachine Readable Output\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nTo get more machine-readable output, simply request it::\n\n linode-cli linodes list --text\n\nIf a tab is a bad delimiter, you can configure that as well::\n\n linode-cli linodes list --text --delimiter ';'\n\nYou may also disable header rows (in any output format)::\n\n linode-cli linodes list --no-headers --text\n\nJSON Output\n\"\"\"\"\"\"\"\"\"\"\"\n\nTo get JSON output from the CLI, simple request it::\n\n linode-cli linodes list --json --all\n\nWhile the `--all` is optional, you probably want to see all output fields in\nyour JSON output. If you want your JSON pretty-printed, we can do that too::\n\n linode-cli linodes list --json --pretty --all\n\nPlugins\n-------\n\nThe Linode CLI allows its features to be expanded with plugins. Some official\nplugins come bundled with the CLI and are documented above. Additionally, anyone\ncan write and distribute plugins for the CLI - these are called Third Party Plugins.\n\nTo register a Third Party Plugin, use the following command::\n\n linode-cli register-plugin PLUGIN_MODULE_NAME\n\nPlugins should give the exact command required to register them.\n\nOnce registered, the command to invoke the Third Party Plugin will be printed, and\nit will appear in the plugin list when invoking ``linode-cli --help``.\n\nTo remove a previously registered plugin, use the following command::\n\n linode-cli remove-plugin PLUGIN_NAME\n\nThis command accepts the name used to invoke the plugin in the CLI as it appears\nin ``linode-cli --help``, which may not be the same as the module name used to\nregister it.\n\nDeveloping Plugins\n^^^^^^^^^^^^^^^^^^\n\nFor information on how To write your own Third Party Plugin, see the `Plugins documentation`_.\n\n.. _Plugins documentation: https://github.com/linode/linode-cli/blob/main/linodecli/plugins/README.md\n\nBuilding from Source\n--------------------\n\nIn order to successfully build the CLI, your system will require the following:\n\n * The ``make`` command\n * ``python3``\n * ``pip3`` (to install ``requirements.txt``)\n\nBefore attempting a build, install python dependencies like this::\n\n make requirements\n\nOnce everything is set up, you can initiate a build like so::\n\n make build\n\nIf desired, you may pass in ``SPEC=/path/to/openapi-spec`` when running ``build``\nor ``install``. This can be a URL or a path to a local spec, and that spec will\nbe used when generating the CLI. A yaml or json file is accepted.\n\nTo install the package as part of the build process, use this command::\n\n make install\n\nTesting\n-------\n\n**WARNING!** Running the CLI tests will remove all linodes and data associated\nwith the account. It is only recommended to run these tests if you are an advanced\nuser.\n\nInstallation\n^^^^^^^^^^^^\n\nThe CLI uses the Bash Automated Testing System (BATS) for testing. To install run the following:\n\n**OSX users**::\n\n brew install bats-core\n\n**Installing Bats from source**\n\nCheck out a copy of the Bats repository. Then, either add the Bats bin directory to your\n$PATH, or run the provided install.sh command with the location to the prefix in which you\nwant to install Bats. For example, to install Bats into /usr/local::\n\n git clone https://github.com/bats-core/bats-core.git\n cd bats-core\n ./install.sh /usr/local\n\nRunning the Tests\n^^^^^^^^^^^^^^^^^\n\nRunning the tests is simple. The only requirements are that you have a .linode-cli in your user folder containing your test user token::\n\n ./test/test-runner.sh\n\n**Running Tests via Docker**\n\nThe openapi spec must first be saved to the base of the linode-cli project:\n\n curl -o ./openapi.yaml https://www.linode.com/docs/api/openapi.yaml\n\nRun the following command to build the tests container:\n\n docker build -f Dockerfile-bats -t linode-cli-tests .\n\nRun the following command to run the test\n\n docker run -e TOKEN_1=$INSERT_YOUR_TOKEN_HERE -e TOKEN_2=$INSERT_YOUR_TOKEN_HERE --rm linode-cli-tests\n\nContributing\n------------\n\nThis CLI is generated based on the OpenAPI specification for Linode's API. As\nsuch, many changes are made directly to the spec.\n\nPlease follow the `Contributing Guidelines`_ when making a contribution.\n\n.. _Contributing Guidelines: https://github.com/linode/linode-cli/blob/main/CONTRIBUTING.md\n\nSpecification Extensions\n^^^^^^^^^^^^^^^^^^^^^^^^\n\nIn order to be more useful, the following `Specification Extensions`_ have been\nadded to Linode's OpenAPI spec:\n\n+-----------------------------+-------------+-------------------------------------------------------------------------------------------+\n|Attribute | Location | Purpose |\n+-----------------------------+-------------+-------------------------------------------------------------------------------------------+\n|x-linode-cli-action | method | The action name for operations under this path. If not present, operationId is used. |\n+-----------------------------+-------------+-------------------------------------------------------------------------------------------+\n|x-linode-cli-color | property | If present, defines key-value pairs of property value: color. Colors must be one of |\n| | | \"red\", \"green\", \"yellow\", \"white\", and \"black\". Must include a default. |\n+-----------------------------+-------------+-------------------------------------------------------------------------------------------+\n|x-linode-cli-command | path | The command name for operations under this path. If not present, \"default\" is used. |\n+-----------------------------+-------------+-------------------------------------------------------------------------------------------+\n|x-linode-cli-display | property | If truthy, displays this as a column in output. If a number, determines the ordering |\n| | | (left to right). |\n+-----------------------------+-------------+-------------------------------------------------------------------------------------------+\n|x-linode-cli-format | property | Overrides the \"format\" given in this property for the CLI only. Valid values are `file` |\n| | | and `json`. |\n+-----------------------------+-------------+-------------------------------------------------------------------------------------------+\n|x-linode-cli-skip | path | If present and truthy, this method will not be available in the CLI. |\n+-----------------------------+-------------+-------------------------------------------------------------------------------------------+\n+x-linode-cli-allowed-defaults| requestBody | Tells the CLI what configured defaults apply to this request. Valid defaults are \"region\",|\n+ | | \"image\", \"authorized_users\", and \"type\". |\n+-----------------------------+-------------+-------------------------------------------------------------------------------------------+\n+x-linode-cli-nested-list | content-type| Tells the CLI to flatten a single object into multiple table rows based on the keys |\n| | | included in this value. Values should be comma-delimited JSON paths, and must all be |\n| | | present on response objects. |\n| | | |\n| | | When used, a new key ``_split`` is added to each flattened object whose value is the last |\n| | | segment of the JSON path used to generate the flattened object from the source. |\n+-----------------------------+-------------+-------------------------------------------------------------------------------------------+\n|x-linode-cli-use-schema | content-type| Overrides the normal schema for the object and uses this instead. Especially useful when |\n| | | paired with ``x-linode-cli-nested-list``, allowing a schema to describe the flattened |\n| | | object instead of the original object. |\n+-----------------------------+-------------+-------------------------------------------------------------------------------------------+\n\n.. _Specification Extensions: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#specificationExtensions\n\n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "CLI for the Linode API",
"version": "5.24.0",
"project_urls": {
"Homepage": "https://www.linode.com/docs/api/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a781e21a2af430d043a183fbc6a55c77530ae44d6334c238c08b8a7b195f4e98",
"md5": "0b59a85df9fa2ddda8a94c8035b94125",
"sha256": "f4680363f0592886fb59ba3028a9c2f25ef910dda980b03122b14954b33ccd21"
},
"downloads": -1,
"filename": "linode_cli_testrelease-5.24.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b59a85df9fa2ddda8a94c8035b94125",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 103388,
"upload_time": "2023-03-21T15:46:56",
"upload_time_iso_8601": "2023-03-21T15:46:56.889406Z",
"url": "https://files.pythonhosted.org/packages/a7/81/e21a2af430d043a183fbc6a55c77530ae44d6334c238c08b8a7b195f4e98/linode_cli_testrelease-5.24.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d2813c62b00e0a0ec1191467b71d78c88949dbbfa35b16eeebd90b0763ecbc23",
"md5": "725b2e5ba51d6e90f2d8ee0e12795a43",
"sha256": "ef772f88e2ae8f5f07a8163ae359e66298e486126ce2df9604fff3038e5274c2"
},
"downloads": -1,
"filename": "linode-cli-testrelease-5.24.0.tar.gz",
"has_sig": false,
"md5_digest": "725b2e5ba51d6e90f2d8ee0e12795a43",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 100665,
"upload_time": "2023-03-21T15:46:59",
"upload_time_iso_8601": "2023-03-21T15:46:59.266638Z",
"url": "https://files.pythonhosted.org/packages/d2/81/3c62b00e0a0ec1191467b71d78c88949dbbfa35b16eeebd90b0763ecbc23/linode-cli-testrelease-5.24.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-21 15:46:59",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "linode-cli-testrelease"
}
JSON