🧰 The Oracle Cloud CLI (oci): Config File, API Keys, Sessions and Query

How oci is organized, what oci setup config writes (and why that key file matters), profiles and browser sessions, JMESPath queries with the data wrapper and the built-in canned queries, and offline help

💡 How this page was tested. On 6 October 2026 I installed the Oracle Cloud CLI 3.94.2 with pip in a virtual environment, and ran everything that works without a real account: the version, the error when no configuration exists, the whole oci setup config walkthrough (with made-up OCIDs, so the file and the key it creates are real but useless), the oci_cli_rc file, and the offline help. Anything that talks to Oracle is marked from the documentation, not run here. The sibling pages: az, aws, gcloud and the comparison.

What oci is

oci is the Oracle Cloud Infrastructure command-line interface. Its own help explains the shape: "Most commands must specify a service, followed by a resource type and then an action. For example, to list users: oci iam user list --compartment-id $T" (where $T holds the OCID of the tenancy). So: oci compute instance list, oci os bucket create, oci iam compartment create. "Output is in JSON format."

The two things that make oci feel different from the others:

  1. OCIDs everywhere. Almost every command wants the OCID of a compartment (--compartment-id) or of a resource (see the account page). Keep them in shell variables.
  2. A key pair, not a login. The classic way to authenticate is an API signing key: a private key on your machine, whose public half you upload to your user in the console.

Getting it

python3 -m venv venv-oci
venv-oci/bin/pip install oci-cli

(Oracle also offers an installer script: from the documentation, not run here.) Or skip installing: Cloud Shell in the OCI console has the CLI already authenticated. The version, and what an unconfigured oci says:

user@lab:~$ oci --version
3.94.2
user@lab:~$ oci iam region list
ERROR: Could not find config file at ~/.oci/config
Do you want to create a new config file? [Y/n]: Abort:
user@lab:~$ oci session --help | sed -n 1,10p
Usage: oci session [OPTIONS] COMMAND [ARGS]...

  Session commands for CLI

Options:
  -?, -h, --help  For detailed help on any of these individual commands, enter
                  <command> --help.

Commands:
  authenticate  Creates a CLI session using a browser based login flow.
  export        Exports a CLI session into a zip that can be imported.
  import        Imports a CLI session from an archive.
  refresh       Refreshes a CLI session
  terminate     Terminates a CLI session by removing the entry from the...
  validate      Tests whether a CLI session is still valid

The config file: oci setup config

oci setup config is an interactive walkthrough. It asks for a location for the config file, your user OCID, your tenancy OCID, a region (it prints a numbered list, and you can type the name), whether to generate a new API signing key pair, where to keep the keys, and a passphrase. I ran it with made-up OCIDs:

user@lab:~$ oci setup config
[...the walkthrough asks for: a location for the config, your user OCID,
 your tenancy OCID, a region (it prints a numbered list), whether to generate
 a new API signing key pair, where to keep it, and a passphrase ("N/A" for none)...]
Private key written to: ~/.oci/oci_api_key.pem
Fingerprint: 0c:9c:91:c4:cf:6d:65:43:63:2b:02:ca:77:8c:e7:2d
Config written to ~/.oci/config

    If you haven't already uploaded your API Signing public key through the
    console, follow the instructions on the page linked below in the section
    'How to upload the public key':

        https://docs.cloud.oracle.com/Content/API/Concepts/apisigningkey.htm#How2

user@lab:~$ cat ~/.oci/config
[DEFAULT]
user=ocid1.user.oc1..aaaaaaaaexampleuser
fingerprint=0c:9c:91:c4:cf:6d:65:43:63:2b:02:ca:77:8c:e7:2d
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaaexampletenancy
region=eu-frankfurt-1
user@lab:~$ ls -l ~/.oci
total 12
-rw------- 1 user user  260 Oct  6 16:15 config
-rw------- 1 user user 1715 Oct  6 16:15 oci_api_key.pem
-rw------- 1 user user  451 Oct  6 16:15 oci_api_key_public.pem

A login without a key: sessions

If you would rather not keep a long-lived key, the CLI has session commands, as the real help shows:

Output and query

And Oracle includes ready-made queries. oci setup oci-cli-rc writes a file of aliases and predefined ("canned") queries. This ran for real:

user@lab:~$ oci setup oci-cli-rc
user@lab:~$ head -n 16 ~/.oci/oci_cli_rc
[OCI_CLI_CANNED_QUERIES]
# For list results, this gets the ID and display-name of each item in the list.
get_id_and_display_name_from_list=data[*].{id: id, "display-name": "display-name"}

get_id_and_display_name_from_single_result=data.{id: id, "display-name": "display-name"}

# Filters where the display name contains some text
filter_by_display_name_contains_text=data[?contains("display-name", `your_text_here`)]

# Get the top 5 results from a list operation
get_top_5_results=data[:5]

# List instance public IPs from list vnics response
# Example: oci compute instance list-vnics --instance-id $I --query query://list_public_ips
list_public_ips=data[?"public-ip" != null]."public-ip"

You use one with --query query://NAME. For example (from the file's own comment): oci compute instance list-vnics --instance-id $I --query query://list_public_ips. Read the queries themselves, because they are a good JMESPath lesson: data[*].{id: id, "display-name": "display-name"} builds a small object per item, data[?contains("display-name", 'text')] filters by name, and data[:5] takes the first five.

Help, with no account

Habits that save you

The cheat sheet

← The Google Cloud CLI (gcloud): Sign In, Configurations, Format and Filter · ↑ All tutorials · Four Cloud CLIs Side by Side: az, aws, gcloud and oci →

© 2026 TechCommune. All rights reserved.
"The OCI CLI wants three OCIDs and a key. Once you have written them down, it is a pleasant tool."