---

name: ctx description: | Unified developer workspace and identity switching with ctx CLI. Covers workspace profile creation (TOML format), switching developer identities across AWS, Git, GitHub CLI, Vercel, kubectl, npm, gcloud, Docker, Terraform, and 1Password. Shell hook setup for auto-switching on cd. Secret resolution via 1Password CLI, macOS Keychain, and shell commands. Directory binding with .ctxrc files and global glob patterns. Synthesizes ctx source code and architecture documentation.

Trigger phrases: "ctx", "ctx switch", "ctx workspace", "developer identity", "switch AWS profile", "switch git identity", "workspace profile", "auto-switch on cd", "shell hook", "ctx new", "ctx bind", ".ctxrc", "developer context", "identity switching", "ctx setup", "ctx doctor", "workspace TOML", "ctx shell-hook", "secret resolution", "1password ctx", "ctx off", "ctx current", "ctx diff", "ctx import-direnv", "ctx capture", "ctx login", "switch workspace", "ctx status"

ctx — Developer Identity Switcher

One command switches your entire developer identity: AWS, Git, GitHub, Vercel, kubectl, npm, gcloud, Docker, Terraform, 1Password — atomically.

Core Concepts

1. Workspace profiles are TOML files declaring which accounts, credentials, and env vars to use per project context.
2. Adapters translate workspace config into env vars, symlinks, or CLI commands — each tool gets the mechanism it needs.
3. Shell eval pattern — ctx prints export/unset commands that the shell evals. Same proven approach as direnv, nvm, pyenv.
4. Auto-switching — shell hook detects directory changes and activates the bound workspace. Zero manual switching.
5. Secrets never stored in plaintext — resolved at switch time from 1Password, macOS Keychain, or shell commands.

Quick Start

"Set up ctx from scratch"

1. Install: go install github.com/elad12390/ctx@latest
2. Create workspace: ctx new company-a
3. Edit profile: ctx edit company-a (opens $EDITOR)
4. Add shell hook to rc file:
   • zsh: eval "$(ctx shell-hook zsh)"
   • bash: eval "$(ctx shell-hook bash)"
   • fish: ctx shell-hook fish | source
5. Switch: ctx switch company-a
6. Bind directory: cd ~/work/company-a && ctx bind company-a

See references/workspace-profiles.md for full TOML schema.

"Switch to a different identity"

ctx switch <name>        # activate workspace
ctx off                  # deactivate, restore previous state
ctx current              # show active workspace
ctx diff <name>          # preview changes before switching

"Auto-switch when I cd into a project"

ctx bind company-a       # creates .ctxrc in current dir
ctx unbind               # removes .ctxrc

Or use global patterns in ~/.config/ctx/config.toml:

[directories]
"~/work/company-a-*" = "company-a"
"~/personal/*"        = "personal"

See references/directory-binding.md for resolution order.

"Something isn't working"

ctx doctor               # check which tools are installed
ctx status               # show active workspace state
CTX_DEBUG=1 ctx switch x # verbose debug output

See references/commands-reference.md for all commands.

Decision Trees

Which adapter mechanism does my tool use?

Tool	Mechanism	What ctx sets
AWS	Env + config files	AWS_PROFILE, AWS_CONFIG_FILE
Git	Env vars	GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_SSH_COMMAND
GitHub CLI	Config dir redirect	GH_CONFIG_DIR → store/
Vercel	Config dir redirect	VERCEL_GLOBAL_CONFIG → store/
kubectl	Env var	KUBECONFIG
npm	Config + registry	NPM_CONFIG_USERCONFIG, NPM_CONFIG_REGISTRY
gcloud	Config dir redirect	CLOUDSDK_CONFIG → store/
Docker	Config dir redirect	DOCKER_CONFIG → store/
Terraform	Config file	TF_CLI_CONFIG_FILE → store/
1Password	Config dir redirect	OP_CONFIG_DIR → store/

See references/adapters.md for full adapter details.

How do I reference a secret?

Source	TOML Syntax
1Password	{ source = "1password", ref = "op://vault/item/field" }
Shell command	{ source = "command", ref = "pass show key" }
Plain text	"literal-value" (non-secrets only)

See references/secrets-and-env.md for secret resolution.

Which shell hook do I need?

Shell	Setup
zsh	eval "$(ctx shell-hook zsh)" in ~/.zshrc
bash	eval "$(ctx shell-hook bash)" in ~/.bashrc
fish	ctx shell-hook fish | source in config.fish

See references/shell-integration.md for hook internals.

File Layout

~/.config/ctx/
  config.toml            # Global settings (directory patterns, defaults)
  workspaces/            # One TOML file per workspace profile
    company-a.toml
    personal.toml
  store/                 # Managed config snapshots (for symlink adapters)
    company-a/
      gh/hosts.yml
      vercel/
      aws/config
  state.json             # Runtime: active workspace, previous env for rollback

Reference Files

File	Contents
references/workspace-profiles.md	Full TOML schema, all sections, EnvValue types, naming rules, examples
references/adapters.md	All 13 adapters, env vars, config paths, symlink vs env mechanism
references/shell-integration.md	Shell hook setup, auto-switching internals, eval pattern
references/secrets-and-env.md	Secret sources, env var resolution, reference syntax
references/directory-binding.md	.ctxrc files, global patterns, bind/unbind, import-direnv
references/commands-reference.md	All CLI commands, flags, usage examples