Using the CLI

Viewing all the CLI Help

You can view the command line help.

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

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>

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:

oci iam compartment list --all --query "data[].[name, \"lifecycle-state\"]"

[ 
  [
    "ATestCompartment",
    "ACTIVE"
  ],
  
  [
    "blocktest",
    "ACTIVE"
  ],
  [
    "ZestyTest",
    "ACTIVE"
  ]
]

<name of the array>[].{<your custom name>:<the name of the field>}

oci iam compartment list --all --query "data[].{Name:name, \"LifecycleState\":\"lifecycle-state\"}"

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

Specifying Search Conditions

oci iam compartment list --all --query "data[?name=='blocktest']"

[
  {
    "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"
  }
]

oci iam compartment list --all --query "data[?\"time-created\"<'2019'&&\"defined-tags\".MySpecialTag!=null].[name, \"lifecycle-state\"]"

[
  [
    "blocktest",
    "ACTIVE"
  ]
]

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

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

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.

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.

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