Using the OCI CLI

Before You Begin

To install and use the OCI CLI, you must have:

A user account for the Compute Web UI.
An API signing key pair, required to sign API requests. If you do not already have an RSA public/private key pair in PEM format, you can create one in the OCI CLI configuration steps. To add the public key to your user account, see Adding an API Public Key to a User Profile.
A Private Cloud Appliance self-signed certificate.

This requirement is satisfied during the configuration steps.

You can install the OCI CLI on macOS, Microsoft Windows, or any supported Linux/UNIX operating system:

Oracle Linux 7 and Oracle Linux 8
CentOS 7.0 and CentOS 8.x
Ubuntu 16.04, Ubuntu 18.04, and Ubuntu 20.04

Installing the OCI CLI

You can install the OCI CLI on Oracle Linux or macOS operating systems using a package manager. To install on Microsoft Windows or some other operating system, use the install script.

Important:

If you already have the CLI installed and configured, you can skip to Configuring the OCI CLI to learn how to further configure the CLI for Private Cloud Appliance.

To install the CLI, its dependencies, and Python, follow the steps for your operating system. During installation, respond to the prompts for information as described in "Responding to the Install Script Prompts."

Oracle Linux 8

Run the following commands to install the CLI:

$ sudo dnf -y install oraclelinux-developer-release-el8
$ sudo dnf install python36-oci-cli

To uninstall the CLI, run:

$ sudo dnf remove python36-oci-cli

Oracle Linux 7

Run the following command to install the CLI:

$ sudo yum install python36-oci-cli

To uninstall the CLI, run:

$ sudo yum remove python36-oci-cli

macOS

You can use Homebrew to install, upgrade, and uninstall the CLI on macOS.

Note:

Optionally, you can install the CLI using the install script. See "Using the Install Script for Other Operating Systems" in this section for details.

To install the CLI, run:
```
$ brew update && brew install oci-cli
```
To upgrade the CLI, run:
```
$ brew update && brew upgrade oci-cli
```
To uninstall the CLI, run:
```
$ brew uninstall oci-cli
```

Microsoft Windows

You can use Microsoft Windows PowerShell to install the CLI.

Open the PowerShell console using the Run as Administrator option.
Set the http_proxy and https_proxy environment variables.

Important:

The value of https_proxy is the hostname or IP address of your HTTP proxy server.
```
$Env:http_proxy="http://www-proxy.example.com:80"
$Env:https_proxy="http://www-proxy.example.com:80"
```
If your proxy server requires a user name and password, or uses a port number other than 80, include that information, as shown in the following example:
```
$Env:https_proxy=http://username:password@proxy.example.com:port
```
Check that your proxy variables are set correctly. Make sure you can connect to internet locations.
```
$Env:http_proxy
$Env:https_proxy
ping https://raw.githubusercontent.com
```
The installer enables auto-complete by installing and running a script. To allow this script to run, you must enable the RemoteSigned execution policy.

To configure the remote execution policy for PowerShell, run the following command:
```
$ Set-ExecutionPolicy RemoteSigned
```

Force PowerShell to use TLS 1.2 for Microsoft Windows 2012 and Microsoft Windows 2016:

$ [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Download the install script:

$ Invoke-WebRequest ^
https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.ps1 ^
-OutFile install.ps1

Run the install script with or without prompts.

Run the install.ps1 script that you downloaded in the previous step.

To avoid prompts and accept the default values, run the script with the following option:
```
$ install.ps1 -AcceptAllDefaults
```
Unset the proxy environment variables.
```
$Env:http_proxy=""
$Env:https_proxy=""
```

Using the Install Script for Other Operating Systems

For any other operating system, run the following install script to install the CLI, its dependencies, and Python.

$ bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"

To avoid prompts and accept the default values, add the --accept-all-defaults option.

Responding to the Install Script Prompts

If you do not have a compatible version of Python installed in Linux or Microsoft Windows, you are prompted to provide a location for installing the binaries and executables. The script installs Python for you.
If you do not have a compatible version of Python installed in macOS, you are notified that your version of Python is incompatible. You must upgrade before you can proceed with the installation. The script does not install Python for you.
When prompted to upgrade the CLI to the newest version, respond with Y to overwrite an existing installation.
When prompted to update your PATH, respond with Y to be able to invoke the oci command without providing the full path to the executable.

Configuring the OCI CLI

Before using the OCI CLI, you must configure it for working with Private Cloud Appliance and obtain the system's certificate authority (CA) chain. You can complete the configuration manually or use the config setup tool to help you.

Important:

If you are already using the OCI CLI and have it configured for other purposes, read this section entirely before proceeding with any of the configuration steps.

Obtain the Required Information

Whether you manually configure the OCI CLI or use the setup config tool, there is required information you must provide for the configuration file. Before you begin the configuration process, ensure you have the following:

User OCID

The user's OCID is in ocid1.user.unique_ID format. You can copy the user's OCID from the user details page in the Compute Web UI. To navigate to your user details page, click your user name in the Compute Web UI dashboard and then click My Profile.
Tenancy OCID

The tenancy OCID is in ocid1.tenancy..unique_ID format. You can copy the tenancy OCID from the tenancy details page in the Compute Web UI. To navigate to the tenancy details page, click your user name in the Compute Web UI dashboard and then click Tenancy.
Region name

The region name is in pcasys1.example.com format, where pcasys1 is the name of your Private Cloud Appliance and example.com is your domain.

If you have access to the Service Web UI, you can find the system and domain names on the dashboard. Otherwise, ask a Service Web UI administrator for the information.

If you do not already have an existing API public and private key pair, we recommend that you create them as part of the manual or automated OCI CLI configuration. For more information, see the Manual Configuration or Automated Configuration section.

If you have an existing API public and private key pair that you want to use, make sure:

They are in PEM format.
Your public key is added to your user profile.
You know the full path and file name of the private key. For example, ~/.oci/oci_api_key.pem .
You have your public key fingerprint, which is in xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx format. You can find this fingerprint on your profile page in the Compute Web UI or through a terminal using a command. For example:
```
openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c
```

Manual Configuration

Complete the following steps to manually configure the OCI CLI for Private Cloud Appliance. Ensure you have gathered all the required information.

The steps below assume you are on a Linux system and that you have already created a user through the Compute Web UI. However, the basic procedure is the same for other system types.

From a terminal, log into the system where you installed the CLI and create an API key pair. For example:

$ oci setup keys
Enter a passphrase for your private key (empty for no passphrase):
Public key written to: /home/username/.oci/oci_api_key_public.pem
Private key written to: /home/username/.oci/oci_api_key.pem
Public key fingerprint: xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx

From a browser, log into the Web UI.
Navigate to your user details page. Click your user name in the top right of the page, and then click My Profile. Your user details page is displayed.
In the Resources section of your user details page, click API Keys, and then click the Add API Key button.
Navigate to the location of your public key or paste the public key contents and then click Upload Key.
In your /home/username/.oci directory, create a file named config. Add a profile section with the required information:
```
[PCA1]
user=ocid1.user...unique_id
key_file=/home/username/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.unique_ID
region=pcasys1.example.com
fingerprint=xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx
```
In this example, pcasys1 is the name of your Private Cloud Appliance and example.com is your domain.

If you have access to the Service Web UI, you can find the system and domain names on the dashboard. Otherwise, ask a Service Web UI administrator for the information.

Automated Configuration

If this is the first time you are using the OCI CLI, the setup config tool helps you walk you through setup process. When you enter the oci setup config command it prompts you for the information required for the config file and the API public/private keys and then generates an API key pair and creates the config file.

To configure the OCI CLI using the setup config tool:

From a command window, enter oci setup config and follow the prompts, for example:

$ oci setup config
This command provides a walkthrough of creating a valid CLI config file.
Enter a location for your config [/home/myuserdir/.oci/config]:
Enter a user OCID: ocid1.user.unique_ID
Enter a tenancy OCID: ocid1.tenancy.unique_ID

Important:

For the step Enter a region by index or name, you cannot enter the region in the required system.domain format. Rather, enter any value from the list as the value is meaningless to Private Cloud Appliance. In Step 2 you will modify the config file to provide the information needed by Private Cloud Appliance.

Enter a region by index or name(e.g.
1: ap-chiyoda-1, 2: ap-chuncheon-1, 3: ap-hyderabad-1, 4: ap-melbourne-1, 5: ap-mumbai-1,
6: ap-osaka-1, 7: ap-seoul-1, 8: ap-sydney-1, 9: ap-tokyo-1, 10: ca-montreal-1,
11: ca-toronto-1, 12: eu-amsterdam-1, 13: eu-frankfurt-1, 14: eu-zurich-1, 15: me-dubai-1,
16: me-jeddah-1, 17: sa-santiago-1, 18: sa-saopaulo-1, 19: sa-vinhedo-1, 20: uk-cardiff-1,
21: uk-gov-cardiff-1, 22: uk-gov-london-1, 23: uk-london-1, 24: us-ashburn-1, 
25: us-gov-ashburn-1, 26: us-gov-chicago-1, 27: us-gov-phoenix-1, 28: us-langley-1, 
29: us-luke-1, 30: us-phoenix-1, 31: us-sanjose-1): 24

Do you want to generate a new API Signing RSA key pair? 
(If you decline you will be asked to supply the path to an existing key.) [Y/n]: Y
Enter a directory for your keys to be created [/home/myuserdir/.oci]:
Enter a name for your key [oci_api_key]:
Public key written to: /home/myuserdir/.oci/oci_api_key_public.pem
Enter a passphrase for your private key (empty for no passphrase):
Private key written to: /home/myuserdir/.oci/oci_api_key.pem
Fingerprint: xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx
Config written to /home/myuserdir/.oci/config

Navigate to the ~/myuserdir/.oci directory and modify the config file to use the correct region, for example:
```
[DEFAULT]
user=ocid1.user.unique_ID
fingerprint=xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx
key_file=/home/myuserdir/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.unique_ID
region=pcasys1.example.com
```
where pcasys1 is the name of your Private Cloud Appliance and example.com is your domain.

If you have access to the Service Web UI, you can find the system and domain names on the dashboard. Otherwise, ask a Service Web UI administrator for the information.
If you haven't already, upload your API Signing public key through the Compute Web UI. For more information, see Adding an API Public Key to a User Profile.

Obtaining the Certificate Authority Bundle

Whether you configured the CLI manually or used the automated tool, you must obtain the Private Cloud Appliance external silo CA chain before you can run commands.

The external silo CA chain must be copied to the system where you are installing the CLI and referenced in the oci_cli_rc file.

Navigate to your ~/.oci directory.
Copy the external silo CA chain from the following location:
```
https://iaas.system-name.domain-name/cachain
```
Save the CA chain in a file. In this example, the file is named ca.crt and is saved in the ~/.oci directory.
In the ~/.oci directory, create a file named oci_cli_rc. Add the profile name and the path to your copy of the external silo CA chain. For example:
```
[PCA1]
cert-bundle=/home/username/.oci/ca.crt
```
Set the OCI_CLI_CERT_BUNDLE environment variable to the same path as in the previous step.

Testing the OCI CLI Configuration

Important:

If you followed the manual configuration process and attempt to test the configuration by running the commands in this section, you might encounter a warning message stating the permissions on the config file are too open. If this happens, follow the instructions in the warning message to resolve the issue.

After you have installed and configured the OCI CLI, enter a list command to verify that the OCI CLI is working correctly. For example:

$ oci iam user list

Using Multiple Profiles

The OCI CLI configuration files config and oci_cli_rc can define more than one profile. Each profile section in the config file references a tenancy within a Private Cloud Appliance. The tenancies can be on different appliances.

In the following example ~/.oci/config file, the PCA1 profile is for a tenancy on the pcasys1 appliance, the PCA2 profile is for a tenancy on the pcasys2 appliance, and the DEFAULT profile is a copy of the PCA1 profile. The DEFAULT profile is used when you have not specified which profile to use.

In this example, the key file and fingerprint are the same in each profile, but the user OCID will be different on the two different appliances or in two different tenancies on the same appliance.

[DEFAULT]
user=ocid1.user.unique_ID_1
key_file=/home/username/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.unique_ID_1
region=pcasys1.example.com
fingerprint=58:f8:69:13:e1:a8:51:4d:5a:a0:11:69:ca:09:48:73
[PCA1]
user=ocid1.user.unique_ID_1
key_file=/home/username/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.unique_ID_1
region=pcasys1.example.com
fingerprint=58:f8:69:13:e1:a8:51:4d:5a:a0:11:69:ca:09:48:73
[PCA2]
user=ocid1.user.unique_ID_2
key_file=/home/username/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.unique_ID_2
region=pcasys2.example.com
fingerprint=58:f8:69:13:e1:a8:51:4d:5a:a0:11:69:ca:09:48:73

Note:

If you do not specify a profile to use, the DEFAULT profile is used. If you do not specify a profile and do not have a DEFAULT profile, you must use the --profile option in your commands.

To specify a profile, set the profile name as the value of the OCI_CLI_PROFILE environment variable:

export OCI_CLI_PROFILE=PCA1

The --profile option is a global option, specified on oci, as in the following example:

$ oci --profile PCA2 iam user list

You must specify the same profiles in your oci_cli_rc file that you specified in your config file:

[DEFAULT]
cert-bundle=/home/username/.oci/pca1/ca.crt
[PCA1]
cert-bundle=/home/username/.oci/pca1/ca.crt
[PCA2]
cert-bundle=/home/username/.oci/pca2/ca.crt

If you have configured multiple profiles, consider creating subdirectories within the .oci directory to store the different API keys and external silo CA chains for each profile.

Consider creating a file of environment variables for each profile. In addition to setting OCI_CLI_PROFILE, set OCI_CLI_CERT_BUNDLE to the same path that you specified in your oci_cli_rc file. Set OCI_CLI_TENANCY to the OCID of the tenancy for this profile. Giving other compartments and resources names makes commands easier to enter and read. For example:

$ oci network subnet create -c $Networking --vcn-id $VCN1 ...

Working with API Signing Keys

If you need to use the OCI CLI or make REST API requests, you must have an RSA API signing public and private key pair in PEM format. API requests are signed with the private key, and the public key is used to verify the authenticity of the request. The private key is stored locally and the public key is uploaded to a user account. You can have a maximum of three (3) public keys per user account.

Important:

The API signing key pair is not the SSH key that you use to access compute instances.

Generating an API Key Pair

If you do not already have an existing API signing public and private key pair, we recommend that you create the key pair as part of the manual or automated configuration. To do so, use the oci setup keys command as shown in the Manual Configuration section or follow the prompts in the Automated Configuration section.

If you want to create a key pair independent of the OCI CLI configuration, the following sections show you how to do this on Linux, macOS, and Microsoft Windows operating systems. You can then use these keys when you configure the OCI CLI.

Using Linux or macOS

Generate the private key.
- Generate the key encrypted with a passphrase:
```
$ openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048
```
  Note:
  
  Use of a passphrase is strongly recommended.
- Generate the key with no passphrase:
```
$ openssl genrsa -out ~/.oci/oci_api_key.pem 2048
```
Check the permission on the private key file and change if necessary.

The file permission should be 600 or 400 to ensure that only you can read the private key file.
Generate the public key from your new private key:
```
$ openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem
```
This public key file can have the same permissions as the private key file or can be readable by everyone.

Using Microsoft Windows

Install Git Bash for Microsoft Windows.

See https://git-scm.com/download/win.
Include the OpenSSL binary in your Microsoft Windows path.

On default installations, the openssl.exe binary is in the following directory:
```
C:\Program Files\Git\mingw64\bin
```

Generate the private key.

Generate the key encrypted with a passphrase:

$ openssl genrsa -out %HOMEDRIVE%%HOMEPATH%\.oci\oci_api_key.pem -aes128 -passout  ^
stdin 2048

Note:

Use of a passphrase is strongly recommended.

Generate the key with no passphrase:

$ openssl genrsa -out %HOMEDRIVE%%HOMEPATH%\.oci\oci_api_key.pem 2048

Check the permission on the private key file and change if necessary.

The file permission should be set so that only you can read the private key file.
Generate the public key from your new private key:
```
$ openssl rsa -pubout -in %HOMEDRIVE%%HOMEPATH%\.oci\oci_api_key.pem -out  ^
%HOMEDRIVE%%HOMEPATH%\.oci\oci_api_key_public.pem
```
This public key file can have the same permissions as the private key file or can be readable by everyone.

Adding an API Public Key to a User Profile

An API signing key is a PEM-format RSA public/private key pair, at least 2048 bits.

Use the Compute Web UI to add your own API public key to your profile. You cannot use the OCI CLI until you have your API signing key pair in place. If you do not have a login and password for the Compute Web UI, contact an administrator.

A user can have a maximum of three (3) public keys added to their user account. If the user has more than one API public key, the user must specify the key's fingerprint to indicate which key they are using to sign the request.

Using the Compute Web UI

From a browser, log in to the Compute Web UI.
Navigate to the user details page.
- If you are adding a public key to your own user account, click your user icon in the upper right of the Compute Web UI, and then click My Profile.
- If you are adding a public key to a different user account, click Identity on the navigation menu, click Users, and then click the name of the user in the user list.
On the user details page, scroll to the Resources section, click API Keys, and then click Add API Key.
In the Add Public Key dialog, navigate to the location of the public key or paste the public key contents and then click Upload Key.

Using the OCI CLI

After you have installed and configured the OCI CLI, you can use the api-key upload command to upload additional keys for your user account or upload keys for another user.

Get the OCID of the user that needs an API signing key (oci iam user list).
Use the user API key list command to ensure that the account does not already have the maximum three API signing keys.

Syntax:
```
$ oci iam user api-key list --user-id user_OCID
```
Run the API key upload command.

Syntax:
```
$ oci iam user api-key upload --user-id ocid1.user.unique_ID \
{ --key public_key | --key-file file://public_keyfile.pem }
```
- public_key – an RSA public key in PEM format
- public_keyfile.pem – a file that contains an RSA public key in PEM format

Finding an API Public Key Fingerprint

Your public key fingerprint, which is in xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx format, can be found on your profile page in the Compute Web UI or through a terminal using the following OpenSSL commands:

Linux and macOS:

$ openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c

Microsoft Windows:

$ openssl rsa -pubout -outform DER -in \.oci\oci_api_key.pem | openssl md5 -c

Deleting an API Signing Key from a User Profile

You can delete your own API signing keys, and tenancy administrators can delete API signing keys for any user in their tenancy.

Using the Compute Web UI

In the navigation menu, click Identity, and then click Users.
Click the name of the user account for which you want to delete an API signing key.
Scroll to the Resources section of the user details page.
For the API key that you want to delete, click the Actions icon (three dots) and then click Delete.

Using the OCI CLI

Get the following information:
- The OCID of the user account from which you want to delete an API signing key.
```
$ oci iam user list
```
- The fingerprint of the API signing key that you want to delete.
```
$ oci iam user api-key list --user-id user_OCID
```

Run the user API key delete command.

Syntax:

$ oci iam user api-key delete --user-id user_OCID --fingerprint fingerprint

Understanding Command Syntax and Finding Help

This section provides some basic information to help you as you begin using the OCI CLI, such as command syntax, how to find OCIDs, and where to get help with commands.

Command Syntax

In general, commands entered in the OCI CLI have the following syntax:

$ oci service type action required-parameters optional-parameters

For example, in the following command:

$ oci iam user create --name joeb --description "Product test" \
--email joeb@example.com

iam is the service
user is the resource type
create is the action
name and description are required parameters
email is an optional parameter

Obtaining OCIDs

When you use the OCI CLI, the majority of commands require an OCID:

list commands require the OCID of the compartment where you are looking for the resource.
create commands require the OCID of the compartment where you want to create the resource.
get, update, and delete commands require the OCID of the resource.
move commands require the OCID of the resource and the OCID of the destination compartment.

Some commands require the OCID of a different resource. For example, creating a route table for a DRG requires the OCID of the DRG.

You can find OCIDs using the OCI CLI or the Compute Web UI. The following lists show you how to find the most commonly needed OCIDs using the OCI CLI.

Block volume service OCIDs

Boot volume

$ oci bv boot-volume list --availability-domain AD-1 \
--compartment-id compartment_OCID

Volume

$ oci bv volume list --compartment-id compartment_OCID

Volume backup policy

$ oci bv volume-backup-policy list --compartment-id compartment_OCID

Volume group

$ oci bv volume-group list --compartment-id compartment_OCID

Compute service OCIDs

Instance

$ oci compute instance list --compartment-id compartment_OCID

Instance VNIC

$ oci compute instance list-vnics --compartment-id compartment_OCID

Volume attachment

$ oci compute volume-attachment list --compartment-id compartment_OCID

Identity and access management service OCIDs

Compartments within a tenancy
```
$ oci iam compartment list
```
Compartments within a tenancy and including the tenancy
```
$ oci iam compartment list --include-root
```

Compartments and all sub-compartments in a tenancy

$ oci iam compartment list --compartment-id-in-subtree true

Compartment including its sub-compartments

$ oci iam compartment list --compartment-id compartment_OCID \
--compartment-id-in-subtree

Group
```
$ oci iam group list
```

Policy

$ oci iam policy list --compartment-id compartment_OCID

Tag namespace

$ oci iam tag-namespace list --compartment-id compartment_OCID

User
```
$ oci iam user list
```

Network service OCIDs

DHCP options

$ oci network dhcp-options list --compartment-id compartment_OCID \
[--vcn-id VCN_OCID]

Route table

$ oci network route-table list --compartment-id compartment_OCID \
[--vcn-id VCN_OCID]

Subnet

$ oci network subnet list --compartment-id compartment_OCID \
[--vcn-id VCN_OCID]

VCN

$ oci network vcn list --compartment-id compartment_OCID

In the Compute Web UI, an OCID Copy button is available on the details page of a resource and often also on the Actions menu for the resource in the resource list.

To more easily specify OCIDs, and to make your commands more readable, you might want to set frequently used OCIDs in environment variables. For example, you could set the tenancy to T. Compartments are the most frequently used OCIDs, and the --compartment-id option can be shortened to -c.

The following examples show listing all VCNs in the NET compartment and using the large shape instance configuration to launch an instance.

$ oci compute vcn list -c $NET
$ oci compute-management instance-configuration launch-compute-instance \
--instance-configuration-id $INST_CFG_LRG

Getting Help with Commands

You can get inline help by appending --help, -h or -? to a command:

oci --help returns a list of commands and global command options.

oci service --help returns a summary of the command reference for a service. For example:

$ oci compute -h
Usage: oci compute [OPTIONS] COMMAND [ARGS]...
  Compute Service CLI

Options:
  -?, -h, --help  For detailed help on any of these individual commands, enter 
                  <command> --help.
Commands:
  boot-volume-attachment          Represents an attachment between a...
  capacity-reservation            A template that defines the...
  console-history                 An instance's serial console data.
  dedicated-vm-host               A dedicated virtual machine host...
  dedicated-vm-host-instance      Condensed instance data when...
  device                          Device Path corresponding to the...
  global-image-capability-schema  Global Image Capability Schema
  global-image-capability-schema-version
                                  Global Image Capability Schema...
  image                           A boot disk image for launching an...
  image-capability-schema         Image Capability Schema
  image-shape-compatibility-entry An image and shape that are...
  instance                        A compute host.
  instance-console-connection     The `InstanceConsoleConnection`...
  measured-boot-report            The measured boot report for a...
  pic                             Partner image catalog (PIC).
  shape                           A compute instance shape that can...
  vnic-attachment                 Represents an attachment between a...
  volume-attachment               A base object for all types of...

oci service resource_type --help returns a summary of the command reference for a resource type. For example:

$ oci compute image -h
Usage: oci compute image [OPTIONS] COMMAND [ARGS]...
  A boot disk image for launching an instance. For more information, see
  [Overview of the Compute Service].

  To use any of the API operations, you must be authorized in an IAM policy.
  If you're not authorized, talk to an administrator. If you're an
  administrator who needs to write policies to give users access, see
  [Getting Started with Policies].

  **Warning:** Oracle recommends that you avoid using any confidential
  information when you supply string values using the API.

Options:
  -?, -h, --help  For detailed help on any of these individual commands, enter
                  <command> --help.

Commands:
  change-compartment  Moves an image into a different compartment within...
  create              Creates a boot disk image for the specified instance...
  delete              Deletes an image.
  export              Exports an image to the Oracle Cloud Infrastructure...
  get                 Gets the specified image.
  import              Imports an exported image from the Oracle Cloud...
  list                Lists a subset of images available in the specified...
  update              Updates the display name of the image.

oci service resource_type action --help returns the complete command reference for the specified service resource action. For example, the following command displays a full description of creating a compute image, and describes all options:
```
$ oci compute image create -h
```

For more information, see the Oracle Cloud Infrastructure CLI Command Reference.

Using JSON for Complex Command Input

Complex command input includes arrays and objects with more than one value. Complex input is passed as a block of key/value pairs in JSON format. The JSON-formatted input can be provided as a string in the command line or as a file that is referenced in the command line.

The OCI CLI supports using both JSON strings and file references in the same command line. However, if the same values are provided in a file and in a string in the same command, the string value takes precedence.

Using a JSON String

To pass a JSON block as a string in the OCI CLI command line, remove the newlines. On macOS, Linux, or UNIX, enclose the entire JSON block in single quotation marks. In Microsoft Windows command lines, enclose the JSON block in double quotation marks, and escape the double quotation marks that are within the block (\").

On any operating system or shell, you might need to escape other characters such as dollar signs.

If you receive the message "Parameter 'parameter_name' must be in JSON format," then your JSON formatting is not correct. If you copied the JSON format as described in Generating JSON Format, then recheck your command-line format, especially characters that might need to be escaped.

macOS, Linux, or UNIX

$ oci compute instance update --instance-id ocid1.image.unique_ID \
--freeform-tags '{"Department":"Finance"}'

Microsoft Windows

> oci compute instance update --instance-id ocid1.image.unique_ID \
--freeform-tags "{\"Department\":\"Finance\"}"

Using a JSON File

An advantage of storing complex option arguments in files is that you can easily reuse arguments that you know are in correct format. You can store the data exactly the way you copy it from output of the --generate-param-json-input option or of the get command: You do not need to remove newlines and escape certain characters as you need to do for command-line strings.

When you pass input using a JSON file, the option argument is the file name prefixed with file://. The file name can be the name of the file in the same directory where you are running the command, the relative path to the file, or the full path to the file.

Generating JSON Format

If you receive the message "Parameter 'parameter_name' must be in JSON format," then your JSON formatting is not correct. The following methods will help you format the data correctly.

JSON Format for a Single Complex Type Option Value

If an option is complex type, then you can generate the JSON format for that option value by using the --generate-param-json-input option. The argument for the --generate-param-json-input option is the name of the option for which you want the JSON format, without the -- option specifier. For example, the following command shows the JSON format to use to specify route rules (--route-rules option) for a route table:

$ oci network route-table update --generate-param-json-input route-rules
[
  {
    "cidrBlock": "string",
    "description": "string",
    "destination": "string",
    "destinationType": "string",
    "networkEntityId": "string"
  },
  {
    "cidrBlock": "string",
    "description": "string",
    "destination": "string",
    "destinationType": "string",
    "networkEntityId": "string"
  }
]

Values that you provide in the option argument replace any existing values. For example, if you already have an ingress rule and you want to add an egress rule, you must specify both the existing ingress rule and the new egress rule. If you specify only the rule that you want to add, any previously existing rules will be gone. Similarly, if you want to add a policy statement or add values for a defined tag, for example, you must respecify the existing statements or values that you want to keep in addition to what you want to add.

Sometimes the output contains a message about choices, such as in the following example:

$ oci compute instance launch --generate-param-json-input source-details
[
  "This parameter should actually be a JSON object rather than an array - pick one of the
  following object variants to use",
  {
    "bootVolumeId": "string",
    "sourceType": "bootVolume"
  },
  {
    "bootVolumeSizeInGBs": 0,
    "imageId": "string",
    "kmsKeyId": "string",
    "sourceType": "image"
  }
]

When you use the Compute Web UI to create an instance, you select either a Custom Image or a Boot Volume. Similarly, the message in the preceding example tells you to specify either the boot volume block or the image block, not both.

JSON Format for Values of All Options of a Command

The --generate-full-command-json-input option shows JSON format for values of all options of the specified command, including values that are not complex values.

$ oci network route-table update --generate-full-command-json-input > route_table_update.json

Use the --from-json option to pass in your customized version of this output.

$ oci network route-table update --from-json file://route_table_update.json

JSON Format of Existing Values

If resources of this type already exist, do a get or list of the resources to see the JSON formatting and also to check the current values.

$ oci network route-table get --rt-id ocid1.routetable.unique_ID

Copy the block you want directly from this output, and then change the values as needed.

In the case where multiple values are allowed, use this method to avoid overwriting values that you want to keep. Copy the block you want from the get or list output, and then change, add, or delete values as needed.

Formatting and Filtering Command Output

By default, all command output is in JSON format:

$ oci iam region list
{
  "data": [
    {
      "key": "pcasysname",
      "name": "pcasysname"
    }
  ]
}

If you prefer, command output can be formatted as a table:

$ oci iam region list --output table
+------------+------------+
| key        | name       |
+------------+------------+
| pcasysname | pcasysname |
+------------+------------+

You can filter output using the JMESPath query option for JSON. Filtering is useful when you have a large amount of output. The --output table option shows a column for each property of a resource. The output table for an instance, for example, has almost 30 columns and probably overflows the width of your display.

To output only the data that you want, use the --query option with the --output table option, as shown in the following example:

$ oci compute image list -c ocid1.compartment.unique_ID --output table \
--query "data [*].{ImageOCID:id, OperatingSystem:\"operating-system\"}"
+-------------------------+-----------------+
| ImageOCID               | OperatingSystem |
+-------------------------+-----------------+
| ocid1.image.unique_ID_1 | OracleLinux     |
| ocid1.image.unique_ID_2 | OracleLinux     |
+-------------------------+-----------------+

For more information about the JMESPath query language for JSON, see JMESPath.