From ff2debe4a113ec886712f3a0c3411fd5f7478ecb Mon Sep 17 00:00:00 2001 From: dohertj2 Date: Wed, 29 Apr 2026 10:11:17 -0400 Subject: [PATCH] Document Infisical CLI setup for client machines --- infisical.md | 133 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) diff --git a/infisical.md b/infisical.md index 4b71ea8..2aa009b 100644 --- a/infisical.md +++ b/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 -- `) 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-` (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="" +export INFISICAL_UNIVERSAL_AUTH_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','','User') +[Environment]::SetEnvironmentVariable('INFISICAL_UNIVERSAL_AUTH_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///]`) directly executable, drop this one-liner alias / function in your shell rc: + +```bash +secret() { # secret // + 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": "", + "INFISICAL_CLIENT_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`.