Using the CLI

This topic describes how to use the CLI to access Oracle Cloud Infrastructure and carry out service-related tasks. This topic assumes that you have configured the CLI and are ready to start using it.

Tip

The CLI has an interactive mode that provides automatic command completion and parameter information and suggestions. For more information, see Using Interactive Mode.

To explore further, Getting Started with the Command Line Interface provides an end-to-end walk-through of using the CLI to launch an instance.

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>

For example, this syntax is applied as follows:

  • compute is the <service>
  • instance is the resource <type>
  • launch is the <action>, and
  • the rest of the command string consists of <options>.

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

oci compute instance launch --availability-domain "EMIr:PHX-AD-1" -c ocid1.compartment.oc1..aaaaaaaal3gzijdlieqeyg35nz5zxil26astxxhqol2pgeyqdrggnx7jnhwa --shape "VM.Standard1.1"   --display-name "Instance 1 for sandbox" --image-id ocid1.image.oc1.phx.aaaaaaaaqutj4qjxihpl4mboabsa27mrpusygv6gurp47kat5z7vljmq3puq --subnet-id  ocid1.subnet.oc1.phx.aaaaaaaaypsr25bzjmjyn6xwgkcrgxd3dbhiha6lodzus3gafscirbhj5bpa

In the previous example, you can provide a friendly name for the instance using the --display-name option. Avoid entering confidential information.

Basic Examples

This section provides examples of basic operations using the CLI.

Note

Using Environment Variables for OCIDs

Several of the CLI examples use environment variables for OCIDs, such as:

  • $T for a tenancy OCID
  • $C for a compartment OCID

For example:

T=ocid1.tenancy.oc1..aaaaaaaaba3pv6wm2ytdrwrx32uzr4h25vkcr4jqae5f15p2b2qstifsfdsq
C=ocid1.compartment.oc1..aaaaaaaarhifmvrvuqtye5q66rck6copzqck3ukc5fldrwpp2jojdcypxfga

To get a namespace, run the following command.

oci os ns get

To list compartments, run the following command.

oci iam compartment list -c $T

To get a list of buckets, run the following command.

oci os bucket list -ns mynamespace --compartment-id $C

To list users and limit the output, run the following command.

oci iam user list --compartment-id $T --limit 5

To add a user to a group, run the following command.

oci iam group add-user --user-id ocid1.user.oc1..aaabcaaaxkkhhtmghvqqq7rgvzwuj3drwmtlsgz6sbfo7y4uc5sprzli377q --group-id ocid1.group.oc1..aaabcaaa66plootq6uuwwxhfdw2lsdqtgeb6l4pjsv5eeuenxrauujj35b7b

Getting Help with Commands

You can get help for any command using --help, -h, or -?. For example:

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

Viewing all the CLI Help

You can view the command line help.

Determining the Installed Version of the CLI

To get the installed version of the CLI, run the following command.

oci --version

Authenticating Using Instance Principals

Instance principals is an IAM service feature that enables instances to be authorized actors (or principals) that can perform actions on service resources. Each compute instance has its own identity, and it authenticates using the certificates that are added to it. These certificates are automatically created, assigned to instances and rotated, preventing the need for you to distribute credentials to your hosts and rotate them.

To enable instance principal authorization from the CLI, you can set the authorization option (--auth) for a command.

For example:

 oci os ns get --auth instance_principal

You can also enable instance principle authorization by setting the OCI_CLI_AUTH environment variable.

For example:
OCI_CLI_AUTH=instance_principal
Note

The value set for --auth parameter takes precedence over the environment variable.

For more information on instance principals, see Calling Services from an Instance.

Using a Proxy Server

The CLI uses HTTP requests to make calls to Oracle Cloud Infrastructure services. If you need to use a proxy server for outgoing HTTP requests in your environment, you can use one of the following methods:

Use the --proxy parameter on the command line

You can specify a proxy server on the command line by including the --proxy parameter when calling a CLI command.

For example:

oci os ns get --proxy https://<add your proxy URL here>/

Add a proxy entry to the CLI configuration file

For details, see Specifying a Proxy Server.

Use environment variables

Set the HTTP_PROXY and HTTPS_PROXY environment variables to point to your proxy server.

For example, on Linux:
https_proxy=https://<add your proxy URL here>/
http_proxy=http://<add your proxy URL here>/
On Windows, using PowerShell:
$Env:http_proxy = "http://<add your proxy URL here>/"

Using Dates and Times in CLI Commands

The CLI supports the following accepted date formats.

  • UTC with milliseconds

    Format: YYYY-MM-DDTHH:mm:ss.sssTZD, Example: 2017-09-15T20:30:00.123Z
  • UTC without milliseconds

    Format: YYYY-MM-DDTHH:mm:ssTZD, Example: 2017-09-15T20:30:00Z
  • UTC with minute precision

    Format: YYYY-MM-DDTHH:mmTZD, Example: 2017-09-15T20:30Z
  • Timezone with milliseconds

    Format: YYYY-MM-DDTHH:mm:ss.sssTZD, Example: 2017-09-15T12:30:00.456-08:00
  • Timezone without milliseconds

    Format: YYYY-MM-DDTHH:mm:ssTZD, Example: 2017-09-15T12:30:00-08:00
  • Timezone with offset with minute precision

    Format: YYYY-MM-DDTHH:mmTZD, Example: 2017-09-15T12:35-08:00
  • Date Only (This date will be taken as midnight UTC of that day)

    Format: YYYY-MM-DD, Example: 2017-09-15
  • Epoch seconds

    Example: 1412195400
Note

In our datetime formats, the T can be replaced with a space. For example, both "2017-09-15 20:30:00.123Z" and 2017-09-15T20:30:00.123Z are acceptable. (Note that if you do not include the T, you must wrap the value in quotes.) We also support time zones with and without the colon. Both +10:00 and +1000 are acceptable.

Managing CLI Input and Output

The CLI provides several options for managing command input and output.

Passing Complex Input

Complex input, such as arrays and objects with more than one value, are passed in JSON format and can be provided as a string at the command line, as a file, or as a command line string and as a file.

MacOS, Linux, or Unix

The following command shows how to pass two values for the --metadata object.

oci os bucket create -ns mynamespace --name mybucket --metadata '{"key1":"value1","key2":"value2"}' --compartment-id ocid1.compartment.oc1..<example>

Windows

On Windows, to pass complex input to the CLI as a JSON string, you must enclose the entire block in double quotes. Inside the block, each double quote for the key and value strings must be escaped with a backslash (\) character.

The following command shows how to pass two values for the --metadata object on Windows.

oci os bucket create -ns mynamespace --name mybucket --metadata "{\"key1\":\"value1\",\"key2\":\"value2\"}" --compartment-id ocid1.compartment.oc1..<example>
Note

JSON Errors

The error message "Parameter '<PARAMETER NAME>' must be in JSON format." indicates that the value you passed for the parameter with name "PARAMETER NAME" was not valid JSON. This error is typically a result of the JSON string not being escaped correctly.

For more information about using JSON strings, see Advanced JSON Options

Format Output as a Table

By default, all responses to a command are returned in JSON format. For example, a response like the following is returned when you issue the command to get a list of regions.

{
  "data": [
    {
      "key": "FRA",
      "name": "eu-frankfurt-1"
    },
    {
      "key": "IAD",
      "name": "us-ashburn-1"
    },
    {
      "key": "ICN",
      "name": "ap-seoul-1"
    },
    {
      "key": "PHX",
      "name": "us-phoenix-1"
    },
    {
      "key": "LHR",
      "name": "uk-london-1"
    },
    {
      "key": "NRT",
      "name": "ap-tokyo-1"
    },			
    {
      "key": "YYZ",
      "name": "ca-toronto-1"
    }				
  ]
}

In some cases, readability can become an issue, which is easily resolved by formatting a response as a table. To get a response to a command formatted as a table, run the following command.

oci iam region list --output table

The following sample list of regions is returned as a two column table.


+-----+----------------+
| key | name           |
+-----+----------------+
| FRA | eu-frankfurt-1 |
| IAD | us-ashburn-1   |
| ICN | ap-seoul-1     |
| PHX | us-phoenix-1   |
| NRT | ap-tokyo-1     |				
| LHR | uk-london-1    |
| YYZ | ca-toronto-1   |  
+-----+----------------+

Using Queries

You can filter output using the --query option for JSON. This option uses the JMESPath query language for JSON.

Filtering is very useful when dealing with large amounts of output. For example, the following command returns a list of all compartments:

oci iam compartment list --all

This command returns a lot of information. Some of the fields returned include compartment-id, name, lifecycle-state, and defined-tags.

Selecting Fields to Display

You can select just the fields you want by specifying the name of the array and the name of one or more fields, passed as a comma-delimted array:

<name of the array>[].[<the name of the field>]
Note

  • Field names are case-sensitive. Provide the name of the field exactly as it is specified in the JSON object.
  • If non-existing field names are specified, the query will include null in your output.
  • If the field names contain special characters or spaces, wrap the field name in escaped double quotes (\" for bash or \`" for PowerShell).
For example, to return just the name of the compartment and the lifecycle state:
oci iam compartment list --all --query "data[].[name, \"lifecycle-state\"]"
This will return output similar to the following:
[ 
  [
    "ATestCompartment",
    "ACTIVE"
  ],
  
  [
    "blocktest",
    "ACTIVE"
  ],
  [
    "ZestyTest",
    "ACTIVE"
  ]
]
You can also retrieve information as objects with customized field names:
<name of the array>[].{<your custom name>:<the name of the field>}
For example:
oci iam compartment list --all --query "data[].{Name:name, \"LifecycleState\":\"lifecycle-state\"}"
This will return output similar to the following:

[
  {
    "LifecycleState": "ACTIVE",
    "Name": "ATestCompartment"
  },
  {
    "LifecycleState": "ACTIVE",
    "Name": "blocktest"
  },
  {
    "LifecycleState": "ACTIVE",
    "Name": "ZestyTest"
  }
]

Specifying Search Conditions

You can specify a search condition for the returned information. For example, to only return a compartment named blocktest:
oci iam compartment list --all --query "data[?name=='blocktest']"
This will return information similar to the following:
[
  {
    "compartment-id": "ocid1.tenancy.oc1..<example_value>",
    "defined-tags": {
      "MySpecialTag": {
        "Phonebook": "software-development-kit"
      }
    },
    "description": "Compartment used by integration tests. 10000",
    "freeform-tags": {},
    "id": "ocid1.compartment.oc1..<example>",
    "inactive-status": null,
    "is-accessible": null,
    "lifecycle-state": "ACTIVE",
    "name": "blocktest",
    "time-created": "2018-06-19T17:08:46.059000+00:00"
  }
]
You can specify multiple search conditions. The following example retrieves the name and lifecycle status of compartments created before 2019 that have the tag MySpecialTag:
oci iam compartment list --all --query "data[?\"time-created\"<'2019'&&\"defined-tags\".MySpecialTag!=null].[name, \"lifecycle-state\"]"
This command will return output similar to the following:
[
  [
    "blocktest",
    "ACTIVE"
  ]
]

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

Advanced JSON Options

You can get the correct JSON format for command options and commands.

  • For a command option, use --generate-param-json-input and specify the command option that you want to get the JSON for. To generate the JSON for creating or updating a security rule, run the following command.

    oci network security-list create --generate-param-json-input ingress-security-rules
  • For an entire command, use --generate-full-command-json-input. To generate the JSON for launching an instance, run the following command.

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

Order of Precedence for JSON Input

The CLI supports combining arguments on the command line with file input. However, if the same values are provided in a file and on the command line, the command line takes precedence.

Using a JSON File for Complex Input

You can pass complex input from a file by referencing it from the command line. For Windows users, this removes the requirement of having to escape JSON text. You provide a path to the file using the file:// prefix.

Path Types

Using testfile.json as an example, the following types of paths are supported.

  • Relative paths from the same directory, for example: file://testfile.json and file://relative/path/to/testfile.json
  • Absolute paths on Linux, MacOS or Unix, for example: file:///absolute/path/to/testfile.json
  • Full file paths on Windows, for example: file://C:\path\to\testfile.json
Note

File Path Expansions

File path expansions, such as "~/", "./", and "../", are supported. On Windows, the "~/" expression expands to your user directory, which is stored in the %USERPROFILE% environment variable. Using environment variables in paths is also supported.

File Locations

The following file locations are supported.

  • Your home directory.

    oci os bucket create -ns mynamespace --name mybucket --compartment-id ocid1.compartment.oc1..aaaaaaaarhifmvrvuqtye5q66rck6copzqck3ukc5fldrwpp2jojdcypxfga --metadata file://~/testfile.json
  • The current directory.

    oci os bucket create -ns mynamespace --name mybucket --compartment-id ocid1.compartment.oc1..aaaaaaaarhifmvrvuqtye5q66rck6copzqck3ukc5fldrwpp2jojdcypxfga --metadata file://testfile.json
  • The /tmp directory (Linux, Unix, or MacOS).

    oci os bucket create -ns mynamespace --name mybucket --compartment-id ocid1.compartment.oc1..aaaaaaaarhifmvrvuqtye5q66rck6copzqck3ukc5fldrwpp2jojdcypxfga --metadata file:///tmp/testfile.json
  • The C:\temp directory (Windows).

    oci os bucket create -ns mynamespace --name mybucket --compartment-id ocid1.compartment.oc1..aaaaaaaarhifmvrvuqtye5q66rck6copzqck3ukc5fldrwpp2jojdcypxfga --metadata file://C:\temp\testfile.json

Examples of Using a JSON File as Input

The examples in this section use JSON that's generated for a command option and an entire command. The JSON is saved in a file, edited, and then used as command line input.

Use File Input for a Command Option

This end-to-end example shows how to generate the JSON for a security list id option used to create a subnet. The JSON is saved in a file, edited, and then used as command line input.

Response from the Command

[
  {
    "icmpOptions": {
      "code": 0,
      "type": 0
      },
    "isStateless": true,
    "protocol": "string",
    "source": "string",
    "tcpOptions": {
    "destinationPortRange": {
      "max": 0,
      "min": 0
      },
    "sourcePortRange": {
      "max": 0,
      "min": 0
      }
    },
    "udpOptions": {
    "destinationPortRange": {
      "max": 0,
      "min": 0
      },
    "sourcePortRange": {
      "max": 0,
      "min": 0
      }
    }
    },
    {
    "icmpOptions": {
      "code": 0,
      "type": 0
      },
    "isStateless": true,
    "protocol": "string",
    "source": "string",
    "tcpOptions": {
    "destinationPortRange": {
      "max": 0,
      "min": 0
      },
    "sourcePortRange": {
      "max": 0,
      "min": 0
      }
    },
    "udpOptions": {
    "destinationPortRange": {
      "max": 0,
      "min": 0
      },
    "sourcePortRange": {
      "max": 0,
      "min": 0
      }
    }
  }
]
Response from the Command
{
  "assignPublicIp": true,
  "availabilityDomain": "string",
  "compartmentId": "string",
  "displayName": "string",
  "extendedMetadata": {
  "string1": {
    "string1": "string",
    "string2": "string"
   },
  "string2": {
    "string1": "string",
    "string2": "string"
   }
  },
  "hostnameLabel": "string",
  "imageId": "string",
  "metadata": {
    "string1": "string",
    "string2": "string"
    },
  "privateIp": "string",
  "shape": "string",
  "skipSourceDestCheck": true,
  "subnetId": "string",
  "vnicDisplayName": "string"
}
Use a JSON File as Input for a Security List Option
  1. To generate the JSON for the security-list-ids option, run the following command.

    oci network subnet create --generate-param-json-input security-list-ids
  2. Create a file and add the following content, which was returned in step 1. This content doesn't have to be escaped or on a single line, it just has to contain valid JSON.

    [
      "string",
      "string"
    ]
  3. Edit the file and replace the "string" values with values, as shown in the following example.

    [
      "ocid1.securitylist.oc1.phx.aaaaaaaaw7c62ybv4676muq5tdrwup3v2maiquhbkbh4sf75tjcf5dm6kvlq",
      "ocid1.securitylist.oc1.phx.aaaaaaaa7snx4jh5drwo2h33rwcdqev6elir55hnrhi2yfndjfons5rcqk4q"
    ]
  4. Save the file as "security-list.json".
  5. To create the subnet using "security-list.json" as input, run the following command.

    oci network subnet create --vcn-id ocid1.vcn.oc1.phx.aaaaaaaa6wmuahgxejkv7ukyruqdrwlmrumtl6vyisxxxavagiqw2eeet2sa -c ocid1.compartment.oc1..aaaaaaaal3gzijdliedxxhqol2rggndrwyg35nz5zxil26astpgeyq7jnhwa  --availability-domain "EMIr:PHX-AD-1" --display-name TESTSUB --dns-label "testinstances" --cidr-block "10.0.0.0/16" --security-list-ids file://security-list.json

Use File Input for an Entire Command

This end-to-end example shows how to generate the JSON to create a virtual cloud network (VCN). The JSON is saved in a file, edited, and then used as command line input.

Use a JSON File as Input to Create a VCN
  1. To generate the JSON needed to create a VCN, run the following command.

    oci network vcn create --generate-full-command-json-input
  2. Create a file and add the following content, which was returned in step 1. This content doesn't have to be escaped or on a single line, it just has to contain valid JSON.

    {
      "cidrBlock": "string",
      "compartmentId": "string",
      "displayName": "string",
      "dnsLabel": "string"
    }
  3. Edit the file and replace the "string" values with values, as shown in the following example.

    {
      "cidrBlock": "10.0.0.0/16",
      "compartmentId": "ocid1.compartment.oc1..aaaaaaaal3gzijdliedxxhqol2rggndrwyg35nz5zxil26astpgeyq7jnhwa",
      "displayName": "TestVCN",
      "dnsLabel": "testdns"
    }
  4. Save the file and name it "create-vcn.json"
  5. To create the VCN using "create-vcn.json" as input, run the following command.
    oci network vcn create --from-json file://create-vcn.json 

Advanced Examples

The following examples show how you can use the CLI to complete complex tasks in Oracle Cloud Infrastructure.

Working with Object Storage

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

Uploading and 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:

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

Upload object contents from the command line (STDIN):

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

Download an object:

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

Print object contents to the command line (STDOUT):

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

Bulk Operations in Object Storage

The CLI supports the following bulk operations in Object Storage:

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

    # Upload all the files in a directory.
    oci os object bulk-upload -ns mynamespace -bn mybucket --src-dir path/to/upload/directory
  • Downloading all objects, or all the objects that match a specified prefix, in a bucket

    # Download all the objects.
    oci os object bulk-download -ns mynamespace -bn mybucket --download-dir path/to/download/directory
    						
    # Download all the objects that match the specified prefix.
    oci os object bulk-download -ns mynamespace -bn mybucket --download-dir path/to/download/directory --prefix myprefix
  • Deleting all objects, or all the objects that match a specified prefix, in a bucket

    # Delete all the objects.
    oci os object bulk-delete -ns mynamespace -bn mybucket
    			
    # Delete objects that match the specified prefix.
    oci os object bulk-delete -ns mynamespace -bn mybucket --prefix myprefix

Bulk operations support several options that let you:

  • Overwrite or skip files/objects using --overwrite or --no-overwrite. (Note: If you pass neither of these options you are prompted for confirmation every time there is something to overwrite.)
  • Limit delete, upload, or download operations using --prefix and/or --delimiter
  • Preview a bulk deletion with --dry-run

To get more information about the commands for bulk operations, run the following help commands:

# bulk-upload
oci os object bulk-upload -h
				
# bulk-download
oci os object bulk-download -h
				
# bulk-delete
oci os object bulk-delete -h

Multipart Operations in Object Storage

Multipart operations for Object Storage include object uploads and downloads.

Multipart Uploads

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

You can configure the following 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 --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.

The --resume-put command allows you to resume a large file upload in cases where the upload was interrupted.

Note

Multipart Uploads from STDIN

Objects uploaded from STDIN are uploaded in multiple parts. If the object content is smaller than 10 MiB, the upload is only 1 part, and the MultipartUpload API is used for the upload. Specifying --no-multipart when uploading from STDIN will result in an error.

The following example shows the command for a multipart upload if the object is larger than 200 MiB.

oci os object put -ns my-namespace -bn my-bucket --file path/to/large/file --part-size 200

For more information about multipart uploads, see Using Multipart Uploads.

Multipart Downloads

Large files can be downloaded from Object Storage in multiple parts to speed up the download.

You can configure the following 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.

The following example shows the command to download any object with a size greater than 500 MiB. The object is downloaded in 128 MiB parts.

oci os object get -ns my-namespace -bn my-bucket --name my-large-object --multipart-download-threshold 500 --part-size 128