Prerequisites & Tool Setup

This document lists all CLI tools needed to work with the Ecommercen K8s manifests repository (github.com/Advisable-com/ecnv4_manifests), along with installation instructions, authentication setup, and verification commands.

Tip: Instead of reading this doc top to bottom, run the devops-setup agent — it detects your OS, checks what's installed, and gives you only the steps you need.

Quick Check

Run these to verify your setup:

kubectl get nodes                                # Cluster access (uses your current-context)
argocd version --client                          # ArgoCD CLI
terraform version                                # Terraform
bw status                                        # Bitwarden CLI
kubeseal --version                               # Sealed Secrets CLI
jq --version                                     # JSON processor
python3 -c "import yaml; print('ok')"            # Python + PyYAML
git --version                                    # Git

---

kubectl

Purpose: Kubernetes cluster management — pods, nodes, logs, exec, port-forward.

Install

Platform	Command
Windows (winget)	winget install Kubernetes.kubectl
Windows (choco)	choco install kubernetes-cli
Windows (scoop)	scoop install kubectl
macOS (Homebrew)	brew install kubectl
Arch/Manjaro (pacman)	sudo pacman -S kubectl
Debian/Ubuntu (apt)	Via kubernetes apt repo
WSL	Follow the Linux instructions for your WSL distro

Auth Setup

1. Obtain the kubeconfig file — pull the current ecnv4 admin kubeconfig entry from the Bitwarden vault, or ask a teammate. (Historically the initial bootstrap wrote one to ansible/playbooks/tmp/rke.yml; that playbook is legacy and not the path you'd use today.)
2. Place it at ~/.kube/config (Linux/macOS/WSL) or %USERPROFILE%\.kube\config (Windows).
3. Note the context name in your kubeconfig for this cluster. Scripts and agents in this repo default to ecnv4 — you can either:
   • Rename your context to match: kubectl config rename-context <original-name> ecnv4
   • Or set the KUBECTL_CONTEXT env var to your context name (bash: export KUBECTL_CONTEXT=<name>, PowerShell: $env:KUBECTL_CONTEXT = "<name>")
4. Verify:

   kubectl get nodes

For getting + configuring your kubeconfig (merging files, renaming contexts, switching between clusters), see Authenticating to the cluster.

---

argocd CLI

Purpose: ArgoCD application management — sync, list, diff, rollback.

Install

Platform	Command
Windows (choco)	choco install argocd-cli
Windows (scoop)	scoop install argocd
Windows (manual)	Download from GitHub releases
macOS (Homebrew)	brew install argocd
Arch/Manjaro	yay -S argocd-bin
Debian/Ubuntu	Download from GitHub releases
WSL	Download Linux binary from GitHub releases

Usage

Day-to-day CLI usage looks like:

argocd app list
argocd app sync <app-name>

If Cloudflare Zero Trust blocks your session, use the untracked/scripts/argo.sh wrapper — it port-forwards to the in-cluster argocd-server Service and auto-authenticates. See GitOps & ArgoCD → the argo.sh wrapper for details.

Verify

argocd version --client

---

terraform

Purpose: Hetzner Cloud infrastructure provisioning — servers, networks, firewalls. See Terraform docs.

Install

Platform	Command
Windows (winget)	winget install Hashicorp.Terraform
Windows (choco)	choco install terraform
Windows (scoop)	scoop install terraform
macOS (Homebrew)	brew install terraform
Arch/Manjaro (pacman)	sudo pacman -S terraform
Debian/Ubuntu (apt)	Via HashiCorp apt repo
WSL	Follow the Linux instructions for your WSL distro

Usage

Always use ./tf.sh instead of bare terraform — it injects Hetzner API token and RKE2 join token from Bitwarden:

cd terraform && ./tf.sh plan

Requires Bitwarden CLI to be unlocked (see below).

Verify

terraform version

---

bw (Bitwarden CLI)

Purpose: Secret injection for Terraform (tf.sh) and autoscaler config (build-autoscaler-config.sh).

Install

Platform	Command
Windows (choco)	choco install bitwarden-cli
Windows (scoop)	scoop install bitwarden-cli
Windows (manual)	Download from GitHub releases
macOS (Homebrew)	brew install bitwarden-cli
Arch/Manjaro	yay -S bitwarden-cli
Debian/Ubuntu	sudo snap install bw or download from GitHub releases
WSL	sudo snap install bw or download Linux binary

Auth Setup (interactive)

For manual terminal use:

1. Log in: bw login
2. Unlock: export BW_SESSION=$(bw unlock --raw)
3. Verify: bw status — should show "status": "unlocked"

Auth Setup (non-interactive — recommended)

This approach lets Claude Code agents and automation scripts unlock the vault without interactive input. It uses Bitwarden's personal API key and the --passwordenv flag documented in the CLI reference.

Step 1: Get your API key from the Bitwarden web vault → Account Settings → Security → Keys → API Key.

Step 2: Create a credentials file:

Linux/macOS/WSL:

cat > ~/.config/bw-credentials << 'EOF'
export BW_CLIENTID="user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export BW_CLIENTSECRET="xxxxxxxxxxxxxxxxxxxxxxxxxx"
export BW_PASSWORD="your-master-password"
EOF
chmod 600 ~/.config/bw-credentials

Windows (PowerShell):

@"
set BW_CLIENTID=user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
set BW_CLIENTSECRET=xxxxxxxxxxxxxxxxxxxxxxxxxx
set BW_PASSWORD=your-master-password
"@ | Out-File -Encoding ascii "$env:USERPROFILE\.config\bw-credentials"

Step 3: Verify it works:

source scripts/bw-unlock.sh && bw status

The repo provides scripts/bw-unlock.sh — a helper that sources the credentials file, logs in via API key if needed, and unlocks the vault non-interactively. It's designed to be sourced (not executed) so BW_SESSION is exported into the calling shell:

source scripts/bw-unlock.sh && ./terraform/tf.sh plan
source scripts/bw-unlock.sh && ./untracked/secrets/build-autoscaler-config.sh

Claude Code agents use this automatically when they need Bitwarden access. If the credentials file is missing, they'll ask you to set it up.

Verify

bw --version

---

helm

Purpose: Helm chart research — search versions, inspect default values, render templates, diff configurations. Used by the helm-searcher agent. Not used for installing or upgrading charts — ArgoCD handles that.

Install

Platform	Command
Windows (winget)	winget install Helm.Helm
Windows (choco)	choco install kubernetes-helm
Windows (scoop)	scoop install helm
macOS (Homebrew)	brew install helm
Arch/Manjaro (pacman)	sudo pacman -S helm
Debian/Ubuntu	See Helm install docs
WSL	Follow the Linux instructions for your WSL distro

Verify

helm version

---

hcloud (Hetzner Cloud CLI)

Purpose: Hetzner Cloud operations — inspect servers, load balancers, networks, firewalls, metrics.

Install

Platform	Command
Windows (winget)	winget install HetznerCloud.cli
Windows (scoop)	scoop install hcloud
macOS (Homebrew)	brew install hcloud
Arch/Manjaro (pacman)	sudo pacman -S hcloud
Debian/Ubuntu	Download from GitHub releases
WSL	Follow the Linux instructions for your WSL distro

Auth Setup

Option A — hcloud context (interactive, persists locally):

hcloud context create ecnv4
# Paste the Hetzner Cloud API token when prompted

Option B — Bitwarden (non-interactive, shared team token):

source scripts/bw-unlock.sh
export HCLOUD_TOKEN=$(bw get password "ecnv4 - hcloud token")
hcloud server list   # verify

Option C — local.env (set HCLOUD_TOKEN directly if you have the token):

# In local.env:
export HCLOUD_TOKEN="your-token-here"

Verify

hcloud version
hcloud server list

---

kubeseal

Purpose: Encrypts Kubernetes Secrets into SealedSecrets using the in-cluster controller's public key.

Install

Platform	Command
Windows	Download from GitHub releases — get the kubeseal-*-windows-amd64.tar.gz
macOS (Homebrew)	brew install kubeseal
Arch/Manjaro	yay -S kubeseal-bin
Debian/Ubuntu	Download from GitHub releases
WSL	Download Linux binary from GitHub releases

Usage

kubeseal contacts the sealed-secrets controller in-cluster to fetch the encryption key. Requires kubectl access to the cluster.

cd untracked/secrets && ./seal-all.sh
# or, for a single file:
./seal.sh seal <path>          # namespace-scoped
./seal.sh cluster-seal <path>  # cluster-wide

Verify

kubeseal --version

---

jq

Purpose: JSON processing — used by build-autoscaler-config.sh and various scripts.

Install

Platform	Command
Windows (winget)	winget install jqlang.jq
Windows (choco)	choco install jq
Windows (scoop)	scoop install jq
macOS (Homebrew)	brew install jq
Arch/Manjaro (pacman)	sudo pacman -S jq
Debian/Ubuntu (apt)	sudo apt install -y jq
WSL	sudo apt install -y jq

Verify

jq --version

---

python3 + PyYAML

Purpose: App update scripts (check-updates.py, do-updates.py) and free port detection in the ArgoCD CLI wrapper.

Install

Platform	Command
Windows (winget)	winget install Python.Python.3 then pip install pyyaml
Windows (choco)	choco install python then pip install pyyaml
Windows (scoop)	scoop install python then pip install pyyaml
macOS (Homebrew)	brew install python3 && pip3 install pyyaml
Arch/Manjaro (pacman)	sudo pacman -S python python-yaml
Debian/Ubuntu (apt)	sudo apt install -y python3 python3-yaml
WSL	sudo apt install -y python3 python3-yaml

Verify

python3 -c "import yaml; print('PyYAML:', yaml.__version__)"

On Windows, python3 may be python or py instead.

---

git

Purpose: Version control — committing and pushing GitOps changes.

Install

Platform	Command
Windows (winget)	winget install Git.Git
Windows (choco)	choco install git
Windows (scoop)	scoop install git
macOS (Homebrew)	brew install git (or use Xcode CLI tools)
Arch/Manjaro (pacman)	sudo pacman -S git
Debian/Ubuntu (apt)	sudo apt install -y git
WSL	sudo apt install -y git

Auth Setup

SSH key must be registered with GitHub for push access:

ssh -T git@github.com

Verify

git --version

---

docker (optional)

Purpose: Building the ecnv4-toolbox image. Not required for day-to-day GitOps work.

Install

Platform	Command
Windows	Docker Desktop or winget install Docker.DockerDesktop
macOS	Docker Desktop or brew install --cask docker
Arch/Manjaro	sudo pacman -S docker && sudo systemctl enable --now docker
Debian/Ubuntu	Docker Engine
WSL	Docker Desktop with WSL 2 backend

Verify

docker version

---

Local Overrides

Two gitignored files let you customize behavior without affecting the shared repo:

local.env — Script overrides

Copy local.env.example to local.env and edit. Scripts (the ArgoCD CLI wrapper, bw-unlock.sh) source this automatically.

Common overrides:

• KUBECTL_CONTEXT — your kubectl context name (default: ecnv4)
• BW_CREDENTIALS_FILE — path to your Bitwarden credentials file
• bw_unlock() — custom function to replace the default unlock flow (e.g., wrap your own alias)

CLAUDE.local.md — Claude Code overrides

Create CLAUDE.local.md in the repo root for personal Claude Code instructions that override CLAUDE.md. Examples:

• "My kubectl context is called hetzner-prod"
• "When unlocking Bitwarden, run bwu instead of source scripts/bw-unlock.sh"
• "I prefer terse output with no explanations"

Claude Code reads this file when it exists and applies your preferences over the shared defaults.

---

Agent-to-Tool Dependency Matrix

Agent	kubectl	argocd	helm	hcloud	terraform	bw	kubeseal	jq	python3	git
k8s-manager	required	-	-	-	-	-	-	-	-	-
helm-searcher	-	-	required	-	-	-	-	-	-	-
hcloud-operator	-	-	-	required	-	optional	-	-	-	-
vault-manager	-	-	-	-	-	required	-	-	-	-
terraform-manager	required	-	-	-	required	required	-	-	-	-
secrets-manager	required	-	-	-	-	optional	required	optional	-	-
gitops-commit-pusher	-	-	-	-	-	-	-	-	-	required
k8s-manifest-locator	-	-	-	-	-	-	-	-	-	-
devops-setup	-	-	-	-	-	-	-	-	-	-

"optional" means the tool is only needed for specific operations (e.g., bw for autoscaler config secrets, jq for JSON processing in build scripts).

Scripts also have dependencies:

• ArgoCD CLI wrapper (untracked/scripts/argo.sh) → kubectl, argocd, python3
• tf.sh → terraform, bw, jq
• seal.sh / seal-all.sh → kubectl, kubeseal
• check-updates.py / do-updates.py → python3, PyYAML, git
• build-autoscaler-config.sh → bw, jq, kubectl, kubeseal