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.
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.
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.
OCI_CLI_AUTH=instance_principal
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.
https_proxy=https://<add your proxy URL here>/
http_proxy=http://<add your proxy URL here>/
$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
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
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>
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>]
- 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).
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>}
For
example: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
blocktest
: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.
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
andfile://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 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.
[
{
"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
}
}
}
]
{
"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"
}
-
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
-
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.
[ "ocid1.securitylist.oc1.phx.aaaaaaaaw7c62ybv4676muq5tdrwup3v2maiquhbkbh4sf75tjcf5dm6kvlq", "ocid1.securitylist.oc1.phx.aaaaaaaa7snx4jh5drwo2h33rwcdqev6elir55hnrhi2yfndjfons5rcqk4q" ]
- Save the file as "security-list.json".
-
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.
-
To generate the JSON needed to create a VCN, run the following command.
oci network vcn create --generate-full-command-json-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.
{ "cidrBlock": "string", "compartmentId": "string", "displayName": "string", "dnsLabel": "string" }
-
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" }
- Save the file and name it "create-vcn.json"
-
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.
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