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