octx

octx is a small terminal helper for switching ops profiles used by Codex workflows. Pick a project once, then keep Codex, SSH, cloud CLIs, and Kubernetes aligned in the current shell.

Supported Profiles

| Profile | Config field | Switch behavior | | --- | --- | --- | | | codex_profile | Exports CODEX_PROFILE | | | ssh_config | Exports OCTX_SSH_CONFIG for the shell ssh wrapper | | | aws_profile | Exports AWS_PROFILE | | | azure_config_dir | Exports AZURE_CONFIG_DIR | | | gcloud_config | Exports CLOUDSDK_ACTIVE_CONFIG_NAME | | | aliyun_profile | Exports ALIBABA_CLOUD_PROFILE | | | kubeconfig | Exports KUBECONFIG |

Features

• Fast project picker in the terminal.
• Picker option to unset the active profiles.
• Optional project colors in the picker and doctor output.
• Exports OPSCTX_PROJECT.
• Exports or unsets AWS_PROFILE, ALIBABA_CLOUD_PROFILE, CODEX_PROFILE, CLOUDSDK_ACTIVE_CONFIG_NAME, AZURE_CONFIG_DIR, KUBECONFIG, and OCTX_SSH_CONFIG.
• Keeps each terminal shell isolated; switching in one shell does not change another shell.
• Generates per-project SSH config files without mutating ~/.ssh/config.
• Ships as an npm package with native Go binaries for Linux and macOS.

Install

npm install -g @ninj4dkill4/octx

Verify the install:

octx --help

Shell Integration

octx needs a shell wrapper because a child process cannot export environment variables into its parent shell.

Add this to ~/.zshrc:

octx() {
  if [[ $# -eq 0 ]]; then
    eval "$(command octx --shell)"
  else
    command octx "$@"
  fi
}

If you use Codex profiles, add this wrapper too:

codex() {
  if [[ -n "${CODEX_PROFILE:-}" ]]; then
    command codex --profile "$CODEX_PROFILE" "$@"
  else
    command codex "$@"
  fi
}

If you use ssh_config, add this wrapper too:

ssh() {
  if [[ -n "${OCTX_SSH_CONFIG:-}" ]]; then
    command ssh -F "$OCTX_SSH_CONFIG" "$@"
  else
    command ssh "$@"
  fi
}

Reload your shell:

source ~/.zshrc

Quick Start

Create a sample config:

octx init

Edit the generated config:

~/.config/opsctx/config.yaml

Example:

projects:
- code: core
  name: Core Platform
  color: "#22c55e"
  aws_profile: core-devops
  aliyun_profile: core-devops
  codex_profile: core
  gcloud_config: core-devops
  azure_config_dir: ~/.azure/core
  kubeconfig: ~/.kube/core
  ssh_config: ~/.ssh/config.d/core

- code: pay
  name: Payment
  color: "#3b82f6"
  aws_profile: payment-devops
  aliyun_profile: payment-devops
  codex_profile: payment
  gcloud_config: payment-devops
  azure_config_dir: ~/.azure/payment
  kubeconfig: ~/.kube/payment
  ssh_config: ~/.ssh/config.d/payment

Only code is required. color, aws_profile, aliyun_profile, codex_profile, gcloud_config, azure_config_dir, kubeconfig, and ssh_config are optional. color accepts #RGB or #RRGGBB and is used only for display in the picker and doctor output. If an optional profile is omitted, octx unsets the matching environment variable during switch. If ssh_config is omitted, octx unsets OCTX_SSH_CONFIG.

Remove the legacy include from ~/.ssh/config if it exists:

Include ~/.config/opsctx/ssh-current

Current versions use the shell ssh wrapper and OCTX_SSH_CONFIG instead of a shared ssh-current symlink.

Switch context:

octx

The picker selects the current shell context by default. If OPSCTX_PROJECT is unset or points to an unknown project, the unset option is selected.

Choose unset at the bottom of the picker to clear the active octx context in the current shell. This unsets OPSCTX_PROJECT, AWS_PROFILE, ALIBABA_CLOUD_PROFILE, CODEX_PROFILE, CLOUDSDK_ACTIVE_CONFIG_NAME, AZURE_CONFIG_DIR, KUBECONFIG, and OCTX_SSH_CONFIG.

Check the current project:

octx current

Diagnose the local setup:

octx doctor

What Switch Does

After selecting a project, octx:

• exports OPSCTX_PROJECT
• exports or unsets AWS_PROFILE
• exports or unsets ALIBABA_CLOUD_PROFILE
• exports or unsets CODEX_PROFILE
• exports or unsets CLOUDSDK_ACTIVE_CONFIG_NAME
• exports or unsets AZURE_CONFIG_DIR
• exports or unsets KUBECONFIG
• exports or unsets OCTX_SSH_CONFIG
• writes a per-project SSH config under ~/.config/opsctx/ssh/ when ssh_config is configured

After selecting unset, octx:

• unsets OPSCTX_PROJECT
• unsets AWS_PROFILE
• unsets ALIBABA_CLOUD_PROFILE
• unsets CODEX_PROFILE
• unsets CLOUDSDK_ACTIVE_CONFIG_NAME
• unsets AZURE_CONFIG_DIR
• unsets KUBECONFIG
• unsets OCTX_SSH_CONFIG

CODEX_PROFILE is intentionally just an environment variable. The codex shell wrapper maps it to:

codex --profile "$CODEX_PROFILE"

aliyun_profile maps to ALIBABA_CLOUD_PROFILE, which Alibaba Cloud CLI uses as the active profile for the current terminal session.

gcloud_config maps to CLOUDSDK_ACTIVE_CONFIG_NAME, which Google Cloud SDK uses as the active named configuration for the current terminal session.

azure_config_dir maps to AZURE_CONFIG_DIR, which Azure CLI uses as the active config directory for the current terminal session.

kubeconfig maps to KUBECONFIG. octx does not run kubectl config use-context or modify kubeconfig files.

ssh_config creates a generated per-project SSH config and maps it to OCTX_SSH_CONFIG. The shell ssh wrapper passes it to ssh -F, so each terminal keeps its own SSH context.

Files

Default paths:

| Purpose | Path | | --- | --- | | Config | ~/.config/opsctx/config.yaml | | Generated SSH configs | ~/.config/opsctx/ssh/*.config | | Legacy SSH include | ~/.config/opsctx/ssh-current |

The config directory name is still opsctx for backward compatibility with early local installs. state.yaml and ssh-current are legacy files and are not used as active context.

Commands

octx          # open picker and switch context
octx init     # write a sample config
octx current  # print the current project code
octx doctor   # diagnose config, profiles, shell env, SSH, and install path
octx version  # print octx version

Doctor

octx doctor checks the local setup without changing files or calling cloud APIs. It validates the core config, warns about legacy ssh-current wiring, reports optional kubeconfig, AWS, Aliyun, Codex, GCloud, and Azure CLI setup as warnings, shows CLI paths under [global] for configured profile integrations, checks the current shell environment, and checks the octx binary resolved from PATH.

Environment checks are intentionally quiet for optional profiles that are unset as expected. doctor reports environment rows when an active configured value matches or when a value needs attention.

Optional integrations are never required for a project. doctor exits non-zero only for core config errors, not because a machine does not have a configured cloud profile or local file.

Doctor output is grouped by [global] and one section per project.

Release

This repository publishes npm packages through GitHub Actions and npm Trusted Publishing.

Release and documentation rules live in RULES.md. Update it when the release flow changes.

Packages:

• @ninj4dkill4/octx
• @ninj4dkill4/octx-linux-x64
• @ninj4dkill4/octx-linux-arm64
• @ninj4dkill4/octx-darwin-x64
• @ninj4dkill4/octx-darwin-arm64

Publish a new version by pushing a semver tag:

git tag vX.Y.Z
git push origin vX.Y.Z

The workflow builds native binaries, prepares package manifests from the tag version, runs dry-run packs, publishes to npm, verifies the npm version, smoke tests installing the exact tag version, and creates the GitHub Release.

Roadmap

• Environment-level switching.
• Terraform workspace or variable support.
• Vault or secrets manager integration.
• Directory-aware auto-switching.

License

MIT