--- name: oraclecloud-local-dev-loop description: | Set up a productive local OCI development workflow using CLI and SDK instead of the web console. Use when the OCI Console is too slow, setting up CLI profiles, or building shell aliases for common operations. Trigger with "oci local dev", "oci cli setup", "oraclecloud dev workflow", "avoid oci console". allowed-tools: Read, Write, Edit, Bash(pip:*), Bash(oci:*), Grep version: 1.0.0 license: MIT author: Jeremy Longshore tags: [saas, oraclecloud, oci] compatible-with: claude-code --- # Oracle Cloud Local Dev Loop ## Overview The OCI web console is slow, hard to navigate, and requires dozens of clicks for common operations. A local dev workflow using the OCI CLI and Python SDK replaces the console for everything: listing resources, launching instances, managing object storage, and checking service health. Profile switching lets you target dev/staging/prod from the same terminal. **Purpose:** Set up a complete local OCI development environment with CLI profiles, shell aliases, environment variable management, and common workflow scripts that eliminate the need for the web console. ## Prerequisites - **Completed `oraclecloud-install-auth`** — valid `~/.oci/config` with at least one profile - **Python 3.8+** with `pip install oci oci-cli` - **Bash or Zsh** shell - OCIDs for your compartments (Governance > Compartments in the Console — last time you need it) ## Instructions ### Step 1: Install and Verify the OCI CLI ```bash pip install oci-cli # Verify installation oci --version # Quick connectivity test oci iam region list --output table ``` ### Step 2: Set Up Multiple Profiles Edit `~/.oci/config` with profiles for each environment: ```ini [DEFAULT] user=ocid1.user.oc1..aaaa_YOUR_USER fingerprint=ab:cd:ef:12:34:56:78:90:ab:cd:ef:12:34:56:78:90 tenancy=ocid1.tenancy.oc1..aaaa_PROD_TENANCY region=us-ashburn-1 key_file=~/.oci/oci_api_key.pem [dev] user=ocid1.user.oc1..aaaa_YOUR_USER fingerprint=ab:cd:ef:12:34:56:78:90:ab:cd:ef:12:34:56:78:90 tenancy=ocid1.tenancy.oc1..aaaa_DEV_TENANCY region=us-phoenix-1 key_file=~/.oci/oci_api_key_dev.pem [staging] user=ocid1.user.oc1..aaaa_YOUR_USER fingerprint=12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef tenancy=ocid1.tenancy.oc1..aaaa_STAGING_TENANCY region=eu-frankfurt-1 key_file=~/.oci/oci_api_key_staging.pem ``` Switch profiles with the `--profile` flag or `OCI_CLI_PROFILE` env var: ```bash # CLI flag oci compute instance list --compartment-id --profile dev # Environment variable (applies to all commands in session) export OCI_CLI_PROFILE=dev oci compute instance list --compartment-id ``` ### Step 3: Environment Variables and .env File Create a project `.env` file for compartment OCIDs and region defaults: ```bash # .env — OCI project configuration (NEVER commit this file) OCI_COMPARTMENT_ID="ocid1.compartment.oc1..aaaa_YOUR_COMPARTMENT" OCI_TENANCY_ID="ocid1.tenancy.oc1..aaaa_YOUR_TENANCY" OCI_REGION="us-ashburn-1" OCI_CLI_PROFILE="DEFAULT" ``` ```bash # Add to .gitignore echo ".env" >> .gitignore # Source in your shell source .env ``` ### Step 4: Shell Aliases for Common Operations Add these to your `~/.bashrc` or `~/.zshrc`: ```bash # --- OCI Shell Aliases --- # Profile switching alias oci-dev='export OCI_CLI_PROFILE=dev && echo "Switched to dev"' alias oci-staging='export OCI_CLI_PROFILE=staging && echo "Switched to staging"' alias oci-prod='export OCI_CLI_PROFILE=DEFAULT && echo "Switched to prod"' # Compute alias oci-instances='oci compute instance list --compartment-id $OCI_COMPARTMENT_ID --output table --query "data[*].{Name:\"display-name\",State:\"lifecycle-state\",Shape:shape,OCID:id}"' alias oci-running='oci compute instance list --compartment-id $OCI_COMPARTMENT_ID --lifecycle-state RUNNING --output table' # Object Storage alias oci-buckets='oci os bucket list --compartment-id $OCI_COMPARTMENT_ID --output table --query "data[*].{Name:name,Created:\"time-created\"}"' # Networking alias oci-vcns='oci network vcn list --compartment-id $OCI_COMPARTMENT_ID --output table' alias oci-subnets='oci network subnet list --compartment-id $OCI_COMPARTMENT_ID --output table' # IAM alias oci-whoami='oci iam user get --user-id $(grep ^user ~/.oci/config | head -1 | cut -d= -f2) --query "data.{Name:name,Email:email}" --output table' # Health check alias oci-health='oci iam region list --output table && echo "OCI connectivity OK"' ``` ### Step 5: Common CLI Workflows **List and filter resources with JMESPath queries:** ```bash # Instances by shape oci compute instance list --compartment-id $OCI_COMPARTMENT_ID \ --query "data[?shape=='VM.Standard.A1.Flex'].{Name:\"display-name\",State:\"lifecycle-state\"}" \ --output table # Buckets with size (requires additional call per bucket) oci os bucket list --compartment-id $OCI_COMPARTMENT_ID \ --query "data[*].name" --raw-output # Find an image by name oci compute image list --compartment-id $OCI_COMPARTMENT_ID \ --query "data[?contains(\"display-name\", 'Oracle-Linux-8')].{Name:\"display-name\",ID:id}" \ --output table --limit 5 ``` **Instance lifecycle from CLI:** ```bash # Launch instance oci compute instance launch \ --compartment-id $OCI_COMPARTMENT_ID \ --availability-domain "Uocm:US-ASHBURN-AD-1" \ --shape "VM.Standard.E4.Flex" \ --shape-config '{"ocpus": 1, "memoryInGBs": 8}' \ --display-name "dev-instance" \ --image-id \ --subnet-id \ --ssh-authorized-keys-file ~/.ssh/id_rsa.pub # Stop / start / terminate oci compute instance action --instance-id --action STOP oci compute instance action --instance-id --action START oci compute instance terminate --instance-id --force ``` **Object storage operations:** ```bash # Upload a file oci os object put --bucket-name my-bucket --file ./data.csv --name data/input.csv # Download a file oci os object get --bucket-name my-bucket --name data/input.csv --file ./downloaded.csv # List objects with prefix oci os object list --bucket-name my-bucket --prefix "data/" \ --query "data[*].{Name:name,Size:size}" --output table # Bulk upload a directory oci os object bulk-upload --bucket-name my-bucket --src-dir ./upload/ --overwrite ``` ### Step 6: Python SDK Local Dev Script Create a reusable dev helper: ```python #!/usr/bin/env python3 """oci_dev.py — Local OCI development helper.""" import oci import os import sys def get_config(profile="DEFAULT"): """Load OCI config with environment variable overrides.""" config = oci.config.from_file("~/.oci/config", profile_name=profile) # Allow env var override for compartment config["compartment_id"] = os.environ.get( "OCI_COMPARTMENT_ID", config.get("tenancy") ) oci.config.validate_config(config) return config def list_instances(config): compute = oci.core.ComputeClient(config, timeout=(10, 30)) instances = compute.list_instances( compartment_id=config["compartment_id"] ).data for inst in instances: print(f"{inst.display_name:<30} {inst.lifecycle_state:<12} {inst.shape}") return instances def list_buckets(config): os_client = oci.object_storage.ObjectStorageClient(config, timeout=(10, 30)) namespace = os_client.get_namespace().data buckets = os_client.list_buckets( namespace_name=namespace, compartment_id=config["compartment_id"] ).data for b in buckets: print(f"{b.name:<40} {b.time_created}") return buckets def health_check(config): identity = oci.identity.IdentityClient(config, timeout=(5, 15)) user = identity.get_user(config["user"]).data regions = identity.list_regions().data print(f"User: {user.name}") print(f"Regions: {len(regions)} available") print("Status: OK") if __name__ == "__main__": profile = os.environ.get("OCI_CLI_PROFILE", "DEFAULT") cfg = get_config(profile) cmd = sys.argv[1] if len(sys.argv) > 1 else "health" if cmd == "instances": list_instances(cfg) elif cmd == "buckets": list_buckets(cfg) elif cmd == "health": health_check(cfg) else: print(f"Usage: python oci_dev.py [instances|buckets|health]") ``` ```bash # Usage python oci_dev.py health python oci_dev.py instances OCI_CLI_PROFILE=dev python oci_dev.py buckets ``` ### Step 7: Project Structure ``` my-oci-project/ ├── .env # OCI_COMPARTMENT_ID, OCI_REGION, OCI_CLI_PROFILE ├── .gitignore # .env, *.pem, ~/.oci/ ├── oci_dev.py # Dev helper script (Step 6) ├── src/ │ └── oci_client.py # Singleton client (see oraclecloud-sdk-patterns) ├── scripts/ │ ├── setup.sh # Install oci + oci-cli + source .env │ └── teardown.sh # Terminate dev resources └── tests/ └── test_oci.py # Unit tests with mocked OCI responses ``` ## Output Successful setup produces: - OCI CLI installed and verified with `oci iam region list` - Multi-profile `~/.oci/config` for dev/staging/prod switching - Shell aliases for common OCI operations (instances, buckets, health) - A reusable Python dev helper script for listing resources and health checks - Environment variable management via `.env` for project-specific OCIDs ## Error Handling | Error | Code | Cause | Solution | |-------|------|-------|----------| | NotAuthenticated | 401 | Wrong profile or expired key | Check `OCI_CLI_PROFILE` matches a valid config section | | NotAuthorizedOrNotFound | 404 | Compartment OCID wrong for this profile | Verify `OCI_COMPARTMENT_ID` matches the profile's tenancy | | ConfigFileNotFound | — | `~/.oci/config` missing | Run `oraclecloud-install-auth` | | command not found: oci | — | OCI CLI not installed | `pip install oci-cli` | | TooManyRequests | 429 | Rapid CLI commands hitting rate limit | Add `--retry-strategy default` or space out requests | | ServiceError status -1 | -1 | Network timeout | Check connectivity; increase timeout in SDK scripts | ## Examples **One-liner resource summary:** ```bash echo "=== OCI Status ===" && \ oci-health && \ echo "Instances:" && oci-instances && \ echo "Buckets:" && oci-buckets ``` **Switch profile and list resources in one command:** ```bash OCI_CLI_PROFILE=dev oci compute instance list \ --compartment-id $OCI_COMPARTMENT_ID --output table ``` ## Resources - [OCI CLI Reference](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm) — full command reference and configuration guide - [OCI CLI Configuration](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm) — config file format and profiles - [OCI Python SDK Reference](https://docs.oracle.com/en-us/iaas/tools/python/latest/) — API documentation for all service clients - [OCI API Reference](https://docs.oracle.com/en-us/iaas/api/) — REST API endpoints and schemas - [OCI Terraform Provider](https://registry.terraform.io/providers/oracle/oci/latest/docs) — infrastructure as code alternative - [OCI Status](https://ocistatus.oraclecloud.com) — service health dashboard ## Next Steps With your local dev loop set up, see `oraclecloud-sdk-patterns` for production-grade client patterns, or `oraclecloud-common-errors` when you hit issues during development.