oracle-cloud-cli-ops
Plan, provision, operate, and tear down Oracle Cloud Always Free infrastructure with the oci CLI.
Open source Open in the app JSON README (API)
About
Plan, provision, operate, and tear down Oracle Cloud Always Free infrastructure with the oci CLI.
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- sarathchandrabellam
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.1.0
- Last push
- 2026-08-12T11:49:43Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
sarathchandrabellam/oracle-cloud-cli-ops
README
# oracle-cloud-cli-ops Run an Oracle Cloud Always Free environment from the command line, with runbooks you can follow by hand and agent skills that follow them for you. No Terraform. No state file. No CI pipeline. Just the `oci` CLI, a handful of copy-pasteable commands, and enough written-down judgement that you don't accidentally create something billable. ## Why this exists Oracle's Always Free tier is genuinely generous — an Arm machine with 2 OCPUs and 12 GB of RAM, free forever. But standing one up is fiddly: you need a VCN, a gateway, a route table, a subnet, a security group, the right image OCID, and the right shape config, in the right order, with the right JSON. Most guides solve this with Terraform. For a single virtual machine that is a bad trade — you inherit state management, drift, and a plan/apply ceremony to manage one box. This repo takes the other path: the CLI is the tool, and the knowledge lives in Markdown. **The catch, stated up front:** the OCI API will happily let you launch a 41-OCPU instance that bills by the hour. Terraform's variable validation used to catch that. Nothing here does, except the pre-flight checks in the runbooks. Read [docs/staying-free.md](docs/staying-free.md) before you launch anything. ## Who this is for - You want a free Arm VM for a side project, a small server, or a home lab. - You'd rather understand the commands than hide them behind a module. - You want your coding agent to do this safely, with guardrails it will respect. Not for you if you're managing many environments or a team — that's where Terraform starts earning its keep. ## Quickstart **Prerequisites:** an Oracle Cloud account and about 30 minutes. Use it with Claude Code: ``` /plugin marketplace add SarathChandraBellam/oracle-cloud-cli-ops /plugin install oracle-cloud-cli-ops /oracle-cloud-cli-ops:oci-setup ``` `oci-setup` installs the CLI if needed, opens a browser to log you in, then **discovers** your tenancy, home region, availability domains, public IP, and SSH key. It asks you only what it genuinely can't work out — which compartment to use — and stores the result where it survives plugin updates. No config file to hand-edit. The plugin discovers account and resource values at runtime; it does not create or read local configuration files. Work through the runbooks through the plugin, in order: | # | Runbook | What you get | |---|---|---| | 1 | [set-up-the-cli.md](docs/runbooks/set-up-the-cli.md) | Installed, authenticated, and knowing your own OCIDs | | 2 | [create-the-network.md](docs/runbooks/create-the-network.md) | VCN, gateway, route table, public subnet, security group | | 3 | [launch-an-instance.md](docs/runbooks/launch-an-instance.md) | A running Always Free Arm VM you can SSH into | | 4 | [connect-and-verify.md](docs/runbooks/connect-and-verify.md) | SSH working, plus what to check when it isn't | | 5 | [tear-it-all-down.md](docs/runbooks/tear-it-all-down.md) | Everything deleted, in dependency order, verified | ## Reference docs - **[always-free-tier.md](docs/always-free-tier.md)** — exactly what Oracle gives away, with the real numbers. The Arm allowance is 2 OCPUs and 12 GB, not the 4/24 you'll see repeated all over the internet. - **[staying-free.md](docs/staying-free.md)** — how to measure your own account's limits, why they're far above the free allowance, and how to avoid a surprise bill. - **[why-not-terraform.md](docs/why-not-terraform.md)** — the honest trade-off, including the four things you genuinely give up. ## Claude Code plugin This repo is also a [Claude Code](https://claude.com/claude-code) plugin. Install it and your agent can drive the whole workflow with the same guardrails the runbooks describe: ``` /plugin marketplace add SarathChandraBellam/oracle-cloud-cli-ops /plugin install oracle-cloud-cli-ops ``` **Skills** — invoked automatically when relevant, or explicitly as `/oracle-cloud-cli-ops:<name>`: | Skill | Use it for | |---|---| | `oci-setup` | First-time setup: authenticate, discover, pick a compartment | | `oci-session` | Authenticating, expired tokens, switching profiles | | `oci-provision` | Creating network and compute inside the free allowance | | `oci-operate` | Inventory, cost checks, SSH troubleshooting, drift review | | `oci-teardown` | Deleting things safely, in the right order, with confirmation | **Subagents** — for longer investigations, delegated with their own context: | Subagent | Use it for | |---|---| | `oci-cost-auditor` | Read-only sweep for anything billable or about to be | | `oci-troubleshooter` | Ordered diagnosis of SSH timeouts and broken networking | | `oci-architect` | Planning what fits in the free allowance before you build | A `SessionStart` hook reports whether the CLI is installed, whether credentials exist, and whether your session token is stale — locally, with no API calls. Everything is plain Markdown with YAML frontmatter. **The runbooks stand alone** — if you don't use an agent at all, ignore this section entirely and follow the docs by hand. ## Other CLIs The same repository includes native adapters for Codex and Gemini CLI. The OCI skills, agents, runbooks, mandatory tagging, snapshots, and safety rules are shared; only manifests, commands, and hook output differ by host. ### Gemini CLI ```bash gemini extensions install https://github.com/SarathChandraBellam/oracle-cloud-cli-ops.git ``` Use `/oci-setup`, `/oci-provision`, `/oci-audit`, or `/oci-teardown`, or ask in natural language and let the bundled skills activate. ### Codex Install the repository as a Codex plugin, or copy its `skills/` directory into your Codex skill location. The same `$oci-setup`, `$oci-provision`, `$oci-audit`, and `$oci-teardown` workflows use the shared runbooks and agents. ## Configuration Nothing is hardcoded to a tenancy, region, or account — not in a single file. Every command reads these variables: | Variable | Meaning | How it's obtained | |---|---|---| | `OCI_CLI_PROFILE` | Which profile in `~/.oci/config` | You choose a name | | `OCI_CLI_AUTH` | `security_token` or `api_key` | You choose the auth style | | `OCI_TENANCY_ID` | For limits and availability-domain queries | **Auto** — read from `~/.oci/config` | | `OCI_COMPARTMENT_ID` | Where resources get created | **Asked** — listed for you to pick | | `OPERATOR_CIDR` | Your public IP as a `/32`, for the SSH rule | **Auto** — detected, then confirmed | | `SSH_PUBLIC_KEY_FILE` | Public key injected into new instances | **Auto** — detected, or generated | | `RESOURCE_PREFIX` | Name prefix for created resources | Defaults to `af` | | `MANAGED_BY_TAG` | Freeform tag for inventory queries | Defaults to the plugin name | No plugin configuration file is written. Authentication remains in the standard `~/.oci/config`; tenancy, compartment, IP, keys, and managed resources are discovered again whenever a skill needs them. Your home region is discovered at runtime, never assumed: ```bash oci iam region-subscription list \ --query 'data[?"is-home-region"]."region-name" | [0]' --raw-output ``` This matters: Always Free compute and storage exist **only** in your home region. The same command in another region bills you. ## Repository layout ``` docs/ always-free-tier.md what Oracle gives away, with verified numbers staying-free.md how not to get billed — read this one why-not-terraform.md the trade-off, including what you give up runbooks/ five numbered procedures, in order skills/ agent skills (oci-session, -provision, -operate, -teardown) agents/ subagent definitions hooks/ SessionStart readiness check scripts/ hook implementation .claude-plugin/ plugin + marketplace manifests .codex-plugin/ Codex plugin manifest gemini-extension.json Gemini CLI extension manifest commands/ Gemini CLI slash-command adapters ``` ## Contributing Issues and PRs welcome — especially corrections to the free-tier numbers, which Oracle changes without announcement. See [CONTRIBUTING.md](CONTRIBUTING.md). ## License [MIT](LICENSE). Not affiliated with or endorsed by Oracle.