Document Infisical CLI setup for client machines

infisical.md

@@ -84,6 +84,139 @@ docker exec infisical-db pg_dump -U infisical -d infisical | gzip > /mnt/share/b
 
 Restore: stop the stack, drop and recreate the DB, `gunzip < dump.sql.gz | docker exec -i infisical-db psql -U infisical -d infisical`, start the stack. Whatever encryption key was in `defaults/main.yml` at backup time must still be in place — the restored ciphertext is only readable with the same `ENCRYPTION_KEY`.
 
+## Client setup (CLI on other machines)
+
+Goal: from any host that needs a credential, run `infisical secrets get …` (or `infisical run -- <cmd>`) instead of finding the value in a `.md` file.
+
+### 1. Create a per-host Machine Identity
+
+One per host — never share. Each is independently revocable and shows up cleanly in the audit log.
+
+1. https://infisical.dohertylan.com → **Org Settings → Access Control → Identities → Add**
+2. Name it `claude-<hostname>` (e.g., `claude-mac`, `claude-ww-vm`, `claude-docker`). Auth method: **Universal Auth**.
+3. Open the new identity → **Client Secrets** → **Create Client Secret** → save the `client_id` + `client_secret` (only shown once).
+4. (Optional but recommended) Open the identity → **Authentication → Universal Auth** → set **Client Secret Trusted IPs** to `10.100.0.0/24` so the credential is unusable off-LAN.
+5. Open the **Homelab** project → **Access Control → Identities → Add** → pick the new identity, role **Viewer** (read-only). Promote to Developer/Admin only if the host needs to write secrets.
+
+### 2. Install the CLI
+
+**Linux (Debian/Ubuntu/Trixie):**
+```bash
+curl -1sLf 'https://artifacts-cli.infisical.com/setup.deb.sh' | sudo -E bash
+sudo apt-get install -y infisical
+```
+
+**macOS:**
+```bash
+brew install infisical/get-cli/infisical
+```
+
+**Windows (PowerShell, admin):**
+```powershell
+winget install --id Infisical.InfisicalCLI -e
+# or:
+scoop bucket add main; scoop install infisical
+```
+
+Verify with `infisical --version`.
+
+### 3. Configure auth + endpoint
+
+The CLI reads `INFISICAL_API_URL` for the host (defaults to Infisical Cloud — must be overridden for self-hosted) and either env vars or a saved login for credentials. Recommended: env vars in your shell rc / Windows user env.
+
+**Linux/macOS** (`~/.bashrc`, `~/.zshrc`):
+```bash
+export INFISICAL_API_URL=https://infisical.dohertylan.com
+export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID="<client-id>"
+export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET="<client-secret>"
+```
+
+**Windows** (PowerShell — sets persistent user env):
+```powershell
+[Environment]::SetEnvironmentVariable('INFISICAL_API_URL','https://infisical.dohertylan.com','User')
+[Environment]::SetEnvironmentVariable('INFISICAL_UNIVERSAL_AUTH_CLIENT_ID','<client-id>','User')
+[Environment]::SetEnvironmentVariable('INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET','<client-secret>','User')
+# Open a new shell for these to take effect.
+```
+
+Each `infisical` command will use Universal Auth automatically when these are set. No `infisical login` needed.
+
+### 4. Verify
+
+```bash
+# Should print one or more secrets from the homelab project
+infisical secrets --env=infrastructure --path=/esxi --silent
+
+# Get a single value (the GOVC password):
+infisical secrets get GOVC_PASSWORD --env=infrastructure --path=/esxi --plain
+
+# Run a command with secrets injected as env vars:
+infisical run --env=infrastructure --path=/esxi -- printenv GOVC_PASSWORD
+```
+
+If the project ID can't be resolved automatically, pin it:
+```bash
+infisical secrets get GOVC_PASSWORD \
+  --projectId=e36459c8-b071-4b86-a43c-795b31e75584 \
+  --env=infrastructure --path=/esxi --plain
+```
+
+### 5. Common usage patterns
+
+```bash
+# govc — fetch the password into env via `infisical run`, no plaintext on disk
+infisical run --env=infrastructure --path=/esxi -- \
+  bash -c 'GOVC_URL=https://10.2.0.12/sdk GOVC_USERNAME=govc GOVC_INSECURE=true \
+           govc vm.info WW_DEV_VM'
+
+# .NET app reads SQL_DEV_SA_PWD from env at startup
+infisical run --env=dev --path=/lmxopcua -- \
+  dotnet run --project src/ZB.MOM.WW.OtOpcUa.Server
+
+# Docker compose with secret env injection
+infisical run --env=apps --path=/gitea -- docker compose up -d
+
+# Shell into one secret quickly:
+PWD=$(infisical secrets get WW_VM_ADMIN_PWD --env=infrastructure --path=/windows-hosts --plain)
+sshpass -p "$PWD" ssh dohertj2@10.100.0.48 hostname
+```
+
+### 6. For Claude Code specifically
+
+Claude can shell out to `infisical` like any other CLI tool. To make the pointer syntax in our docs (`[Infisical: homelab/<env>/<folder>/<KEY>]`) directly executable, drop this one-liner alias / function in your shell rc:
+
+```bash
+secret() {  # secret <env>/<path>/<KEY>
+  local arg=$1 env="${arg%%/*}" rest="/${arg#*/}" key="${rest##*/}" folder="${rest%/*}"
+  infisical secrets get "$key" --env="$env" --path="${folder:-/}" --plain
+}
+```
+
+Now `secret infrastructure/esxi/GOVC_PASSWORD` returns the value, matching the doc pointer 1:1.
+
+### 7. (Optional) Infisical MCP server for Claude Code
+
+For native tool access (instead of shell-out), add an MCP server to `~/.claude/mcp.json`. The community package's name and exact config can shift — check the latest before depending on it. Outline:
+
+```jsonc
+{
+  "mcpServers": {
+    "infisical": {
+      "command": "npx",
+      "args": ["-y", "@infisical/mcp-server"],
+      "env": {
+        "INFISICAL_HOST": "https://infisical.dohertylan.com",
+        "INFISICAL_CLIENT_ID": "<id>",
+        "INFISICAL_CLIENT_SECRET": "<secret>",
+        "INFISICAL_PROJECT_ID": "e36459c8-b071-4b86-a43c-795b31e75584"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code and `mcp__infisical__*` tools will be available.
+
 ## Homepage entry
 
 Listed under the **Infrastructure** group on https://home.dohertylan.com — icon `infisical.png` (from dashboard-icons), URL `https://infisical.dohertylan.com`, description "Secrets Management". Added in `roles/homepage/defaults/main.yml`.