{"id":45776714,"url":"https://github.com/adrianmross/oci-context","last_synced_at":"2026-05-19T01:04:07.939Z","repository":{"id":340687290,"uuid":"1167003589","full_name":"adrianmross/oci-context","owner":"adrianmross","description":"Manage your OCI CLI context quicker","archived":false,"fork":false,"pushed_at":"2026-03-26T23:53:39.000Z","size":240,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T04:55:04.505Z","etag":null,"topics":["cli","go","oci","oracle","oraclecloud","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adrianmross.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-25T21:00:45.000Z","updated_at":"2026-03-26T23:53:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/adrianmross/oci-context","commit_stats":null,"previous_names":["adrianmross/oci-context"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/adrianmross/oci-context","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianmross%2Foci-context","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianmross%2Foci-context/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianmross%2Foci-context/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianmross%2Foci-context/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adrianmross","download_url":"https://codeload.github.com/adrianmross/oci-context/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianmross%2Foci-context/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33197520,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"ssl_error","status_checked_at":"2026-05-18T09:27:28.300Z","response_time":71,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","go","oci","oracle","oraclecloud","tui"],"created_at":"2026-02-26T10:02:23.663Z","updated_at":"2026-05-19T01:04:07.924Z","avatar_url":"https://github.com/adrianmross.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# oci-context\n\nA daemon + CLI/TUI to manage OCI context (profile, tenancy, compartment, region) akin to kubectl contexts. Designed to work with other tools by exposing context over a local socket or via `oci-context export`.\n\n## Components\n- **Daemon (oci-contextd / `oci-context daemon serve`)**: serves Unix socket APIs and can run background auth validation/refresh loops.\n- **CLI/TUI (oci-context)**: manage contexts, switch current context, export env/JSON, control daemon, and pick via TUI selector.\n\n## Install\n\nOne-line install (default: `oci-context` latest stable):\n\n```sh\ncurl -sSL https://raw.githubusercontent.com/adrianmross/oci-context/main/install.sh | bash\n```\n\nInstall daemon binary instead:\n\n```sh\nTOOL=oci-contextd curl -sSL https://raw.githubusercontent.com/adrianmross/oci-context/main/install.sh | bash\n```\n\nInstall a specific version:\n\n```sh\nVERSION=v0.1.0 curl -sSL https://raw.githubusercontent.com/adrianmross/oci-context/main/install.sh | bash\n```\n\n### TUI controls (quick reference)\n- `/` to start filtering the current list; hotkeys are suppressed while typing.\n- `Enter` applies the filtered list and in-region modes stages the selection.\n- `Space` stages/highlights the current row (pending save); staged items show in magenta.\n- `Ctrl+S` or `q` saves the staged/current selection from any mode.\n- **Hotkey casing rule:** in the main menu (`contexts`) use lowercase hotkeys; in submenus (`tenancies`, `compartments`, `regions`) use uppercase hotkeys.\n- Main menu (`contexts`): `r` opens regions, `c` opens compartments, `t` opens tenancies.\n- Submenus: `R` opens regions, `C` opens compartments, `T` opens tenancies, `P` returns to profiles/contexts.\n- Navigation: `backspace` goes up/back.\n- Quit without saving: `Esc` or `Ctrl+C`.\n\n## Config\nConfig resolution\n- Default path (global): `~/.oci-context/config.yml`\n- Project-aware auto-detection (when `--config` not set and `-g/--global` not set): first match wins in this order\n  - `./.oci-context.yml`\n  - `./.oci-context.json`\n  - `./.oci-context/config.yml`\n  - `./.oci-context/config.json`\n  - `./oci-context.yml`\n  - `./oci-context.json`\n  - `./oci-context/config.yml`\n  - `./oci-context/config.json`\n\nGlobal vs project selection\n- `--config` always overrides\n- `-g, --global` forces the global config (`~/.oci-context/config.yml`)\n- Otherwise the first project-local file found (above) is used; if none found, fall back to global\n\n```yaml\noptions:\n  oci_config_path: ~/.oci/config\n  socket_path: ~/.oci-context/daemon.sock\n  default_profile: \"\"\n  daemon_contexts: []\ncontexts:\n  - name: dev\n    profile: DEFAULT\n    tenancy_ocid: ocid1.tenancy.oc1..aaaa\n    compartment_ocid: ocid1.compartment.oc1..bbbb\n    region: us-phoenix-1\n    user: alice@example.com\n    notes: dev tenancy\n  - name: prod\n    profile: PROD\n    tenancy_ocid: ocid1.tenancy.oc1..cccc\n    compartment_ocid: ocid1.compartment.oc1..dddd\n    region: us-ashburn-1\ncurrent_context: dev\n```\n\n## IPC API (Unix socket, framed JSON)\nRequests include:\n- `{ \"method\": \"get_current\" }`\n- `{ \"method\": \"use_context\", \"name\": \"dev\" }`\n- `{ \"method\": \"list\" }`\n- `{ \"method\": \"add_context\", \"context\": { ... } }`\n- `{ \"method\": \"delete_context\", \"name\": \"dev\" }`\n- `{ \"method\": \"export\", \"format\": \"env|json\" }`\n- `{ \"method\": \"auth_status\", \"name\": \"dev\" }` (name optional; defaults to current)\n\nResponses: `{ \"ok\": true, \"data\": ... }` or `{ \"ok\": false, \"error\": \"...\" }`.\n\n## CLI commands\n- `oci-context --version` or `oci-context -v`\n- `oci-context init`\n- `oci-context list`\n- `oci-context current`\n- `oci-context oci -- \u003coci args...\u003e` (runs OCI CLI with current context defaults)\n- `oci-context use \u003cname\u003e`\n- `oci-context add`\n- `oci-context set \u003cname\u003e --field value`\n- `oci-context delete \u003cname\u003e`\n- `oci-context status`\n- `oci-context doctor`\n- `oci-context export --format env|json`\n- `oci-context auth methods|show|set|set-user|login|refresh|ensure|validate|setup|notify`\n- `oci-context setup` (bootstrap config + daemon; auth optional with `--with-auth`)\n- `oci-context daemon serve [--auto-refresh --validate-interval 5m --refresh-interval 15m]`\n- `oci-context daemon install` (installer entrypoint; use subcommands for specific targets)\n- `oci-context daemon up` (one-command restart + nudge after return/wake)\n- `oci-context daemon doctor` (diagnose daemon/service/socket/auth health)\n- `oci-context daemon auth-status [--context \u003cname\u003e]`\n- `oci-context daemon nudge [--context \u003cname\u003e]`\n- `oci-context daemon monitor list|add|remove|clear`\n- `oci-context daemon install launchd|sleepwatcher|hammerspoon|systemd`\n- `oci-context auth notify` (macOS manual trigger)\n- `oci-context tui`\n\n### OCI CLI Defaults (Transparent `oci` Usage)\nTo run plain `oci ...` commands without repeatedly passing `--profile`, `--region`, and `--compartment-id`, load managed OCI CLI defaults once per shell:\n\n```sh\neval \"$(oci-context export -f oci-env)\"\n```\n\nThis sets:\n- `OCI_CLI_RC_FILE` to a managed rc file updated from your current context\n- `OCI_CLI_CONFIG_FILE` to your configured OCI config path\n\nAfter that, when you run `oci-context use ...` (or save from TUI), the managed OCI CLI defaults are refreshed automatically.\n\n### current\nPrints only the current context name.\n\n```\n$ oci-context current\ndev\n```\n\n### status\nShows current context details with friendly names by default.\n\nDefault human-friendly multiline (omits profile line when context == profile):\n\n```\n$ oci-context status\ncontext: dev\nprofile: DEFAULT\nauth: api_key\ntenancy: My Tenancy (ocid1.tenancy.oc1..aaaa)\ncompartment: My Compartment (ocid1.compartment.oc1..bbbb)\nuser: Alice (ocid1.user.oc1..cccc)\nregion: us-phoenix-1\n```\n\nPlain OCIDs only (`-p`):\n\n```\n$ oci-context status -p\ncontext=dev profile=DEFAULT auth=api_key tenancy=ocid1.tenancy.oc1..aaaa compartment=ocid1.compartment.oc1..bbbb user=ocid1.user.oc1..cccc region=us-phoenix-1\n```\n\nSingle-line friendly with abbreviated OCIDs (`-o plain`):\n\n```\n$ oci-context status -o plain\ncontext=dev profile=DEFAULT auth=api_key tenancy=My Tenancy (ocid1…aaaa) compartment=My Compartment (ocid1…bbbb) user=Alice (ocid1…cccc) region=us-phoenix-1\n```\n\nSkip live OCI identity lookups when agents only need cached config/current-context\nstate:\n\n```sh\noci-context status --cached\noci-context status --no-lookup -o json\n```\n\nStructured outputs:\n\n```\n$ oci-context status -o json\n{ \"context\": \"dev\", \"profile\": \"DEFAULT\", ... }\n\n$ oci-context status -o yaml\ncontext: dev\nprofile: DEFAULT\n...\n```\n\nErrors:\n- If no current context is set, returns: `no current context set`.\n- If a bad `-o` value is provided, returns: `unsupported output format: \u003cvalue\u003e`.\n\n## Integration\n- Shell: `eval $(oci-context export --format env)` sets OCI_CLI_PROFILE, OCI_TENANCY_OCID, OCI_COMPARTMENT_OCID, OCI_REGION.\n- Tools: read JSON via `oci-context export --format json` or query the socket.\n\n### Auth readiness for scripts\n\nUse `auth ensure` before OCI-dependent automation. It validates the selected\ncontext, refreshes `security_token` auth when possible, and returns a clear\nresult for agents and scripts:\n\n```sh\noci-context auth ensure --output json\noci-context auth show --output json\noci-context auth methods --output json\noci-context doctor --output json\n```\n\n`auth methods` supports `--output text|json|yaml` and defaults to the existing\nhuman text. `auth show --output json` includes `daemon_available` and, when the\ndaemon cannot be reached, `daemon_error` so scripts can distinguish unavailable\ndaemon state from missing auth data.\n\nIf validation and refresh cannot recover a security token, the command reports\n`login_required: true`. To allow an interactive browser login as part of the\nsame command, pass `--login`:\n\n```sh\noci-context auth ensure --login\n```\n\nFor non-interactive automation, pass `--no-interactive`. This prevents browser\nlogin/setup flows and reports `login_required` in structured output instead:\n\n```sh\noci-context --no-interactive auth ensure --login --output json\n```\n\nUse `doctor` for a best-effort local health summary of config, OCI CLI, daemon,\nand auth readiness:\n\n```sh\noci-context doctor --output json\n```\n\n## Agent Contract\n\n- Stable automation output is JSON. Agents should prefer `--output json`,\n  `-o json`, or `--format json` for supported commands such as `status`,\n  `export`, `auth ensure`, `auth show`, and daemon status commands.\n- JSON keys are compatibility surface. Add fields when needed, but avoid\n  renaming or removing existing fields without a documented migration path.\n- Preferred local checks are `make fmt`, `make vet`, `make test`,\n  `make lint-workflows`, and `make validate-workflows`.\n- Releases are produced from semantic `v*` tags through GoReleaser. The\n  `auto-release` workflow may create the next tag from Conventional Commit\n  subjects on `main`, but it skips commits that modify workflow files.\n\n## Daemon Auth Monitoring\nThe daemon can monitor and maintain auth for one or more contexts in the background.\n\n- If `options.daemon_contexts` is empty, daemon monitors `current_context`.\n- If `options.daemon_contexts` has entries, daemon monitors all listed contexts.\n- `security_token` contexts: daemon validates and refreshes based on intervals.\n- Other auth methods: daemon validates only.\n- Failure handling uses exponential backoff and stderr rate-limiting to reduce noise.\n\nManage monitored contexts:\n\n```sh\noci-context daemon monitor add dev prod\noci-context daemon monitor list\noci-context daemon monitor remove dev\noci-context daemon monitor clear\n```\n\nTrigger immediate maintenance without waiting for interval:\n\n```sh\noci-context daemon nudge\noci-context daemon nudge --context dev\n```\n\nRun daemon with auth maintenance enabled:\n\n```sh\noci-context daemon serve --auto-refresh --validate-interval 5m --refresh-interval 15m\n```\n\nCheck runtime status:\n\n```sh\noci-context daemon auth-status --context dev\noci-context auth show --context dev\n```\n\n## Background Service\n### macOS (`launchd`)\nOne-shot install/reload (recommended):\n\n```sh\noci-context daemon install\n```\n\nVerbose mode for setup/doctor/up/install commands:\n\n```sh\noci-context daemon install --verbose\noci-context daemon doctor --verbose\noci-context daemon up --verbose\n```\n\nThis writes the launchd plist, (re)loads it, and kickstarts the job so the running daemon uses the current binary.\n\nQuick recovery when you return to your computer:\n\n```sh\noci-context daemon up\n```\n\nThis kickstarts the launchd daemon and sends an immediate nudge.\n\nRun diagnostics:\n\n```sh\noci-context daemon doctor\n```\n\nShort aliases:\n- `oci-context daemon fix` == `oci-context daemon recover` == `oci-context daemon up`\n- `oci-context daemon check` == `oci-context daemon doctor`\n\nGenerate a plist:\n\n```sh\noci-context daemon install launchd \\\n  --binary /path/to/oci-context \\\n  --config ~/.oci-context/config.yml \\\n  --auto-refresh \\\n  --validate-interval 5m \\\n  --refresh-interval 15m\n```\n\nThen load/start:\n\n```sh\nlaunchctl unload ~/Library/LaunchAgents/com.adrianmross.oci-context.daemon.plist 2\u003e/dev/null || true\nlaunchctl load ~/Library/LaunchAgents/com.adrianmross.oci-context.daemon.plist\nlaunchctl start com.adrianmross.oci-context.daemon\n```\n\nAfter reinstalling/upgrading `oci-context`, restart the running launchd job so the daemon picks up the new binary. Otherwise, IPC commands can hit stale behavior (for example, `daemon nudge` returning `method not implemented` while help/docs show it):\n\n```sh\nlaunchctl kickstart -k gui/$(id -u)/com.adrianmross.oci-context.daemon\n```\n\n### sleep/wake automation with sleepwatcher\nInstall wake hook automation (restarts daemon + nudges auth checks on wake):\n\n```sh\nbrew install sleepwatcher\noci-context daemon install sleepwatcher\n```\n\n### Actionable wake notifications with Hammerspoon (macOS)\nInstall managed Hammerspoon integration plus a wake hook script that sends clickable notifications. Clicking `Re-auth now` runs `oci session authenticate` for the affected profile.\n\n```sh\nbrew install --cask hammerspoon\noci-context daemon install hammerspoon\n```\n\nNotes:\n- This command writes/updates:\n  - `~/.hammerspoon/oci_context.lua` (managed URL handler + auth task runner)\n  - `~/.hammerspoon/init.lua` (adds `pcall(require, \"oci_context\")` when missing)\n  - `~/.wakeup` (wake script that nudges daemon and raises actionable notifications on auth failures)\n- If you prefer manual reload, run with `--reload=false` and then:\n\n```sh\nopen -g 'hammerspoon://reloadConfig'\n```\n\nManually trigger an actionable notification from CLI:\n\n```sh\noci-context auth notify --context dev --reason \"manual check\"\noci-context auth notify --context dev --reason \"manual check\" --tenancy-name your-tenancy\n```\n\n`--tenancy-name` is optional. When omitted, `notify` uses the selected context's `tenancy_ocid`.\n`--native-notify` defaults to false; enable it if you also want a native macOS notification.\nIf `terminal-notifier` is installed, `notify` uses it and clicking the native notification opens the Hammerspoon URL action.\n\n### Linux (`systemd`, user service)\nOne-shot install for a user service:\n\n```sh\noci-context daemon install systemd\n```\n\n### Top-level Bootstrap\nRun project/global config bootstrap and daemon setup in one command:\n\n```sh\noci-context setup\n```\n\nUseful options:\n- `--no-daemon` skip daemon setup\n- `--with-auth` also run auth setup for selected context\n- `--context \u003cname\u003e` choose auth setup context\n- `--verbose` print underlying system commands\n\nor generate manually:\n\nExample unit file (`~/.config/systemd/user/oci-context-daemon.service`):\n\n```ini\n[Unit]\nDescription=oci-context daemon\nAfter=network-online.target\n\n[Service]\nExecStart=/path/to/oci-context daemon serve --config %h/.oci-context/config.yml --auto-refresh --validate-interval 5m --refresh-interval 15m\nRestart=always\nRestartSec=5\n\n[Install]\nWantedBy=default.target\n```\n\nEnable and start:\n\n```sh\nsystemctl --user daemon-reload\nsystemctl --user enable --now oci-context-daemon\nsystemctl --user status oci-context-daemon\n```\n## Status\nWork in progress.\n\n---\n\n## Development and CI/CD\n\n### Local prerequisites\n- Go (from `go.mod` go version; currently 1.25.6)\n- `actionlint` (for workflow linting): `brew install actionlint` **or** `go install github.com/rhysd/actionlint/cmd/actionlint@latest`\n- `act` (for local workflow dry runs): `brew install act` **or** `go install github.com/nektos/act@latest`\n\nCheck tool availability:\n```sh\nmake tools\n```\n\n### Local validation\nRuns formatting, vet, tests, actionlint, and an `act` dry run against a sample PR payload:\n```sh\nmake validate\n```\nTargets:\n- `make fmt`\n- `make vet`\n- `make test`\n- `make lint-workflows`\n- `make validate-workflows` (uses `.github/testdata/pull_request.json`)\n\n### GitHub Actions workflows\n- **CI** (`.github/workflows/ci.yml`): on push/PR to main/develop/release/**; runs gofmt (checks diff), go vet, go test, actionlint.\n- **Release** (`.github/workflows/release.yml`): on tag `v*` or manual dispatch; validates tag, runs tests, and uses GoReleaser to publish cross-platform tarballs plus `checksums.txt`.\n- **CD** (`.github/workflows/cd.yml`): manual `workflow_dispatch` with `env` input; placeholder deploy step to be customized.\n\n### Release tagging flow\n```sh\ngit tag v0.1.0\ngit push origin v0.1.0\n```\nThis triggers the Release workflow, builds binaries, and attaches them to the GitHub release.\n\n### Acting CI locally\nExample dry-run of CI with act (requires Docker):\n```sh\nact pull_request --eventpath .github/testdata/pull_request.json --dryrun\n```\n\n### Repository\nPrivate GitHub repo: https://github.com/adrianmross/oci-context\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrianmross%2Foci-context","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadrianmross%2Foci-context","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrianmross%2Foci-context/lists"}