Oracle Cloud Infrastructure (OCI) CLI

Reference page

Introduction

The CLI is a small-footprint tool that you can use on its own or with the Console to complete Oracle Cloud Infrastructure tasks. The CLI provides the same core functionality as the Console, plus additional commands. Some of these, such as the ability to run scripts, extend Console functionality.

This CLI and sample are dual licensed under the Universal Permissive License 1.0 and the Apache License 2.0; third-party content is separately licensed as described in the code.

The CLI is built on the Oracle Cloud Infrastructure SDK for Python and runs on Mac, Windows, or Linux (for more information about SDKs, see: the Other Resources section below). The Python code makes calls to Oracle Cloud Infrastructure APIs to provide the functionality implemented for the various services. These are REST APIs that use HTTPS requests and responses. For more information, see: About the API.

Installation

Quick start

Select an OS-specific version below to install a local version of the OCI CLI.

OCI CLI currently supports: Oracle Linux 8, Oracle Linux 7, Mac OS, Windows, and Linux and Unix

Special cases

• WSL (Windows Subsystem for Linux) in Windows 10 or above

OCI CLI container image

OCI also supports running a container image version of the CLI.

Requirements

Set up: for details on how to install and configure OCI CLI by using a container image, see: Working with the OCI CLI container image.

Troubleshooting

If you should encounter issues either during installation (Python or CLI) or when using the CLI itself, refer to the page, Troubleshooting the CLI for assistance.

Authentication

Token-based authentication for the CLI allows customers to authenticate their session interactively, then use the CLI for a single session without an API signing key. This enables customers using an identity provider that is not SCIM-supported to use a federated user account with the CLI and SDKs.

Requirements

The requirements are the same as those listed for the CLI in Requirements, except that instead of an SSH keypair, you need a web browser for the authentication process.

Note: There is still a way to start a token-based CLI session even if you don’t have access to a browser.

Starting a token-based CLI session

To use token-based authentication for the CLI on a computer with a web browser:

1. In the CLI, run the following command. This will launch a web browser.
   Copy

   
       oci session authenticate

2. In the browser, enter your user credentials.

   Note: This authentication information is saved to the .config file.

Other actions

• Refreshing a token
• Validating a token

Configuration

The CLI supports using a file for CLI-specific configurations. You can use these optional configurations to extend CLI functionality.

With this configuration file you can:

• Specify a default profile
• Set default values for command options
• Define aliases for commands
• Define aliases for options
• Define named queries that are passed to the --query option instead of typing a JMESPath expression on the command line.

Note: The CLI also supports the use of environment variables to specify defaults for some options. see: CLI Environment Variables for more information.

Configuration file

Location

Default location: ~/.oci/oci_cli_rc

Specify the location via:

• Environment variable: OCI_CLI_RC_FILE
• Command-line option: --cli-rc-file

Example:

    <CLI command> --cli-rc-file path/to/my/cli/rc/file

Setting up the oci_cli_rc file

In a new CLI window, run:

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

Note: This command creates the file you specify that includes examples of default command aliases, parameter aliases, and named queries.

Working with your configuration file

• Setting up a default profile
  

  Section: OCI_CLI_SETTINGS

  Format: default_profile=<profile name>

• Specifying default values
  

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

  Note: 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.

• Specifying command aliases
  

  There are two types of aliases: global aliases and command sequence aliases.

• Specifying option aliases
  

  Section: OCI_CLI_PARAM_ALIASES

  Format: <option alias> = <original option>

  Example:

  --ad = --availability-domain

  Note: Option aliases are applied globally.

• Specifying named queries
  

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

  Section: OCI_CLI_CANNED_QUERIES

• Autocomplete

  Note: If you used the CLI installer, autocomplete was already installed by default.

  However, if you manually installed the CLI or only wish to enable auto-complete on a per-session basis, use one of the commands below.

  • Manual installation - Run the following command:
    Copy

    
        oci setup autocomplete

  • Session-by-session basis – Run the following command:
    Copy

    
        eval "$(_OCI_COMPLETE=source oci)"

Using the CLI

Reference documentation

Basic command line syntax

Most commands must specify a service, followed by a resource type and then an action.

The basic command line syntax is:

    oci <service> <type> <action> <options>

Example:

The following command to launch an instance shows a typical command line construct:

    oci compute instance launch --availability-domain "EMIr:PHX-AD-1" -c <compartment> --shape "VM.Standard1.1"  --display-name "Instance 1 for sandbox" --image-id <imageID> --subnet-id  <subnetID>

Here, compute is the service, instance is the type, launch is the action, and the balance of the command represents the options.

Note: Throughout this document, the term oci will be used to refer to commands executed within the CLI environment.  This is to be distinguished from OCI, which is about the Oracle Cloud Infrastructure platform.

Getting help with commands

For help with a specific command, you can enter help <command> on the command line or view the Command Line Reference.

In addition, you can get help for any command by using the --help, -h, or -? flag.

Examples:

• oci - -help
• oci os bucket -h
• oci os bucket create -?

For a full list of commands, refer to the OCI CLI help documentation.

Output formats

• JSON (--output JSON) – (default) The output is formatted as JSON string.
  

  For additional information about working with JSON, the Advanced JSON options section below.

• Table (--output table) - The output is formatted as a table with headings derived from the query parameters. It typically presents in an easier-to-read, human-friendly format.
• --raw-output - You can supply this argument to the CLI if you know that the output is a single string value; any surrounding quotes are removed for you in the output.

Additional features

Interactive mode

In this mode, the oci helps guide you through command usage with auto-complete.

Advanced JSON options

Correct JSON format

The OCI CLI provides a built-in method to get the correct JSON format for both command options and commands.

• Command options - For a command option, use --generate-param-json-input and specify the command option that you want to get the JSON for.

  Example: To generate the JSON for creating or updating a security rule, run the following command:

  Copy

  
      oci network security-list create --generate-param-json-input ingress-security-rules

• Entire command - For an entire command, use --generate-full-command-json-input.

  Example: To generate the JSON for launching an instance, run the following command:

  Copy

  
      oci compute instance launch --generate-full-command-json-input

JMESPath

JMESPath is a query language for JSON that allows you to extract and transform elements from a JSON document.

For additional references, see:

• JMESPath project page
• JMESPath tutorial

jq

jq is a command-line JSON processor which can be utilized in conjunction with OCI CLI input and output.

“jq is like sed for JSON data - you can use it to slice and filter and map and transform structured data.”

For additional references, see:

• jq project page
• jq man page

For some ways to use jq with the OCI CLI, see:

• Useful examples (advanced)
• OCI jq tricks

Search and query functions

For helpful insights and use cases, see: Exploring the search and query features of the Oracle Cloud Infrastructure command line interface.

o, the OCI CLI wrapper utility

o is a smart wrapper for the oci command in Oracle Cloud’s CLI. o knows all the oci commands, and it learns about your resources. With this knowledge, o helps you use oci to manage your cloud resources. Tasks that used to require scripting can now be performed directly from the command line.

To learn more about o, see:

• Introducing o, the easy way to use the CLI
• o project repo README

Useful examples (General)

Where $T is the tenancy OCID, $C is the compartment OCID, and $G is the group OCID

Note: the tenancy is always considered to be the root compartment; this means that when the user-id flag isn’t used the command will default to using the tenancy as the compartment OCID

Useful examples (Advanced)

General

Locate tenancy OCID

oci iam availability-domain list --all | jq -r '.data[0]."compartment-id"'

Retrieve the home region

oci iam region-subscription list | jq -r '.data[0]."region-name"'

Get the base URL of an object stored in the home region

namespace=$(oci os ns get | jq -r .data)

home=$(oci iam region-subscription list | jq -r '.data[0]."region-name"')

echo https://objectstorage.$home.oraclecloud.com/n/$namespace/b/<bucketname>"

Get a list of subscribed region names and keys

oci iam region-subscription list | jq '.data[]."region-name" | .data[]."region-key"'

Create policy at the root level

TENANCY=$(oci iam availability-domain list --all | jq -r '.data[0]."compartment-id"')

oci iam policy create --compartment-id $TENANCY --name <policyname> --statements '["sentence1", "sentence2"]' --description <policydescription>

Obtain OCID from compartment name

Note: Compartment names are case sensitive.

compname="<compartmentName>"

compocid=$(oci iam compartment list --compartment-id-in-subtree true --all | jq --arg compname "$compname" '.data[] | select(."name"==$compname)' | jq -r ."id")

echo $compocid

Obtain FN-OCID from COMPARTMENT OCID + APP-NAME + FN-NAME

compartment="ocid1.compartment.oc1......aea" # see: above to obtain the OCID

appname="<appName> "

fnname="<functionName>"

appid=$(oci fn application list -c $compartment  --all | jq --arg appname "$appname" '.data[] | select(."display-name"==$appname)' | jq -r ."id")

fnid=$(oci fn function list --application-id $appid | jq --arg fnname "$fnname" '.data[] | select(."display-name"==$fnname)' | jq -r ."id")

echo $fnid

List container images in a compartment

oci artifacts container image list --compartment-id <compartmentOCID>

Functions (fn)

CLI for the Functions service.

Full set of OCI CLI fn commands.

Function

A function resource defines the code (Docker image) and configuration for a specific function. Functions are defined in applications.

Create

oci fn function create --application-id <applicationID> --display-name <displayName> --image <imageName> --memory-in-mbs <integer>

Delete

oci fn function delete --function-id <functionID>

List

List the functions associated with an application.

oci fn function list --application-id <applicationID>

Application

An application contains functions and defined attributes shared between those functions, such as network configuration and configuration.

List

oci fn application list -c <compartmentID>

Images

Create an image

Creates a boot disk image for the specified instance or imports an exported image from the Oracle Cloud Infrastructure Object Storage service.

oci compute image create --compartment-id <compartmentID>

Launch an instance from an image

(see: above)

Instances

Lists the shapes that can be used to launch a VM instance

Note: this applies to a dedicated virtual machine host within the specified compartment

oci compute dedicated-vm-host instance-shape list --compartment-id <compartment_OCID>

List instances

oci compute instance list --compartment-id <compartment_OCID>

Actions (stop/start/reset)

oci compute instance action --action [text] --instance-id [instanceID]

where the values of the action flag are:

STOP, START, SOFTRESET, RESET, SOFTSTOP, SENDDIAGNOSTICINTERRUPT, DIAGNOSTICREBOOT, REBOOTMIGRATE

Launch

Creates a new instance in the specified compartment and the specified availability domain.

oci compute instance launch --availability-domain <availability_domain> --compartment-id <compartment_OCID> --shape <shape> --subnet-id [subnetID]

Where shape refers to the shape of the instance. The shape determines the number of CPUs, amount of memory, and other resources allocated to the instance.

You can enumerate all available shapes by calling ListShapes.

Launch an instance from an image

oci compute instance launch --availability-domain <availability_domain> --compartment-id <compartment_OCID> --shape <shape> --subnet-id [subnetID] --image-id [imageID]

Where imageID is the OCID of the image used to boot the instance.

Note: This is a shortcut for specifying an image source via the --source-details complex JSON parameter.

If the image-id parameter is used, you cannot provide the --source-details or --source-boot-volume-id parameters.

Terminate

Terminates the specified instance. Any attached VNICs and volumes are automatically detached when the instance terminates.

oci compute instance terminate –instance-id <instanceID>

Monitor

Activate instance monitoring

Activate Resource Plugin for compute instance identified by the instance ocid. Stores monitored instances Id and its state. Tries to enable Resource Monitoring plugin by making remote calls to Oracle Cloud Agent and Management Agent Cloud Service.

oci appmgmt-control monitored-instance activate-plugin --monitored-instance-id <instanceID>

List monitored instances

oci appmgmt-control monitored-instance-collection list-monitored-instances --compartment-id <COMPARTMENT_OCID>

Instance pools

Creating

Use instance pools to create and manage multiple compute instances within the same region as a group.

oci compute-management instance-pool create --compartment-id <COMPARTMENT_OCID> --instance-configuration-id <INSTANCE_CONFIGURATION_OCID> --placement-configurations <file://path/to/file.json> --size <NUMBER_OF_INSTANCES>

Where <file://path/to/file.json> is the path to a JSON file that defines the placement configuration. For information about how to generate an example of the JSON file, see: Advanced JSON Options.

Deleting

Permanently delete instance pools that you no longer need.

Note: When you delete an instance pool, the resources that are associated with the pool are permanently deleted.

oci compute-management instance-pool terminate --instance-pool-id <INSTANCE_POOL_OCID>

Stopping and starting instances in an instance pool

You can stop and start individual instances in an instance pool as needed to update software or resolve error conditions (see: above).

Note: To stop all instances in an instance pool, stop the instance pool itself.

If you manually stop all instances in an instance pool instead of stopping the instance pool itself, the instance pool will try to relaunch the individual instances.

Start all instances

oci compute-management instance-pool start --instance-pool-id <INSTANCE_POOL_OCID>

Stop all instances

oci compute-management instance-pool stop --instance-pool-id <INSTANCE_POOL_OCID>

Reset all instances

oci compute-management instance-pool reset --instance-pool-id <INSTANCE_POOL_OCID>

Softreset all instances

oci compute-management instance-pool softreset --instance-pool-id <INSTANCE_POOL_OCID>

List instances in an instance pool

oci compute-management instance-pool list-instances --compartment-id <compartmentID> --instance-pool-id <INSTANCE_POOL_OCID>

List instance pools in a compartment

oci compute-management instance-pool list --compartment-id <compartmentID>

Object storage

Object Storage is a fully programmable, scalable, and durable cloud storage service

You can use the CLI for object operations within the Object Storage service.

Note: In the OCI Object Storage service, a bucket is a container for storing objects in a compartment within an Object Storage namespace.

For more information, see:

• Complete list of OCI CLI Object commands
• Working with Oracle Cloud Storage from the Command Line

Uploading/downloading files

Objects can be uploaded from a file or from the command line (STDIN) and can be downloaded to a file or to the command line (STDOUT).

Upload an object (file)

oci os object put -ns <mynamespace> -bn <mybucket> --name myfile.txt --file /Users/me/myfile.txt --metadata '{"key1":"value1","key2":"value2"}'

Upload object contents (STDIN)

oci os object put -ns <mynamespace> -bn <mybucket> --name myfile.txt --file <--'object content'

Download an object (file)

oci os object get -ns <mynamespace> -bn <mybucket> --name myfile.txt --file /Users/me/myfile.txt

Output object contents (STDOUT)

oci os object get -ns <mynamespace> -bn <mybucket> --name myfile.txt --file –

Note: The “-“ parameter tells the file flag to output to STDOUT.

Misc

Get the base URL of object storage in home region

Bulk operations

Uploading files in a directory and all its subdirectories to a bucket

oci os object bulk-upload -ns <mynamespace> -bn <mybucket> --src-dir path/to/upload/directory

Downloading all objects in a bucket

oci os object bulk-download -ns <mynamespace> -bn <mybucket> --download-dir path/to/download/directory

Download all object that match a specified prefix

oci os object bulk-download -ns <mynamespace> -bn <mynamespace> --download-dir path/to/download/directory --prefix <myprefix>

Delete all objects in a bucket

oci os object bulk-delete -ns <mynamespace> -bn <mynamespace>

Delete objects that match the specified prefix

oci os object bulk-delete -ns <mynamespace> -bn <mynamespace>

 --prefix <myprefix>

Multipart operations

Uploads (large files)

Large files (>128 MiB) can be uploaded to Object Storage in multiple parts to speed up the upload. By default, large files are uploaded using multipart operations. You can override this default by using the --no-multipart option.

For more information about uploading large files, see: Using Multipart Uploads.

Related options for the oci os object put command:

• --no-multipart overrides an automatic multipart upload if the object is larger than 128 MiB. The object is uploaded as a single part, regardless of size.
• --part-size in MiB, to use in a multipart operation. The default part size is 128 MiB and a part size that you specify must be greater than 10 MiB. If the object is larger than the value specified by --part-size, it is uploaded in multiple parts.
• --parallel-upload-count, to specify the number of parallel operations to perform. You can use this value to balance resources and upload times. A higher value may improve times but consume more system resources and network bandwidth. The default value is 10.

Note: The oci cs object resume-put command allows you to resume a large file upload in cases where the upload was interrupted.

Downloads (large files)

Likewise, large files can be download from Object Storage in multiple parts to accelerate the process.

Related options for the oci os object get command:

• --multipart-download-threshold lets you specify the size, in MiB at which an object should be downloaded in multiple parts. This size must be at least 128 MiB.
• --part-size, in MiB, to use for a download part. This gives you the flexibility to use more (smaller size) or fewer (larger size) parts as appropriate for your requirements. For example, compute power and network bandwidth. The default minimum part size is 120 MiB.
• --parallel-download-count lets you specify how many parts are downloaded at the same time. A higher value may improve times but consume more system resources and network bandwidth. The default value is 10.

OKE (Container Engine for Kubernetes)

CLI reference for OKE

Clusters

Create a Kubernetes cluster

oci ce cluster create --compartment-id <compartmentID> --kubernetes-version <version> --name <clusterName> --vcn-id <VCN_OCID>

Delete a Kubernetes cluster

oci ce cluster delete --cluster-id <clusterOCID>

Generate token

Generate an ExecCredential based token for Kubernetes SDK/CLI authentication

oci ce cluster generate-token --cluster-id <clusterOCID>

List Kubernetes clusters in a compartment

oci ce cluster list --compartment-id <compartmentOCID>

Node-pools

Create node pool

oci ce node-pool create --cluster-id <clusterOCID> --compartment-id <compartmentID> --name <clusterName> --node-shape <nodeShapeName>

Delete node pool

oci ce node-pool delete --node-pool-id <nodePoolID>

Delete node

oci ce node-pool delete-node --node-id <computeInstanceID> --node-pool-id <nodePoolID>

List all pools in a compartment

oci ce node-pool list --compartment-id <compartmentID>

Automation

• Scheduling OCI CLI commands to run via a Kubernetes CronJob

Security

Threat Intelligence

When Cloud Guard is enabled in your tenancy, it provides threat detection using Threat Intelligence data.

The Threat Intelligence service is used to search for information about known threat indicators, including suspicious IP addresses, domain names, and other digital fingerprints.

For more information, see:

Overview of the Threat Intelligence service.

List threat indicators

oci threat-intelligence indicator-summaries list-indicators --compartment-id <compartmentID>

List threat indicators for a particular IP address

oci threat-intelligence indicator-summaries list-indicators --compartment-id <root_compartment_OCID> --type IP_ADDRESS --value <indicator_IP_address>

The supported indicator types are:

IP_ADDRESS, DOMAIN_NAME, URL, MD5_HASH, SHA1_HASH, SHA256_HASH, and FILE_NAME.

List threat indicators of a particular thread type and a minimum confidence score

oci threat-intelligence indicator-summaries list-indicators --compartment-id <root_compartment_OCID> --threat-type-name phishing --confidence-above 50

see: Threat Types or use:

oci threat-intelligence threat-types-collection list-threat-types --compartment-id <root_compartment_OCID>

Virtual Machine (VM) hosts

List VMs

Returns a list of dedicated virtual machine hosts that match the specified criteria in the specified compartment.

oci compute dedicated-vm-host list --compartment-id <compartment_OCID>

List VM host instances

oci compute dedicated-vm-host-instance list --compartment-id <compartment_OCID> --dedicated-vm-host-id <dedicatedVMhost_OCID>

Get information about a VM

oci compute dedicated-vm-host get --dedicated-vm-host-id <dedicatedVMhost_OCID>

Create a VM

oci compute dedicated-vm-host create --dedicated-vm-host-shape <shape_name> --wait-for-state ACTIVE --display-name <display_name> --availability-domain <availability_domain> --compartment-id <compartment_OCID>

where <shape_name> is the shape for the dedicated virtual machine host

Note: It can take up to 15 minutes for the dedicated virtual machine host to be fully created. It must be in the ACTIVE state before you can launch an instance on it.

Delete a VM

oci compute dedicated-vm-host delete --dedicated-vm-host-id <dedicated_VM_host_OCID>

Query the current state of a VM

oci compute dedicated-vm-host get --dedicated-vm-host-id <dedicatedVMhost_OCID>

Move a VM to another compartment

oci compute dedicated-vm-host change-compartment - -compartment-id <compartmentID> --dedicated-vm-host-id <dedicatedVMhost_OCID>

Other resources

DevOps Tools and Plug-Ins

• OCI Module for PowerShell
• Terraform Provider
• Ansible Collection
• Ansible OCI Guide

Open Source at Oracle

• Open Source at Oracle – Developer Resource Center
• Open Source at Oracle - GitHub resources

Scripts and Automation

Disclaimer: All code in this section should be considered as a proof-of-concept, used primarily for demonstration purposes, and is not supported by Oracle. The code here should not be used in its present form for Production purposes.

General

• OCI Scripts and example code (list of links, various contributors)

Contributors: Christophe Pauliat (cpauliat) and Çetin Ardal (kral2)

• OCI scripting with OCI CLI (pdf slide deck)

Note: parts of this could be used as a CHEAT SHEET, although there are few OCI CLI command examples (other than installation and upgrading).

Specific applications

• How to list all Oracle Cloud Infrastructure instances and their IP addresses

Contributor: Stephen Cross (Product Manager, Oracle Cloud Infrastructure)

• Oracle Cloud Infrastructure CLI Scripting: How to Quickly Override the Default Configuration

Contributor: Olaf Heimburger

Databases

• Automated CLI Scripts to Scale Autonomous Database CPUs

Contributor: Vivek Singh

• Automate Patching and Upgrade your Cloud Databases using OCI CLI

Contributor: Sinan Petrus Toma

• OCI Database Cloud Service Patching of Database and Grid Infrastructure Using OCI CLI

Contributor: Abhilash Kumar

Infrastructure

• OCI Bastion Service Part II: Create Bastion service using OCI CLI & Terraform

Contributor: Kosseila Hd

• IaC in the Cloud: Integrating Terraform and Resource Manager into your CI/CD Pipeline - Building with the OCI CLI

Contributor: Todd Sharp

SDKs

• SDKs for the CLI

Oracle Cloud Infrastructure provides several Software Development Kits (SDKs) and a Command Line Interface (CLI) to facilitate the development of custom solutions.

SDKs: Java, Python, TypeScript and JavaScript, .NET, Go, Ruby, PL/SQL

Note: The PL/SQL SDK enables you to write code to manage OCI resources. The latest PL/SQL SDK version is pre-installed by Oracle for all Autonomous Databases using shared Exadata infrastructure.

• Main Oracle Python SDK examples
• Automating developer setup in Oracle Cloud Infrastructure (Oracle blog)

Contributor: Philip Wilkins

Note: some of the images in this blog post from 2021 appear to be broken

Services

Anomaly Detection Service

• Access Anomaly Detection Service with OCI CLI
• Anomaly Detection Service

Databases

MySQL Database Service

• Manage MySQL Database Service (MDS) DB Systems with OCI CLI

Oracle Database Service

• Oracle Database on OCI
• OCI CLI db commands

IAM (Identity and Access Management)

• Calling OCI CLI Using Instance Principal

Vision

OCI Vision is a serverless, cloud-native service that provides deep learning-based, prebuilt, and custom computer vision models over REST APIs. OCI Vision helps you identify and locate objects, extract text, and identify tables, document types, and key-value pairs from business documents like receipts. No data science experience is required to use the prebuilt or custom features of OCI Vision.

You can access the service through the Oracle Cloud Console, OCI software developer kits (SDKs) in Python and Java, or the OCI CLI.

For more information, see:

• Service documentation and Tutorials
• SDKs and CLI
• Vision OCI CLI commands

Training

• Oracle LiveLabs

LiveLabs is the place to explore Oracle's products and services using workshops designed to enhance your experience building and deploying applications on the Cloud and On-Premises. Use your existing Oracle Cloud account, a Free Tier account, or a LiveLabs Sandbox reservation to build, test and deploy applications on Oracle's Cloud.

• OCI Workshops and Sprints
• Oracle Quick Start - Automated deployments of enterprise software on OCI

• Oracle Cloud Infrastructure – build your OCI knowledge with free digital training
• Oracle Help Center Learn – OCI CLI
• Oracle Learning Videos – OCI CLI