Configuring the CLI

This topic describes the required configuration for the CLI and includes optional configurations that enable you to extend CLI functionality. This topic assumes that you installed the CLI and are ready to configure it for your environment.

Setting up the Config File

Before using the CLI, you have to create a config file that contains the required credentials for working with Oracle Cloud Infrastructure. You can create this file using a setup dialog or manually, using a text editor.

Use the Setup Dialog

To have the CLI walk you through the first-time setup process, step by step, use the oci setup config command. The command prompts you for the information required for the config file and the API public/private keys. The setup dialog generates an API key pair and creates the config file.

Manual Setup

If you want to set up the API public/private keys yourself, and write your own config file, see SDK and Tool Configuration.

Use the oci setup keys command to generate a key pair to include in the config file.

Using a File for CLI Configurations

The CLI supports using a file for CLI-specific configurations. You can:

  • Specify a default profile.
  • Set default values for command options so you don't have to type them into the command line.
  • Define aliases for commands. For example, using "ls" as an alias for list.
  • Define aliases for options. For example, using "--ad" as an alias for --availability-domain.
  • Define named queries that are passed to the --query option instead of typing a JMESPath expression on the command line.

The default location and file name is ~/.oci/oci_cli_rc. You can also explicitly specify this file with the --cli-rc-file option or by with the legacy --defaults-file option. For example:

# Uses the file from ~/.oci/oci_cli_rc
oci os bucket list
			
# Uses a custom file
oci os bucket list --cli-rc-file path/to/my/cli/rc/file

Setting up an oci-cli-rc File

To set up an oci-cli-rc file, run the following command.


oci setup oci-cli-rc --file path/to/target/file

The preceding command creates the file you specify that includes examples of default command aliases, parameter aliases, and named queries.

Specifying a Default Profile

Specify a default profile in the OCI_CLI_SETTINGS section of the CLI configuration file. The next example shows how to specify a default profile named IAD. The CLI looks for a profile named IAD in your ~/.oci/config file, or any other file that you specify using the --config-file option.

[OCI_CLI_SETTINGS]
default_profile=IAD

You can also specify a default value for the --profile option using the OCI_CLI_PROFILE environment variable.

If a default profile value has been specified in multiple locations, the order of precedence is:

  1. The value specified in the --profile option.
  2. The value specified in the OCI_CLI_PROFILE environment variable.
  3. The value specified in the default_profile field in the OCI_CLI_SETTINGS section of the CLI configuration file.

Specifying Default Values

The CLI supports using a default values file so that you don't have to keep typing them into the command line. For example, instead of typing in a --compartment-id on each launch instance command or having to keep specifying the --namespace when using Object Storage commands. You can put this information in a default values file.

Default values can be applied at different levels, from general to specific:

  • Globally, across all the CLI commands.
  • To a particular service, such as Compute or Object Storage.
  • To a specific group, such as commands related to exporting images.
  • To a specific command.

Default values are treated hierarchically, with specific values having a higher order of precedence than general values. For example, if there is a globally defined value for compartment-id and a specific compartment-id defined for the compute instance launch command, the CLI uses the value for the compute instance launch instead of the global default.

Default Values File Name and Location

When you start the CLI, the program looks for the default values file in ~/.oci/oci_cli_rc. You can also specify a different file and location by using the --cli-rc-file option, as illustrated by the following:

# Uses the default values file from ~/.oci/oci_cli_rc
oci os bucket list
					
# Uses a custom default values file
oci os bucket list --cli-rc-file path/to/my/cli/custom-oci-cli-rc-file

Command Value Priority

If a value is provided on the command line also exists in --cli-rc-file, the value from the command line has priority. For a command with options that take multiple values, the values are taken entirely from the command line or from --cli-rc-file. The 2 sources aren't merged.

Defaults Value File Syntax

The --cli-rc-file file can be divided into different sections with one or more keys per section.

Sections

In the next example, the file has two sections, with a key in each section. To specify which section to use, you use the --profile option in the CLI.

[DEFAULT]
compartment-id = ocid1.compartment.oc1..aaaaaaaal5zx25nzpgeyqd3gzijdlg3ieqeyrggnx7il26astxxhqoljnhwa
[ANOTHER_SECTION]
compartment-id = ocid1.compartment.oc1..aaaaaaaal3gzieyqdrggnx7xil26astxxhqol2pgjjdlieqeyg35nz5znhwa
Keys

Keys are named after command line options, but do not use a leading double hyphen (--). For example, the key for --image-id is image-id. You can specify keys for single values, multiple values, and flags.

  • Keys for Single Values. The next example shows how to specify key values at different levels, and with different scope.

    [DEFAULT]
    # Defines a global default for bucket-name
    bucket-name = my-global-default-bucket-name
    
    # Defines a default for bucket-name, which applies to all 'compute' commands
    compute.bucket-name = bucket-name-for-image-import-export
    				
    # Defines a default for bucket-name, which applies to all 'os object' commands (e.g., os object get)
    os.object.bucket-name = bucket-name-for-object-commands
    
    # Defines a default for bucket-name, for the 'os object multipart list' command
    os.object.multipart.list.bucket-name = bucket-name-for-multipart-list
  • Keys for Multiple Values. Some options, such as --include and --exclude on the oci os object bulk-upload command can be specified more than once. For example:

    oci os object bulk-upload -ns my-namespace -bn my-bucket --src-dir my-directory --include *.txt --include *.png

    The next example shows how you would enter the --include values in the --cli-rc-file file

    [DEFAULT]
    os.object.bulk-upload.include =
    			*.txt
    			*.png

    In the previous example, one value is given for each line and each line must be indented underneath its key. You can use tabs or spaces and the amount of indentation doesn't matter. You can also put a value on the same line as the key, add more values on the following lines, and use a path statement for a value. For example:

    [DEFAULT]
    os.object.bulk-upload.include = *.pdf
    			*.txt
    			*.png
    			my-subfolder/*.tiff
  • Keys for Flags. Some command options are flags, like --force, which uses a Boolean value. To set a flag for the --force option, use the following command.

    os.object.delete.force=true

Specifying Command Aliases

Specify named queries in the OCI_CLI_COMMAND_ALIASES section of the CLI configuration file. There are two types of aliases, global aliases and command sequence aliases. The following example shows each type of alias.

[OCI_CLI_COMMAND_ALIASES]
# This is a global alias that lets you use "ls" instead of "list" for any list command in the CLI.
#
ls = list

# Command examples:
# oci os object ls or oci os compute ls

# This is a command sequence alias that lets you use "oci os object rm" instead of "oci os 
# object delete". 
# <alias> = <dot-separated sequence of groups and sub-groups>.<command or group to alias>
# 
rm = os.object.delete					

# Command example:
# <alias> = rm, <sequence of groups and sub-groups> = os object, <command or group to alias> = delete	 								

If you want to define default values for options in your CLI configuration file, you can use the alias names you have defined. For example, if you have -ls as an alias for --list, you can define a default for an availability domain when listing instances by using the following command.

[DEFAULT]
compute.instance.ls.compartment-id=ocid1.compartment.oc1..aaaaaaaal5zx25nzpgeyqd3gzijdlg3ieqeyrggnx7il26astxxhqoljnhwa

Specifying Option Aliases

Specify option aliases in the OCI_CLI_PARAM_ALIASES section of the CLI configuration file. Option aliases are applied globally. The following example shows some aliases for command options.


[OCI_CLI_PARAM_ALIASES]
# Option aliases either start with a double hyphen (--) or are a single hyphen (-) followed by a # single letter. For example: --example-alias, -e
#
--ad = --availability-domain
--dn = --display-name
--egress-rules = --egress-security-rules
--ingress-rules = --ingress-security-rules

If you want to define default values for options in your CLI configuration file, you can use the alias names you have defined. For example, if you have -ad as an alias for --availability-domain, you can define a default for an availability domain when listing instances by using the following command.

[DEFAULT]
compute.instance.list.ad=xyx:PHX-AD-1

Specifying Named Queries

If you use the --query parameter to filter or manipulate output, you can define named queries instead of using a JMESPath expression on the command line.

Specify named queries in the OCI_CLI_CANNED_QUERIES section of the CLI configuration file.

Enabling Auto-complete

If you used the CLI installer, you don't have to configure auto-complete because it's enabled automatically.

To enable auto-complete (tab completion) for a manual CLI installation, run the following command.

oci setup autocomplete

To enable auto-complete on a session by session basis, run the following command.

eval "$(_OCI_COMPLETE=source oci)"

Support for Auto-complete on Windows

Auto-complete on Windows is only supported if you're using PowerShell. A script runs to enable this feature. However, you must change the PowerShell execution policy to RemoteSigned. To configure this policy, run the following command at the PowerShell command line.

Set-ExecutionPolicy RemoteSigned