Month: August 2025

Mastering the OCI CLI: What It Does, Tips, Tricks, and Gotchas

The Oracle Cloud Infrastructure (OCI) Command Line Interface (CLI) is a powerful tool for managing OCI resources programmatically. It allows developers, DevOps engineers, and administrators to interact with Oracle Cloud services using scripts or direct commands, streamlining tasks like provisioning compute instances, managing storage, or configuring Kubernetes clusters. This blog post explores what the OCI CLI does, along with essential tips, tricks, and common gotchas to help you use it effectively.

What Does the OCI CLI Do?

The OCI CLI is a Python-based command-line tool that provides a programmatic interface to Oracle Cloud Infrastructure services. It allows you to:

  • Manage Resources: Create, update, and delete resources such as virtual machines, block volumes, object storage, and Kubernetes clusters.
  • Automate Tasks: Integrate OCI operations into CI/CD pipelines, scripts, or automation workflows.
  • Access Advanced Features: Perform operations not always available in the OCI Console, such as fine-grained control over resources or bulk operations.
  • Debug and Monitor: Use the --debug flag to troubleshoot issues or inspect API calls.

The CLI supports a wide range of OCI services, including Compute, Networking, Storage, Identity, and Container Engine for Kubernetes (OKE). It’s particularly useful for automating repetitive tasks, managing large-scale deployments, or accessing features programmatically.

Tips and Tricks for Using the OCI CLI

1. Simplify Installation with the Right Python Version

The OCI CLI requires Python 3.11 to function correctly. Using Python 3.10, 3.12, or 3.13 will result in installation failures due to compatibility issues (more on this in the “Gotchas” section). Ensure you have Python 3.11 installed before proceeding.

Tip: Use a version manager like pyenv to manage multiple Python versions and avoid conflicts:

pyenv install 3.11.0
pyenv global 3.11.0

2. Quick Setup with Config File

After installing the OCI CLI, configure it using:

oci setup config

This command generates a configuration file at ~/.oci/config and prompts you for details like user OCID, tenancy OCID, region, and API key. You can also create the file manually for scripted setups.

Tip: Use multiple profiles in the config file to manage different OCI accounts:

[DEFAULT]
user=ocid1.user.oc1..<user-ocid>
fingerprint=<fingerprint>
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..<tenancy-ocid>
region=us-phoenix-1

[SECOND_PROFILE]
user=ocid1.user.oc1..<another-user-ocid>
fingerprint=<another-fingerprint>
key_file=~/.oci/another_oci_api_key.pem
tenancy=ocid1.tenancy.oc1..<another-tenancy-ocid>
region=us-ashburn-1

Switch profiles with the --profile flag:

oci compute instance list --profile SECOND_PROFILE

3. Leverage JSON Output for Automation

The OCI CLI outputs results in JSON by default, making it ideal for scripting. Parse outputs with tools like jq:

oci compute instance list --compartment-id <compartment-ocid> | jq '.data[].id'

Tip: Use --output table for human-readable output during manual exploration:

oci compute instance list --output table

4. Use Environment Variables for Sensitive Data

Avoid hardcoding sensitive information in scripts. Set environment variables for credentials:

export OCI_CLI_USER=ocid1.user.oc1..<user-ocid>
export OCI_CLI_FINGERPRINT=<fingerprint>
export OCI_CLI_KEY_FILE=~/.oci/oci_api_key.pem
export OCI_CLI_TENANCY=ocid1.tenancy.oc1..<tenancy-ocid>
export OCI_CLI_REGION=us-phoenix-1

The CLI will automatically use these variables, reducing the risk of exposing credentials.

5. Debug with the --debug Flag

If a command fails, use the --debug flag to get detailed logs, including HTTP requests and responses:

oci ce cluster create-kubeconfig --cluster-id <cluster-ocid> --debug

This is invaluable for troubleshooting authentication or resource issues.

Gotchas to Watch Out For

1. Python Version Compatibility

The OCI CLI is strict about Python versions. Only Python 3.11 is supported. Using other versions results in errors:

    • Python 3.10 fails with a SameFileError during installation:
shutil.SameFileError: 'C:\\Program Files (x86)\\Oracle\\oci_cli\\Scripts\\create_backup_from_onprem.exe' and 'C:\\Program Files (x86)\\Oracle\\oci_cli\\scripts\\create_backup_from_onprem.exe' are the same file
    • Python 3.12 and 3.13 fail due to the removal of the distutils module:
ModuleNotFoundError: No module named 'distutils'

This issue has been reported to Oracle (see GitHub issue #968).

Workaround: Install Python 3.11 explicitly and verify the version:

python --version

2. Switching OCI Accounts

When switching between OCI accounts, the .oci directory in your home folder (~/.oci on Linux/Mac or C:\Users\<username>\.oci on Windows) can cause conflicts. If not updated, you may encounter 404 NotAuthorizedOrNotFound errors:

ServiceError: {"code": "NotAuthorizedOrNotFound", "message": "Authorization failed or requested resource not found."}

Workaround: Rename or remove the .oci directory before re-running oci setup config:

mv ~/.oci ~/.oci_backup
oci setup config

3. Cygwin Hangs with oci ce cluster create-kubeconfig

Running the oci ce cluster create-kubeconfig command in Cygwin can cause the command to hang after entering the passphrase:

Enter a passphrase for your private key ("N/A" for no passphrase): "N/A"

Workaround: Use PowerShell instead of Cygwin for this command:

oci ce cluster create-kubeconfig --cluster-id <cluster-ocid> --file $HOME/.kube/config --region us-phoenix-1 --token-version 2.0.0 --kube-endpoint PUBLIC_ENDPOINT

4. API Key Quota Limits

OCI imposes a limit of 3 API keys per user. Exceeding this limit results in an IdcsConversionError:

ServiceError: {"code": "IdcsConversionError", "message": "You can not create ApiKey as maximum quota limit of 3 has been reached.", "status": "400"}

Workaround: Remove unused API keys via the OCI Console:

  1. Navigate to Identity & Security > Users.
  2. Select your user and go to the API Keys section.
  3. Delete unnecessary keys to free up quota.

5. Config File Not Found in Cygwin

In Cygwin, you might see:

ERROR: Could not find config file at C:\Users\<username>\.oci\config

This happens because Cygwin uses a different home directory (/home/<username>). The CLI expects the config file in the Windows home directory.

Workaround: Copy the .oci directory to the Windows home directory or specify the config file explicitly:

oci --config-file /cygdrive/c/Users/<username>/.oci/config ...

Bonus: Advanced Tricks

1. Batch Operations with Scripts

Use loops in Bash or PowerShell to perform bulk operations. For example, to terminate multiple instances:

for instance in $(oci compute instance list --compartment-id <compartment-ocid> | jq -r '.data[].id'); do
    oci compute instance action --instance-id $instance --action TERMINATE
done

2. Use Aliases for Common Commands

Save time by creating aliases for frequently used commands:

alias oci-instances='oci compute instance list --compartment-id <compartment-ocid>'

Add this to your ~/.bashrc or ~/.zshrc for persistence.

3. Validate Inputs with --dry-run

Some OCI CLI commands support a --dry-run flag to simulate operations without making changes. Use it to verify your command before execution:

oci compute instance launch --dry-run --compartment-id <compartment-ocid> ...

Conclusion

The OCI CLI is a versatile tool for managing Oracle Cloud Infrastructure resources, but it comes with its share of nuances. By sticking to Python 3.11, managing your .oci directory carefully, and using PowerShell for specific commands like create-kubeconfig, you can avoid common pitfalls. Leverage tips like JSON parsing, environment variables, and debug mode to enhance your workflows. With these insights, you’ll be well-equipped to harness the full power of the OCI CLI for automation and resource management.

For more details, check the OCI CLI documentation or report issues on the OCI CLI GitHub.