OCloud is a powerful command-line interface (CLI) tool designed to simplify interactions with Oracle Cloud Infrastructure (OCI). It provides a streamlined experience for exploring and retrieving information about common OCI services with a focus on usability, performance, and automation.
Whether you're exploring instances, working with databases, or need to quickly find resources across your OCI environment, OCloud offers an intuitive and efficient interface that works seamlessly with your existing OCI configuration.
- Instances: List, search, and explore compute instances with interactive TUI
- Images: Browse and search compute images
- OKE Clusters: List, search, and explore Kubernetes clusters with node pool details
- Autonomous Database: List, search, and explore ADB instances with interactive TUI
- HeatWave MySQL: List, search, and explore HeatWave database instances with interactive TUI
- OCI Cache Cluster: List, search, and explore OCI Cache Clusters (Redis/Valkey) with interactive TUI
- VCNs: Virtual Cloud Networks with gateways, subnets, NSGs, route tables, and security lists
- Subnets: Network subnet management
- Load Balancers: Explore and search load balancer configurations with health summaries
- Compartments: Navigate compartment hierarchy with tenancy-level scope support
- Policies: Explore IAM policies across compartments
- Bastion: Comprehensive bastion and session management
- List and explore existing bastions
- Create interactive bastion sessions with TUI-guided flows
- Connect to Compute Instances (Managed SSH & Port Forwarding)
- Connect to Databases (Autonomous DB & HeatWave via Port Forwarding)
- Connect to OKE Clusters (Managed SSH to nodes & Port Forwarding to API server)
- Connect to Load Balancers (Port Forwarding with TUI selection and health summaries)
- Enhanced privileged port handling with sudo password validation
- Automatic SSH tunnel management with background processes
- Interactive SSH key pair selection
- Automatic kubeconfig setup for OKE connections
- Object Storage: Comprehensive interactive TUI for bucket exploration and object management
- Browse and search buckets with tenancy-level scope support
- TUI-driven Uploads: Interactive file picker with automatic multipart upload for large files (>10MB)
- TUI-driven Downloads: Interactive bucket and object selection with local directory browser
- Real-time Progress: Visual progress bars for both upload and download operations
- Powerful Search: Fuzzy, prefix, and substring matching using Bleve indexing
- Interactive TUI: Navigate resources with the terminal user interface for select commands
- JSON Output: Consistent structured output across all commands
- Pagination: Unified pagination support (
--limit,--page) - Authentication: Interactive OCI Auth with automatic session refresh
- Tenancy Mapping: Friendly names for tenancies and compartments
# Add the tap
brew tap cnopslabs/ocloud https://github.com/cnopslabs/ocloud
# Install ocloud
brew install ocloudDownload the latest binary from the release page and place it in your PATH.
macOS/Linux:
# Move the binary to a directory in your PATH
mv ~/Downloads/ocloud ~/.local/bin
# For macOS, clear quarantine (if applicable)
sudo xattr -d com.apple.quarantine ~/.local/bin/ocloud
# Make executable
chmod +x ~/.local/bin/ocloud# Clone the repository
git clone https://github.com/cnopslabs/ocloud.git
cd ocloud
# Build and install
make build
make install- OCI CLI: Installed and configured (Quickstart guide)
- kubectl: For OKE cluster interactions (macOS | Linux)
- SSH Key Pair: Required for OCI Bastion sessions (
~/.ssh)
# View configuration and available commands
ocloud
# Authenticate with OCI
ocloud config session authenticate
# Search for compute instances
ocloud compute instance search "prod"
# Get HeatWave databases with pagination
ocloud database heatwave get --limit 10 --page 1
# Search Autonomous Databases in JSON format
ocloud database autonomous search "test" --json
# Interactive VCN list (TUI)
ocloud network vcn list
# Interactive object upload and download
ocloud storage object-storage upload
ocloud storage object-storage download
# Create bastion session with interactive TUI flow
ocloud identity bastion create
# List private Load Balancers and health status
ocloud network load-balancer listRunning ocloud without any arguments displays the configuration details and available commands.
Example output (values will vary by version, time, and your environment):
██████╗ ██████╗██╗ ██████╗ ██╗ ██╗██████╗
██╔═══██╗██╔════╝██║ ██╔═══██╗██║ ██║██╔══██╗
██║ ██║██║ ██║ ██║ ██║██║ ██║██║ ██║
██║ ██║██║ ██║ ██║ ██║██║ ██║██║ ██║
╚██████╔╝╚██████╗███████╗╚██████╔╝╚██████╔╝██████╔╝
╚═════╝ ╚═════╝╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝
Version: v0.1.10
Configuration Details: Valid until <timestamp>
OCI_CLI_PROFILE: DEFAULT
OCI_TENANCY_NAME: cloudops
OCI_COMPARTMENT_NAME: cnopslabsdev1
OCI_AUTH_AUTO_REFRESHER: ON [<pid>]
PORT_FORWARDING: ON [1521, 3306, 6443]
OCI_TENANCY_MAP_PATH: /Users/<name>/.oci/.ocloud/tenancy-map.yaml
Interact with Oracle Cloud Infrastructure
Usage:
ocloud [flags]
ocloud [command]
Available Commands:
compute Explore OCI compute services
config Configure ocloud CLI and authentication
database Explore OCI Database services
help Help about any command
identity Explore OCI identity services
network Explore OCI networking services
version Print the version information
Flags:
--color Enable colored log messages.
-c, --compartment string OCI compartment name
-d, --debug Enable debug logging
-h, --help help for ocloud (shorthand: -h)
-j, --json Output information in JSON format
--log-level string Set the log verbosity debug, (default "info")
-t, --tenancy-id string OCI tenancy OCID
--tenancy-name string Tenancy name
-v, --version Print the version number of ocloud CLI
OCloud can be configured in multiple ways, with the following precedence (highest to lowest):
- Command-line flags
- Environment variables
- OCI configuration file (
~/.oci/config)
| Variable | Description | Default |
|---|---|---|
OCI_CLI_PROFILE |
OCI configuration profile | DEFAULT |
OCI_TENANCY_NAME |
Tenancy name (looked up in tenancy map) | - |
OCI_COMPARTMENT |
Compartment name | - |
OCI_REGION |
OCI region | - |
OCI_TENANCY_MAP_PATH |
Path to tenancy mapping file | ~/.oci/.ocloud/tenancy-map.yaml |
OCloud provides interactive authentication with automatic session refresh:
# Authenticate with OCI
ocloud config session authenticate
# Filter regions by prefix (e.g., us, eu, ap)
ocloud config session authenticate --filter us
# Filter by realm (e.g., OC1, OC2)
ocloud config session authenticate --realm OC1The OCI Auth Refresher is a background service that automatically refreshes your OCI session before it expires, keeping your session active for long-running operations. Status is displayed in configuration output: OCI_AUTH_AUTO_REFRESHER: ON [PID].
Map tenancy names to OCIDs using ~/.oci/.ocloud/tenancy-map.yaml:
- environment: Prod
tenancy: cncloudps
tenancy_id: ocid1.tenancy.oc1..aaaaaaaawdfste4i8fdsdsdkfasfds
realm: OC1
compartments:
- sandbox
- production
regions:
- us-chicago-1
- us-ashburn-1View tenancy mapping:
ocloud config info map-file
ocloud config info map-file --realm OC1 --json| Flag | Short | Description |
|---|---|---|
--compartment |
-c |
OCI compartment name |
--tenancy-name |
Tenancy name | |
--debug |
-d |
Enable debug logging |
--json |
-j |
Output in JSON format |
--help |
-h |
Display help |
--version |
-v |
Print version |
--color |
Enable colored output | |
--log-level |
Set verbosity (debug, info, warn, error) |
| Flag | Short | Description |
|---|---|---|
--json |
-j |
JSON output format |
--all |
-A |
Include all related information |
--limit |
-m |
Records per page (default: 20) |
--page |
-p |
Page number (default: 1) |
--scope |
compartment (default) or tenancy |
|
--tenancy-scope |
-T |
Force tenancy-level scope |
Some identity commands support compartment or tenancy scope:
# Compartments
ocloud identity compartment get # configured compartment (default)
ocloud identity compartment get --scope tenancy # whole tenancy
ocloud identity compartment get -T # same as above
# Policies
ocloud identity policy get --scope compartment
ocloud identity policy search prod -TFor VCN commands, include specific resources or use --all:
| Flag | Short | Description |
|---|---|---|
--gateway |
-G |
Internet/NAT gateways |
--subnet |
-S |
Subnets |
--nsg |
-N |
Network security groups |
--route-table |
-R |
Route tables |
--security-list |
-L |
Security lists |
--all |
-A |
All of the above |
Examples:
# Get VCNs with all related resources
ocloud network vcn get --all
ocloud network vcn get -G -S -N -R -L
# Search VCNs with JSON output
ocloud network vcn search prod -A -jOCloud provides comprehensive bastion session management with interactive TUI-guided flows for secure access to OCI resources.
The ocloud identity bastion create command launches an interactive flow that guides you through:
- Session Type Selection: Choose between Bastion management or creating a new session
- Bastion Selection: Pick from your active bastions via TUI
- Target Type Selection: Choose your connection target (Instance, Database, OKE, or Load Balancer)
- Session Type: Select Managed SSH or Port Forwarding
- Resource Selection: Interactive TUI to pick the specific resource
- SSH Key Selection: Choose your SSH key pair from
~/.ssh - Connection Setup: Automatic tunnel creation and configuration
Managed SSH: Direct interactive SSH session to compute instances
ocloud identity bastion create
# Select: Session → Choose Bastion → Instance → Managed SSH → Pick Instance → Select KeysPort Forwarding: Create an SSH tunnel to instance ports (e.g., VNC, RDP, custom apps)
ocloud identity bastion create
# Select: Session → Choose Bastion → Instance → Port Forwarding → Pick Instance → Enter Port
# SSH tunnel runs in background, logs written to ~/.oci/.ocloud/logs/Autonomous Database: Secure port forwarding to Autonomous DB private endpoints
ocloud identity bastion create
# Select: Session → Choose Bastion → Database → Autonomous → Pick ADB → Enter Port (default: 1521)
# Tunnel runs in background, connect to localhost:<port>HeatWave MySQL: Secure port forwarding to HeatWave database instances
ocloud identity bastion create
# Select: Session → Choose Bastion → Database → HeatWave → Pick HeatWave DB → Enter Port (default: 3306)
# Tunnel runs in background, connect to localhost:<port>Managed SSH to Node: Direct SSH access to OKE worker nodes
ocloud identity bastion create
# Select: Session → Choose Bastion → OKE → Managed SSH → Pick Cluster → Pick Node → Select KeysPort Forwarding to API Server: Access Kubernetes API server via bastion
ocloud identity bastion create
# Select: Session → Choose Bastion → OKE → Port Forwarding → Pick Cluster → Enter Port (default: 6443)
# Automatically offers to create/merge kubeconfig
# kubectl commands work via the tunnel to localhost:<port>Port Forwarding: Secure access to private Load Balancers with TUI-guided selection and health summaries
ocloud identity bastion create
# Select: Session → Choose Bastion → Load Balancer → Pick LB → Enter Port (default local: 8443, target: 443)
# Note: Supports privileged local ports (e.g., 443) with sudo password validation- Tunnels run as background processes and persist after CLI exits
- Logs written to
~/.oci/sessions/<profile>/logs/ssh-tunnel-<port>-<date>.log - State tracking in
~/.oci/sessions/<profile>/tunnel/tunnel-<port>.json - Automatic port availability checking
- Privileged port support: Secure handling of ports < 1024 with sudo password validation
- Connection verification with a 30-second timeout
ocloud identity bastion get # List all bastions in compartment
ocloud identity bastion get --json # JSON output# Instances
ocloud compute instance get
ocloud compute instance list # Interactive TUI
ocloud compute instance search "roster" --json
ocloud comp inst s "roster" -j
# Images
ocloud compute image get --limit 10
ocloud compute image list # Interactive TUI
ocloud compute image search "Oracle-Linux"
ocloud comp img s "Oracle-Linux" -j
# OKE Clusters
ocloud compute oke get
ocloud compute oke list # Interactive TUI
ocloud compute oke search "orion" --json# Autonomous Database
ocloud database autonomous get --limit 10 --page 1
ocloud database autonomous list # Interactive TUI
ocloud database autonomous search "test" --json
ocloud db adb s "test" -j
# HeatWave MySQL
ocloud database heatwave get --all
ocloud database heatwave list # Interactive TUI
ocloud database heatwave search "prod" --json
ocloud db hw s "8.4" -j
# OCI Cache Cluster (Redis/Valkey)
ocloud database cache-cluster get --all
ocloud database cache-cluster list # Interactive TUI
ocloud database cache-cluster search "prod" --json
ocloud db cc s "VALKEY_7_2" -j
# Alternative aliases: cachecluster, cc# VCNs
ocloud network vcn get --all
ocloud network vcn list # Interactive TUI
ocloud network vcn search "prod" -A -j
# Load Balancers
ocloud network load-balancer get
ocloud network load-balancer list # Interactive TUI
ocloud network load-balancer search "prod" --all
ocloud net lb s "prod" -A -j
# Subnets
ocloud network subnet list # Interactive TUI
ocloud network subnet find "pub" --json# Compartments
ocloud identity compartment get
ocloud identity compartment list # Interactive TUI
ocloud identity compartment get -T # Tenancy scope
ocloud identity compartment search "sandbox" --json
# Policies
ocloud identity policy get
ocloud identity policy list # Interactive TUI
ocloud identity policy search "monitor" -T
# Bastion
ocloud identity bastion get # List existing bastions
ocloud identity bastion create # Interactive bastion session creation
ocloud ident b create # Short alias# Object Storage
ocloud storage object-storage get
ocloud storage object-storage search "prod" --json
ocloud storage object-storage list # Interactive TUI list
ocloud storage object-storage upload # Interactive TUI-driven upload
ocloud storage object-storage download # Interactive TUI-driven download
ocloud storage os s "prod" -jConnect to a private Autonomous Database through a bastion session:
# 1. Authenticate with OCI
ocloud config session authenticate
# 2. Create bastion session with interactive flow
ocloud identity bastion create
# Select: Session → Choose Active Bastion → Database → Autonomous → Pick ADB
# The tunnel runs in the background on localhost:1521 (or custom port)
# 3. Connect using SQL client
sqlplus admin@localhost:1521/mydb_highAccess a private OKE cluster's API server through port forwarding:
# Create port forwarding session to OKE API server
ocloud identity bastion create
# Select: Session → Choose Bastion → OKE → Port Forwarding → Pick Cluster
# Accept kubeconfig creation/merge when prompted
# Tunnel runs in background, kubectl now works via localhost:6443
kubectl get nodes
kubectl get pods --all-namespacesInteractive SSH session to a private compute instance:
ocloud identity bastion create
# Select: Session → Choose Bastion → Instance → Managed SSH → Pick Instance
# Provides direct interactive SSH shellCombine search with bastion for quick access:
# 1. Search for HeatWave databases
ocloud database heatwave search "prod" --json | jq '.[] | select(.lifecycleState=="ACTIVE")'
# 2. Create connection to selected database
ocloud identity bastion create
# Select: Session → Bastion → Database → HeatWave → Pick the prod DB
# Tunnel established to localhost:3306
# 3. Connect with MySQL client
mysql -h 127.0.0.1 -P 3306 -u admin -pEffortlessly manage your files in OCI Object Storage with TUI-guided flows:
ocloud storage object-storage upload
# 1. Select destination bucket from list
# 2. Browse local filesystem to pick a file
# 3. Monitor upload progress (multipart used for files >10MiB)ocloud storage object-storage download
# 1. Select source bucket
# 2. Pick object(s) from the bucket list
# 3. Choose local destination and monitor download progress| Command | Description |
|---|---|
make build |
Build the binary to bin/ocloud |
make install |
Install to $GOPATH/bin |
make test |
Run all tests with coverage |
make fmt |
Format Go source files |
make vet |
Run go vet static analysis |
make lint |
Run golangci-lint |
make vuln |
Run govulncheck |
make clean |
Remove build artifacts |
make release |
Build for all platforms and create archives |
Run the comprehensive test script that covers all command categories:
./test_ocloud.shThe script tests:
- Root commands and global flags
- Configuration commands (info, map-file, session)
- Compute commands (instance, image, oke)
- Identity commands (compartment, policy)
- Network commands (subnet, vcn, load-balancer)
- Storage commands (object-storage)
- Database commands (autonomous, heatwave, cache-cluster)
- Interactive TUI Commands: Use
q,Esc, orCtrl+Cto quit. Exiting without selection is graceful. - Search Patterns: Searches support fuzzy matching, so typos and partial matches work.
- JSON Output: Use
--jsonfor scripting and automation. - Debug Logging: Run with
--log-level debugor-dfor troubleshooting. - Colored Output: Use
--colorfor better readability in terminals. - Bastion Tunnels: Background SSH tunnels persist after CLI exits. Check logs in
~/.oci/sessions/<profile>/logs/if connection fails. - OKE Access: Port forwarding to the OKE API server automatically offers kubeconfig setup for seamless kubectl access.
- Database Connections: Use bastion port forwarding for secure access to private Autonomous DB and HeatWave instances without exposing public endpoints.
OCloud provides detailed error messages with configurable log levels:
--log-level debug: Most verbose, shows all logs (equivalent to-d)--log-level info: Default, shows standard information--log-level warn: Warnings and errors only--log-level error: Errors only
Enable colored output with --color for better visibility.
We welcome contributions! See CONTRIBUTING.md for:
- Development setup and architecture overview
- Coding standards and testing requirements
- Data flow patterns across domain, mapping, services, and cmd layers
Use our GitHub Issue Forms for faster triage:
- Bug Report: Include command(s), environment details, region/tenancy context, and debug logs
- Feature Request: Describe CLI UX impact and affected layers
Open a new issue
Tips for bug reports:
- Run with
--log-level debugand include relevant logs (redact secrets) - Provide exact command(s), flags, OS/arch, and
ocloud versionoutput
For questions, use Discussions
This project is licensed under the MIT License—see the LICENSE file for details.
OCloud uses third-party open-source software, including:
- Oracle Cloud Infrastructure Go SDK - Dual-licensed under UPL-1.0 or Apache-2.0 Copyright (c) 2016, 2024, Oracle and/or its affiliates
For a complete list of third-party software and their licenses, see:
- NOTICE - Third-party software notices and attributions
- third_party/ - Full license texts for dependencies