Adding a new CLI adapter

An adapter teaches clikae how to switch profiles for a particular CLI tool.

TL;DR

1. Copy lib/adapters/_template.sh to lib/adapters/<your-cli>.sh.
2. Fill in the metadata and the two required hooks.
3. Submit a PR (or keep it local).

cp lib/adapters/_template.sh lib/adapters/gh.sh
# edit
clikae adapters         # your new adapter should appear
clikae init gh personal

The adapter contract

Every adapter is a bash script that defines a set of functions. The dispatcher loads it and calls these hooks. Required functions:

Optional. These are what separate a tank you can switch to from a tank clikae can actually work with — define none and your CLI still switches accounts correctly; define the session ones and it joins the board, the resume picker and clean. Each is independently optional: a caller that doesn't find one degrades honestly rather than pretending. Engines listed are the ones that define it today, as a reference implementation to read.

The classification rule that matters: never key behaviour on "an adapter file exists." antigravity has an adapter file that is a resume-only shim on a launch-only target. clikae_is_target (lib/core/profile_store.sh) is the canonical predicate, and it wins.

The five strategies

Most CLIs fit one of these. Pick the right one and the adapter is usually 10 lines.

env-dir — env var points at a config DIRECTORY

Examples: Anthropic Claude (CLAUDE_CONFIG_DIR), GitHub CLI (GH_CONFIG_DIR), Google Cloud (CLOUDSDK_CONFIG), Docker (DOCKER_CONFIG), Helm (HELM_CONFIG_HOME).

adapter_meta_strategy() { echo "env-dir"; }
adapter_export_env() { printf 'MY_CFG_DIR=%s\n' "$1"; }
adapter_run() { local d="$1"; shift; MY_CFG_DIR="$d" exec mycli "$@"; }

env-file — env var points at a config FILE

Examples: kubectl (KUBECONFIG), AWS CLI (AWS_CONFIG_FILE, AWS_SHARED_CREDENTIALS_FILE).

In adapter_init, you may want to touch the file or seed it.

adapter_init() { touch "$1/config"; }
adapter_export_env() { printf 'KUBECONFIG=%s/config\n' "$1"; }
adapter_run() { local d="$1"; shift; KUBECONFIG="$d/config" exec kubectl "$@"; }

env-var — env var holds a profile NAME

Examples: AWS CLI (AWS_PROFILE, when used with the shared credentials file).

adapter_export_env() { printf 'AWS_PROFILE=%s\n' "$(basename "$1")"; }
adapter_run() { local d="$1"; shift; AWS_PROFILE="$(basename "$d")" exec aws "$@"; }

flag — wrapper injects a --profile-style flag

Examples: doctl (--context), aws --profile (when not using env vars).

adapter_export_env() { :; }   # nothing for the alias path; the flag does the work
adapter_run() { local d="$1"; shift; exec doctl --context "$(basename "$d")" "$@"; }

(clikae alias doesn't make as much sense for flag strategies — it would generate an alias that loses extra arg-passing. We're considering wrapping flag-strategy adapters in a small shim script in v0.2.)

subcommand — CLI has its own activate/use command

Examples: gcloud config configurations activate, kubectl config use-context.

adapter_run() {
  local d="$1"; shift
  gcloud config configurations activate "$(basename "$d")" >/dev/null
  exec gcloud "$@"
}

Conventions

• Use exec in adapter_run. This lets signals (Ctrl-C) reach the child cleanly.
• The <profile_dir> you receive is ~/.clikae/profiles/<cli>/<name>/. You're free to lay out anything inside it.
• Never write outside the profile dir without good reason.
• Keep the file dependency-free: pure POSIX-ish bash, no Python/Node.

Testing your adapter

# From the repo root:
PATH="$PWD/bin:$PATH" clikae adapters     # your CLI shows up?
clikae init <cli> testprof
clikae run <cli> testprof
clikae remove <cli> testprof --force

Add a bats test under tests/bats/adapters/<cli>.bats, then run the gate:

bash scripts/test.sh        # shellcheck -S warning + the whole bats suite

One thing will surprise you. If your adapter uses env-dir / env-file / env-var / flag, you must also add its row to the $script:ClikaeAdapters table in powershell/Clikae.psm1 — tests/bats/compat.bats asserts the two stay in sync, and it is a blocking gate even though Windows itself is an unsupported community port whose own CI never blocks. Copy the shape of a neighbouring row; you don't need PowerShell installed to satisfy it (the test greps source, it doesn't run pwsh).

A subcommand-strategy adapter is exempt: that strategy marks a capability shim on a launch-only target rather than a switchable engine, and the test skips it.