OCI CLI install and setup: create your config, upload an API key and run your first commands

#The goal

You want to run oci commands from your own machine rather than clicking through the console. Setup takes about ten minutes. It needs a few IDs from the console and one key pair.

Tip

If you only need commands now and can't install anything, use Cloud Shell. The CLI is already there and already signed in.

#Step 1: install

On Linux or macOS:

bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"

Accept the defaults, then open a new shell so your PATH updates.

On Oracle Linux 8 or 9, you can use the package instead (the exact package name depends on your release):

sudo dnf -y install oraclelinux-developer-release-el8
sudo dnf -y install python36-oci-cli

On any system with a recent Python, in a virtual environment:

python3 -m venv ~/oci-venv
source ~/oci-venv/bin/activate
pip install oci-cli

On Windows PowerShell:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-WebRequest https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.ps1 -OutFile install.ps1
.\install.ps1 -AcceptAllDefaults

Check the version:

oci --version

#Step 2: collect three values

Find these in the console:

If you need a refresher on these terms, read compartments, OCIDs and regions.

#Step 3: run the setup wizard

oci setup config

It asks for each value in turn. Say yes when it offers to generate a new API signing key pair. It writes:

The finished config looks like this:

[DEFAULT]
user=ocid1.user.oc1..aaaaexample
fingerprint=12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef
tenancy=ocid1.tenancy.oc1..aaaaexample
region=ap-mumbai-1
key_file=~/.oci/oci_api_key.pem

#Step 4: upload the public key

Print it:

cat ~/.oci/oci_api_key_public.pem

In the console, open your user's profile, go to API keys (under Tokens and keys on newer pages), choose Add API key > Paste a public key, and paste the text. Include the BEGIN and END lines.

Check that the fingerprint shown by the console matches the one in your config.

Warning

A user can have only a limited number of API keys. Upload only the public key, and never email or commit the .pem private key.

#Step 5: test it

oci os ns get

This prints your Object Storage namespace. It needs no special permissions, so it's a clean test of your login.

A few more useful first commands:

oci iam region list --output table
oci iam availability-domain list --output table
oci iam compartment list --compartment-id-in-subtree true --all \
  --query "data[].{Name:name,State:\"lifecycle-state\"}" --output table

To list instances in a compartment:

export C=ocid1.compartment.oc1..aaaaexample
oci compute instance list --compartment-id "$C" \
  --query "data[].{Name:\"display-name\",State:\"lifecycle-state\",Shape:shape}" \
  --output table

Notice the escaped quotes. OCI field names contain hyphens, so --query needs them quoted. More of these are in the daily ops post.

#Fix common setup errors

Fix file permissions:

oci setup repair-file-permissions --file ~/.oci/config
oci setup repair-file-permissions --file ~/.oci/oci_api_key.pem

#Use several tenancies or regions

Add another section to ~/.oci/config:

[DR]
user=ocid1.user.oc1..aaaaexample
fingerprint=12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef
tenancy=ocid1.tenancy.oc1..aaaaexample
region=ap-hyderabad-1
key_file=~/.oci/oci_api_key.pem

Choose it per command:

oci os ns get --profile DR

Or change only the region for one call:

oci compute instance list --compartment-id "$C" --region ap-hyderabad-1

#Sign in with a browser instead

If you can't use API keys, a session token lasts about an hour and can be refreshed:

oci session authenticate --region ap-mumbai-1 --profile-name TOKEN
oci os ns get --profile TOKEN --auth security_token
oci session refresh --profile TOKEN

#Prevent it next time

• Rotate API keys on a schedule, and delete old ones from your user.
• On OCI compute, prefer instance principals to keeping a key on the server.
• Keep the ~/.oci directory out of Git and shared backups.
• If a key leaks, follow the leaked key response.