Connections & credentials

Per-environment credential isolation, CLI profiles, and the read-only safety contract.

reckon uses per-environment, folder-specific credentials. .envrc resolves RECKON_ENV, pins XDG_CONFIG_HOME to .config/<env>/ inside the clone, and loads credentials in order — .env.common, then .env.<env>, then .env.<env>.local, later winning. On native Windows, dot-source scripts/activate.ps1 -Env <env> for the same result.

Because each environment gets its own config directory, production, staging, and UAT never share credential state.

Choosing an environment

./scripts/reckon use staging     # persists in .reckon-env, survives new shells
./scripts/reckon status          # confirm what is active and how it resolved

Precedence is RECKON_ENV (exported) → .reckon-env (file) → production. An unrecognised value in either fails closed: no credentials are loaded at all, rather than silently selecting a real environment.

Preferred: environment credentials

Setup seeds .env.production from .env.example. Populate it with real credentials — create .env.staging and .env.uat the same way as you need them:

$EDITOR .env.production
direnv allow            # optional, see below

Values left at their .env.example defaults (replace_me, *.example.com) are treated as unconfigured. ./scripts/reckon preflight will report the integration as unavailable rather than claim a connection that cannot work.

direnv is optional

direnv auto-loads .envrc when you cd in. If it is not installed or not hooked into your shell, nothing warns you — .envrc simply never runs and the CLIs fall back to saved profiles. ./scripts/reckon doctor detects exactly this. To activate a shell without direnv:

eval "$(./scripts/reckon env)"

Kafka and database clients read credentials directly from this environment. The workspace also derives the RPK_* settings from the configured KAFKA_* values and points AWS at repo-local config files.

Fallback: saved CLI profiles

Interactive profiles remain available for tools that support them:

grafana login
jenkins login
cubeapm login
aws configure
gh auth login

Their state stays under the clone:

.config/<env>/grafana-cli/config.yaml
.config/<env>/jenkins-cli/config.yaml
.config/<env>/cubeapm-cli/config.yaml
.config/<env>/aws/{config,credentials}
.config/<env>/gh/{config.yml,hosts.yml}

A saved profile counts as configured even when the matching environment variables are absent — which is how gh auth login alone is enough for GitHub.

The read-only contract

Isolation prevents credential mix-ups; it does not make a privileged credential safe. The actual write barrier is a read-only database role or Kafka principal. The workspace layers client defaults and agent rules on top:

PostgreSQL receives default_transaction_read_only=on through PGOPTIONS.
MySQL receives a read-only session init command through $XDG_CONFIG_HOME/mysql/my.cnf; always pass that file to mysql.
ClickHouse requires a server-side readonly=1 user profile and --readonly=1 on every client invocation; it activates when CLICKHOUSE_HOST is set.
MongoDB uses secondary read preference, which controls routing but does not provide authorization.
kcat, rpk, kubectl, and redis-cli are read-only by documented usage, so only the approved read-shaped commands are allowed.
Every psql, mysql, mongosh, and clickhouse query should still prompt for approval.

For database work, re-read the Database safety contract in CLAUDE.md. EXPLAIN non-trivial reads first, put a LIMIT on every SELECT, and invoke MySQL as mysql --defaults-extra-file="$XDG_CONFIG_HOME/mysql/my.cnf".

Verify connections

Use one safe read per tool before an investigation. These checks also expose a wrong profile or missing environment variable early:

grafana user current -o json
jenkins status -o json
cubeapm metrics label-values service -o json
aws sts get-caller-identity --output json
gh auth status
rpk cluster info
kubectl get ns
redis-cli -u "$REDIS_URL" PING

Database and Kafka verification commands are documented in README.md; review their safety notes before running them against production.