Automating OCI with the CLI

Clicking through a console is fine for looking around and fine for the occasional one off change, but it does not scale, it cannot be repeated reliably, and it leaves no record of what was done. The moment a task has to be done more than once, done the same way every time, or done as part of a larger automated flow, the command line becomes the right tool. This guide explains how to automate Oracle Cloud Infrastructure with the OCI command line interface, what it is good for, and how to use it well.

It is part of our DevOps and automation on OCI cluster. It sits alongside our guide to the OCI SDK for automation, complements the declarative approach in Terraform on OCI getting started, and supports the pipeline work in CI CD on OCI end to end.

What the CLI is for

The OCI CLI is a command line tool that talks to the same API the console uses, which means anything that can be done in the console can be done from the command line, and crucially, can be scripted. The value of the CLI is that commands can be saved, repeated, combined, and run without a human present, turning a manual sequence of clicks into a script that runs the same way every time. This is the first step from doing things by hand toward doing things by automation.

The CLI suits operational tasks, the everyday running of an estate: querying what exists, making routine changes, kicking off jobs, gathering information, and stitching together small workflows. It is the natural tool for the imperative, do this now, kind of work, as distinct from the declarative, make the estate look like this, work that infrastructure as code tools handle. Knowing which kind of task is in front of you decides which tool to reach for, a distinction worth being clear about.

CLI versus infrastructure as code

A common confusion is when to use the CLI and when to use a tool like Terraform, and the answer turns on the difference between imperative and declarative work. The CLI does what you tell it, in the order you tell it, which is right for actions and operations. Terraform, covered in our Terraform on OCI getting started guide, describes a desired end state and makes the estate match it, which is right for building and maintaining infrastructure. They are complementary rather than competing.

Authenticating the CLI

Before the CLI can do anything it has to prove who it is, and how it authenticates depends on where it runs. On a person's machine it authenticates with that person's API credentials, which should be guarded as carefully as any other credential. Inside the OCI estate, on a compute instance for example, the better approach is instance principals, where the instance is granted an identity and the CLI uses that, removing the need to store credentials on the machine at all.

This distinction matters for automation, because scripts that run unattended must not have long lived credentials sitting in files where they could be stolen. Using instance principals or other workload identities for automated CLI use, and saving stored credentials only for interactive human use, is the secure pattern, and it connects to the broader discipline covered in our guide to secrets management in OCI pipelines.

Patterns for CLI automation

The CLI becomes powerful when its commands are combined, and a few patterns recur. The first is querying and filtering, using the CLI to ask what exists and narrowing the answer to exactly what is needed, which is the basis of any script that has to act on a set of resources. The second is scripting sequences, where a series of commands is saved into a script that performs a whole task reliably, the same way every time. The third is integration, where the CLI is called from within a larger pipeline or automation to perform a step.

A discipline that pays off is to make scripts safe to run more than once, so that running a script twice does not create duplicates or cause errors, because automated scripts do get run again, and a script that only works the first time is a trap. Writing scripts that check the current state before acting, and that handle the case where the desired result already exists, is what makes CLI automation dependable rather than fragile.

When to graduate to the SDK

The CLI is excellent for scripting, but there is a point where a task outgrows it, usually when the logic becomes complex, the data handling becomes involved, or the automation needs to be a proper program rather than a script. At that point the OCI SDK, which gives the same capabilities from within a real programming language, is the better tool, and we cover it in our guide to the OCI SDK for automation. The CLI and the SDK are points on a spectrum, and moving from one to the other as complexity grows is natural.

For the large middle ground of operational automation, though, the CLI is the workhorse, and a team comfortable with it can automate a great deal of the everyday running of an estate quickly. Building these operational automations, and knowing when to use the CLI, the SDK, or infrastructure as code, is part of what we bring through our DevOps and IaC solution and our OCI managed services. The CLI is the tool that turns repetitive console work into reliable automation, and it is where a great deal of practical OCI automation begins.