Smyekh David-West

Posted on Aug 11 • Edited on Aug 15

How to Set Up Oracle Cloud Infrastructure (OCI) Locally and in VS Code: A Beginner's Guide

#cloud #oracle #vscode #devops

☁️ Pre-Flight Checklist

Before we taxi down the runway, here’s your flight plan. Keep this handy to navigate your flight path. Welcome aboard the cloud! ☁️

Enjoy your flight! ☁️

Diving into Oracle Cloud Infrastructure (OCI)? A powerful local development environment is key. This guide provides a complete, beginner-friendly walkthrough for setting up the OCI Command Line Interface (CLI) and integrating it seamlessly with Visual Studio Code.

By the end of this tutorial, you’ll be able to:

Install and configure the OCI CLI for powerful automation.
Authenticate securely using both long-term API keys and temporary session tokens.
Integrate OCI with VS Code to manage resources without leaving your editor.
Build a rock-solid foundation for real-world OCI development.

Whether you're studying for an OCI certification or starting a hands-on project, this setup is for you. The CLI gives you automation power, while the VS Code extension keeps resource management and development all in one place.

Prerequisites

Before we start, make sure you have the following:

An Oracle Cloud Account: An active OCI tenancy is required. The Free Tier is perfect for this guide and gives you always-free resources to experiment with.
Python 3.6+: The OCI CLI is a Python tool. It relies on Python libraries for secure communication and configuration parsing. You can check your version with:

python3 --version

Terminal Access: You'll need a command line. On macOS/Linux, use the built-in Terminal. On Windows, use PowerShell or Windows Terminal.
VS Code: While optional, this guide focuses on integrating the CLI with VS Code for the best developer experience.

Step 1: Install the OCI CLI

The OCI CLI is Oracle’s command-line tool for interacting with all OCI services. The quickest way to install it on macOS is with Homebrew.

First, update Homebrew and install the CLI:

brew update && brew install oci-cli

After the installation finishes, verify it was successful:

oci --version

If you see a version number, you're good to go!

Step 2: Configure the CLI with an API Key

Next, we'll create a configuration file and an API key. This key is a long-term credential that allows the CLI to authenticate with your OCI account.

Run the setup command:

oci setup config

This command will walk you through a series of prompts. Here’s how to answer them:

Config Location: Press Enter to accept the default location (/Users/your_user/.oci/config).
User OCID: Find this in the OCI Console. Click your Profile icon → User Settings → User Details. Copy the OCID and paste it here.
Tenancy OCID: Find this in the OCI Console. Click your Profile icon (top right) → Tenancy. Copy the OCID and paste it here.
Region: Enter your home region by index or name, for example, af-johannesburg-1 or the index number in the list provided.
Generate API Key: Type Y to generate a new RSA key pair.
Key Directory: Press Enter to save the keys in the default (/Users/your_user/.oci) directory. You will get a prompt saying, 'Public key written to: /Users/your_user/.oci/oci_api_key_public.pem.'’
Passphrase: You will be prompted to create a passphrase for your private key.
Once you’re done with the passphrase, the private key will be written to /Users/your_user/.oci/oci_api_key.pem, and the CLI will display your key's fingerprint.
Write your passphrase to the config file: Type Y, and the config is written to /Users/your_user/.oci/config.

Your local machine now has a key, but OCI doesn't know about it yet. We need to upload the public key to your OCI account.

For high security (recommended): Enter a strong passphrase. This encrypts your private key file on your disk. You will be prompted to enter it each time you run an OCI command, protecting your key if your computer is ever compromised.

For simplicity: You can leave this blank by pressing Enter twice or typing "N/A" for no passphrase. This is convenient for initial testing but is less secure.

Step 3: Upload Your Public API Key

The CLI created a private key (oci_api_key.pem) and a public key (oci_api_key_public.pem). You now need to upload the public key to your OCI user settings.

Go to the OCI Console.
Click your Profile icon (top right) and select User settings.
You’ll be directed to your profile page with all your user information and details
Select the tokens and keys tab, click Add API key
You’ll be given three options. ‘Generate API key pair’, ‘Choose public key file’ and ‘Paste a public key’
Select 'Choose public key' and click on 'Drop a file or select one’ option
This will open your system's file explorer. Navigate to the .oci folder inside your user's home directory and select the oci_api_key_public.pem file.
Once you upload the file, Click Add

OCI will then give you a Tenancy OCID, User OCID and Fingerprint.

These should already match what’s in your ~/.oci/config, but you can copy and check. Now your local CLI can securely communicate with OCI.

Tip: Files and folders starting with a dot (.) are hidden by default. To show them: Mac: Press Cmd + Shift + . in Finder. Windows: In File Explorer, go to View → Show → Hidden items. Linux: Press Ctrl + H in your file manager.

Step 4: Verify Your CLI Connection

Your CLI is now configured! Test it by running a simple command to get your Object Storage namespace.

oci os ns get

If the command returns a JSON object with your namespace data, your connection is working perfectly.

You should get this JSON response:

{
  "data": "mytenancynamespace"
}

That means your OCI CLI is fully installed, configured, and authenticated. "mytenancynamespace" is your Object Storage namespace, so your API key upload and config file are both working.

From here, you can:

Use the CLI directly for OCI resource management.
Install the OCI Toolkit for VS Code to interact with OCI without leaving your editor — it will use the exact same ~/.oci/configsetup you just made.

Step 5: Install and Configure the OCI Toolkit for VS Code

Now, let's bring OCI into your editor.

Open VS Code.
Go to the Extensions tab (the square icon in the sidebar).
Search for OCI Toolkit for VS Code and install the one published by Oracle. This installs all the sub-extensions at once. You can uninstall specific ones if you don’t need them.

This extension can use your existing API key, but for VS Code, it's better to use a temporary session-based token. This is more secure, as the token expires automatically.

In your VS Code terminal, run:

oci session authenticate

Follow the prompts:

Region: Enter your region again. (Pick the region that matches your OCI tenancy's home region.)
Browser Authentication: Your web browser will open to the Oracle Cloud login page. Sign in as you normally would.
Profile Name: After you authenticate, the CLI will display “Completed browser authentication process!” and ask for a profile name. Use something descriptive like vscode-session.

The CLI will confirm that the new profile has been written to your ~/.oci/config file. And then prompt you to try out your newly created session credentials with the following example command:

oci iam region list --config-file /Users/your_user/.oci/config --profile vs-code --auth security_token

If it works, you’ll see a list of all regions your tenancy has access to. This means your OCI CLI session authentication is working and your newly created profile is valid.

A Note on Security for Your Next Steps

For this guide and when exploring your Free Tier account, using your default administrator user is perfectly fine. However, as you move toward building real-world applications, it's crucial to follow the Principle of Least Privilege.

This means creating dedicated IAM users with policies that grant only the permissions necessary for a specific task. This practice minimises security risks.

And most importantly: NEVER commit your ~/.oci/config file or your .pem private keys to a Git repository. Add ~/.oci/ to your global .gitignore file to prevent this from happening accidentally.

Putting It All Together: Sync a Local Directory to the Cloud

Now for the fun part. Let's perform a task that showcases the true power of having the CLI at your fingertips. We will create a project folder on your local machine and upload it to an OCI Object Storage bucket with a single command.

Step 1: Create a Project Folder and Some Files Locally

First, let's create a directory with a few files, just as you would for any project.

# Create a new directory for our project
mkdir my-cloud-project

# Move into the directory
cd my-cloud-project

# Create a few files
echo "My project plan" > plan.txt
echo '<html><body><h1>Hello from OCI!</h1></body></html>' > index.html

mkdir assets
echo "Some important data" > assets/data.csv

You now have a simple project folder ready on your computer.

Step 2: Create an Object Storage Bucket in OCI

Next, use the CLI to create a new "bucket" to store your files in the cloud. You'll need your Compartment OCID for this. You can find it in the OCI console.

How to find your Compartment OCID: In the OCI console, navigate to Identity & Security, then click on Compartments. If you don’t have one, you can create one here. Click on the compartment you want to use and copy its OCID from the details page.

# Replace the compartment OCID with your own
oci os bucket create --name "my-project-backup" --compartment-id "ocid1.compartment.oc1..your_compartment_ocid"

Step 3: Sync Your Entire Folder to the Cloud

This is where the magic happens. Run the sync command to upload your entire local my-cloud-project directory to the bucket you just created. The CLI will automatically upload any new or modified files.

# Make sure you are still inside the my-cloud-project directory
# The '.' tells the CLI to sync the current directory
oci os object sync --bucket-name "my-project-backup" --src-dir .

Note: The oci os object sync command only uploads new or changed files to the bucket. It compares your local files with those already in Object Storage and skips files that haven’t changed, making it efficient for incremental backups.

The output will show you which files are being uploaded.

And that's it!

Go check the OCI Console. Navigate to Storage -> Buckets -> my-project-backup, and you will see your plan.txt, index.html, and the assets folder with data.csv inside, all perfectly replicated.

Why is this powerful?

With a single sync command, you synchronised an entire local folder with a cloud storage bucket. This is perfect for backing up project files, sharing assets, or even deploying a static website. Doing this through the web console would have required creating the bucket and then uploading each file one by one. The CLI automates it, saving you time and effort.

Now that you have the OCI CLI configured locally and integrated with VS Code, you can start automating your cloud workflows, manage resources faster, and explore OCI services right from your terminal or editor.

You're now equipped to build, automate, and manage your OCI resources like a pro.

Happy building! ⛅️

Cover Photo by BoliviaInteligente on Unsplash

DEV Community