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 get a list of buckets, run the following command.
Command
CopyTry It
oci os bucket list -ns mynamespace --compartment-id $C
To list users and limit the output, run the following command.
Command
CopyTry It
oci iam user list --compartment-id $T --limit 5
To add a user to a group, run the following command.
Command
CopyTry It
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:
To get the installed version of the CLI, run the following command.
Command
CopyTry It
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:
Command
CopyTry It
oci os ns get --auth instance_principal
You can also enable instance principle authorization by setting the
OCI_CLI_AUTH environment variable.
For example:
Copy
OCI_CLI_AUTH=instance_principal
Note
The value set for --auth parameter takes precedence over the environment variable.
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:
Copy
oci os ns get --proxy https://<add your proxy URL here>/
Date Only (This date will be taken as midnight UTC of that day)
Copy
Format: YYYY-MM-DD, Example: 2017-09-15
Epoch seconds
Copy
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.
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.
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.
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.
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.
Copy
oci iam region list --output table
The following sample list of regions is returned as a two column table.
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.
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.
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.
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"
]
Edit the file and replace the "string" values with values, as shown in the following example.
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.
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.
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:
Copy
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):
Copy
oci os object put -ns mynamespace -bn mybucket --name myfile.txt --file <--'object content'
Download an object:
Copy
oci os object get -ns mynamespace -bn mybucket --name myfile.txt --file /Users/me/myfile.txt
Print object contents to the command line (STDOUT):
Copy
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
Copy
# 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
Copy
# 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
Copy
# 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.
Copy
oci os object put -ns my-namespace -bn my-bucket --file path/to/large/file --part-size 200
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.
Copy
oci os object get -ns my-namespace -bn my-bucket --name my-large-object --multipart-download-threshold 500 --part-size 128