X

Step Up to Modern Cloud Development

  • December 1, 2017

Updates to Oracle Cloud Infrastructure CLI

Mike Ross
Senior Member of Technical Staff

We’ve been hard at work the last few months making updates to our command line interface for Oracle Cloud Infrastructure, and wanted to take a minute to share some of the new functionality! The full list of new features and services can be found in our changelog on GitHub, and below are a few core features we wanted to call out specifically:

Defaults

We know how tedious it can be to type out the same values again and again while using the CLI, so we have added the ability to specify default values for parameters. The example below shows a sample oci_cli_rc file which sets two defaults: one at a global level which will be applied to all operations with a --compartment-id parameter, and one for only ‘os’ (object storage) commands which will be applied to all ‘os’ commands with a --namespace parameter.

Content of ~/.oci/oci_cli_rc:

[DEFAULT]
# globally scoped default for all operations with a --compartment-id parameter
compartment-id= ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2…
# default for --namespace scoped specifically to Object Storage commands
os.namespace=mynamespace

Example commands that no longer need explicit parameters:

oci compute instance list # no --compartment-id needed
oci os bucket list  # no --compartment-id or --namespace needed

 

Command and parameter aliases

To help with specifying long command and parameter names, we have also added support for defining aliases. The example oci_cli_rc file below shows examples of defining aliases for commands and parameters:

Content of ~/.oci/oci_cli_rc:

[OCI_CLI_PARAM_ALIASES]
--ad=--availability-domain
-a=--availability-domain
--dn=--display-name

[OCI_CLI_COMMAND_ALIASES]
# This lets you use "ls" instead of "list" for any list command in the CLI (e.g. oci compute instance ls)
ls = list

# This lets you do "oci os object rm" rather than "oci os object delete"
rm = os.object.delete

Table output

JSON output is great for parsing but can be problematic when it comes to readability on the command line. To help with this we have added table output format which can be triggered for any operation by supplying --output table. This also makes it easier to use common tools like grep and awk on the CLI output to grab specific records from a table. See the section on JMESPath below to see how you can filter data to make your table output more concise.

Here is an example command and output:

oci iam region list --output table
+-----+--------------------+
| key | name              |
+-----+--------------------+
| FRA | eu-frankfurt-1 |
| IAD | us-ashburn-1    |
| PHX | us-phoenix-1   |
+-----+--------------------+

JMESPath queries

Often times a CLI operation will return more data than you are interested in. To help with filtering and querying data from CLI responses, we have added the --query option which allows running arbitrary JMESPath (http://jmespath.org/) queries on the CLI output before the data is returned.

For example, you may want to list all of the instances in your compartment but only want to see the display-name and lifecycle-state, you can do this with the following query:

# using the oci_cli_rc file from above so we don’t have to specify --compartment-id

oci compute instance list --query 'data[*].{"display-name":"display-name","lifecycle-state":"lifecycle-state"}'

This is especially convenient for use with table output so you can limit the output to a size that will fit in your terminal.

You can also define queries in your oci_cli_rc file and reference them by name so you don’t have to type out complex queries, for example:

Content of ~/.oci/oci_cli_rc:

[OCI_CLI_CANNED_QUERIES]
get_id_and_display_name_from_list=data[*].{id: id, "display-name": “display-name"}

Example command:

oci compute instance list -c $C --query query://get_id_and_display_name_from_list

To help getting started with some of these features we have added the command 'oci setup oci-cli-rc' to generate a sample oci_cli_rc file with examples of canned queries, defaults, and parameter / command aliases.

JSON Input made easier

We have made a number of improvements to how our CLI works with complex parameters that require JSON input:

Reading JSON parameters from a file:

For any parameter marked as a "COMPLEX TYPE" you can now specify the value to be read from a file using the "file://" prefix instead of needing to format a JSON string on the command line. For example:

oci iam policy create —statements file://statements.json

Generate JSON skeletons for single parameter

To help with specifying JSON input from a file we have added --generate-param-json-input to each command with complex parameters to enable generating a JSON template for a given input parameter. For example, if you are not sure of the format for the oci iam policy create --statements parameter you can issue the following command to generate a template:

oci iam policy create --generate-json-param-input statements

output:

[
  “string”,
  “string”
]

You can then fill out this template and specify it as the input to a create policy call like so:

oci iam policy create --statements file://statements.json

Generate JSON skeletons for full command input

We also support generating a JSON skeleton for the full command input. A common workflow with this parameter is to dump the full JSON skeleton to a file, edit the file with the input values you want, and then execute the command using that file as input. Here is an example:

# command to emit full JSON skeleton for command to a file input.json
oci os preauth-request create --generate-full-command-json-input > input.json
# view content of input.json and edit values
cat input.json
{
  "accessType": "ObjectRead|ObjectWrite|ObjectReadWrite|AnyObjectWrite",
  "bucketName": "string",
  "name": "string",
  "namespace": "string",
  "objectName": "string",
  "opcClientRequestId": "string",
  "timeExpires": "2017-01-01T00:00:00.000000+00:00"
}

# run create pre-authenticated request with the values specified from a file
oci os preauth-request create --from-json file://input.json

Windows auto-complete for power shell

We have now added tab completion for Windows PowerShell! Completion works on commands and parameters and can be enabled with the following command:

oci setup autocomplete

For more in-depth documentation on these features and more, check out our main CLI documentation page here.

Related content

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha

Recent Content

Oracle

Integrated Cloud Applications & Platform Services