Utility Scripts
The scripts/ directory contains helper utilities for inventory management, Bitwarden integration, and operational tasks. They are not deployed to machines — they run on your local development machine or during CI.
Inventory Management
register-machine.py
Register a new machine in inventory.yml and create its host_vars file.
Usage:
python3 scripts/register-machine.py <name> [type] [path-to-inventory.yml]
Arguments:
<name>— machine name (e.g.,kanpur,goa)[type]— group/machine type:desktop,server,vps,termux_hosts(default:desktop)[path-to-inventory.yml]— inventory file path (default:inventory.yml)
What it does:
- Adds the machine to the
all.hostssection - Adds it to the specified group under
all.children - Sets
ansible_host: localhostandansible_connection: local - Creates
host_vars/<name>.ymlwith a template
Example:
python3 scripts/register-machine.py goa server
purge-machine.py
Remove a machine from inventory.yml and its host_vars file. Mirror of register-machine.py.
Usage:
python3 scripts/purge-machine.py <name> [path-to-inventory.yml]
Important: Does NOT delete the corresponding Bitwarden SSH key item — you can re-onboard the machine later using the same name.
Example:
python3 scripts/purge-machine.py matrix
nmap-inventory.sh
Scan the LAN using nmap and cross-reference with Tailscale to show network status.
Usage:
./scripts/nmap-inventory.sh [CIDR]
Arguments:
[CIDR]— network range to scan (default:192.168.0.0/24). Override with a different subnet.
Output columns:
- IP address
- MAC address
- Hostname (reverse DNS or nmap service detection)
- Tailscale status (online/offline)
Prerequisites:
nmapinstalled- Tailscale running and authenticated
- Network access to the scanned range
Example:
./scripts/nmap-inventory.sh 10.0.0.0/24
Bitwarden Integration
bw-resolve.sh
Resolve a usable BW_SESSION for local and remote operations. Tries multiple fallback tiers.
Usage:
./scripts/bw-resolve.sh local
./scripts/bw-resolve.sh remote <host>
Modes:
-
local— Resolve a session on your local machine. Returnsexport BW_SESSION=...on stdout or exits 1 if unlock fails. -
remote <host>— Unlock Bitwarden on a remote machine, export that session inline overssh -t, and return it. Used byjust apply-remoteto drive secret-dependent tasks on the target.
Session resolution order:
- Existing
BW_SESSIONenvironment variable (if still valid) - Cached session in
/tmp/bw_session(if not expired) - Interactive
bw unlockprompt (asks for master password)
Example — local:
eval "$(./scripts/bw-resolve.sh local)"
bw list items # Now BW_SESSION is set
Example — remote:
./scripts/bw-resolve.sh remote himachal
# Executes commands on himachal with Bitwarden access
bw-unlock.sh
Simpler variant of bw-resolve.sh — resolves a session on the local machine only.
Usage:
./scripts/bw-unlock.sh
Output: Prints <session-token> on stdout, or exits 1 if all tiers fail.
bw-seed-ssh-keys.sh
Pull SSH public keys from all online machines and seed them into a Bitwarden collection.
Usage:
./scripts/bw-seed-ssh-keys.sh
What it does:
- Connects to each machine in the online fleet
- Retrieves their
~/.ssh/id_ed25519.pub - Creates Bitwarden login items named
james@<hostname>with the public key in the password field - Updates existing items in place (safe to re-run)
Prerequisites:
- SSH access to all machines (keys already in
~/.ssh/authorized_keys) - Bitwarden CLI (
bw) authenticated - Tailscale or direct network access to all machines
Run once: Before onboarding a new machine, so their SSH keys are available in Bitwarden during setup.
bw-seed-kube.sh
Seed kubeconfig and talosconfig from this machine into Bitwarden.
Usage:
./scripts/bw-seed-kube.sh
What it does:
- Exports your local
~/.kube/configto Bitwarden as a secure note - Exports your local
~/.talos/configto Bitwarden - Updates existing items in place
Prerequisites:
- kubectl configured with cluster access
- talosctl configured with cluster access
- Bitwarden CLI (
bw) authenticated
Use when: You've set up cluster access locally and want to share it to other machines.
Apply and Status
record-apply.py
Record the outcome of a just apply run for tracking and status checks.
Usage:
python3 scripts/record-apply.py <exit-code> [label] [skip-tags]
Arguments:
<exit-code>— exit code from the Ansible apply (0 = success, non-zero = failure)[label]— optional descriptive label (default: inferred from context)[skip-tags]— optional comma-separated skip tags (for partial applies)
Output: Writes to ~/.cache/dotfiles/last-apply.json with:
- Timestamp
- Exit code (0 = success, 1 = failure)
- Label and skip tags (if provided)
Used by: just doctor to check health status and flag old or failed applies.
last-apply-status.py
Pretty-print the last recorded apply status. Used by just doctor.
Usage:
python3 scripts/last-apply-status.py
Exit codes:
0— apply succeeded and timestamp is recent (< 48 hours)1— apply failed OR timestamp is stale (≥ 48 hours)
Output: Human-readable status with timestamp, result, and any tags.
online_hosts.py
Print the online fleet hosts: inventory hosts whose tailnet name is online, excluding the vps group and this machine. A host's tailnet name is its tailnet_name in inventory.yml (e.g. termux → pixel-9a), otherwise its inventory name. A peer's name is its MagicDNS short name; the OS HostName is used only when a peer has no DNSName, because HostNames aren't unique (several phones report localhost).
Usage:
python3 scripts/online_hosts.py # inventory names, space-separated
python3 scripts/online_hosts.py --peers # raw online tailnet names, one per line
Used by: just _online_hosts (bulk applies, doctor-fleet, push-terminfo), and roles/ssh_mesh, which runs --peers on the target via the script module.
Silently fails: If Tailscale is not running, returns empty output (so scripts gracefully degrade).
Cluster and Infrastructure
kubevirt-node
Operations on KubeVirt nodes for the test cluster.
Usage:
./scripts/kubevirt-node [command] [node-name]
Supported commands:
list— List all KubeVirt test nodesstart <node>— Power on a nodestop <node>— Power off a nodestatus <node>— Show node status
Prerequisites:
kubectlconfigured with cluster access- Permission to manage VirtualMachine resources
sync-brews.sh
Sync the Homebrew package state: fetch the current installed packages from Homebrew and update group_vars/all.yml with the new list.
Usage:
./scripts/sync-brews.sh
What it does:
- Runs
brew list --formulaeandbrew list --casks - Extracts the current package list
- Updates the
homebrew_packagesandhomebrew_caskssections ingroup_vars/all.yml - Prints a diff so you can review changes
Use when: You've manually installed packages with brew install and want to record them in the inventory for automated management.
ess-render-values.py
Historical helper for rendering ESS Helm values for the terminated AWS Talos cluster from Bitwarden. It does not configure the standalone OCI deployment.
Usage:
python3 scripts/ess-render-values.py < ess-helm-values-template.yml > values.yml
What it does:
- Reads the
ess-helm-valuessecure note from Bitwarden - Applies environment and variable substitutions (e.g.,
${DOMAIN}) - Outputs the rendered Helm values to stdout
Previously used by: AWS cluster deployment pipelines to generate Helm configurations.
Prerequisites:
bwCLI authenticated with Bitwarden vault access- The
ess-helm-valuessecure note exists in Bitwarden
Prerequisites and Setup
All scripts assume:
- Python 3 (for
.pyscripts) - Bash (for
.shscripts) - Bitwarden CLI (
bw) installed and configured when BW scripts are used - SSH access to target machines (for remote operations)
- Tailscale installed for machine discovery (for inventory scripts)
Set up Bitwarden CLI once:
brew install bitwarden-cli # macOS
# or: apt-get install bw # Linux
bw login <email>
Session tokens are cached locally in /tmp/ for convenience; they expire and are renewed automatically.