v0.3.0

Configuration now resolves through @lostgradient/environmentalist, and the manifest has a home.

The manifest defaults to ~/.battlestation.toml

You can run battlestation diff from anywhere without remembering where the file lives — which is what makes a routine drift check practical.

Configuration resolution

Most-explicit-wins, per key:

Priority	Source
1	--file / --interval flags
2	BATTLESTATION_CONFIGURATION / BATTLESTATION_INTERVAL
3	.env files
4	battlestation.config.{ts,js,json,toml,yaml} in the project
5	~/.battlestation, ~/.config/battlestation/config.*
6	Defaults: ~/.battlestation.toml, weekly

export BATTLESTATION_CONFIGURATION=~/dotfiles/mac.toml
battlestation diff                      # uses the exported path
battlestation diff --file ./other.toml  # a flag still wins

Paths beginning with ~ are expanded; relative paths resolve against the working directory.

Only settings that describe how battlestation runs are configurable this way. Per-invocation switches like --json, --yes, and --dry-run are deliberately excluded — a persisted yes = true would be a footgun rather than a convenience.

Upgrading

If your manifest lives somewhere else, either move it to ~/.battlestation.toml or point at it:

mv ./battlestation.toml ~/.battlestation.toml
# or
export BATTLESTATION_CONFIGURATION=/path/to/battlestation.toml

Explicit --file usage is unchanged.

v0.2.0

Drift detection — the job battlestation is best at is now automatable.

Added

• diff --exit-code exits 1 when the live system no longer matches your TOML file, the same way git diff --exit-code does, in both text and --json modes. Previously diff always exited 0, so battlestation diff || notify could never fire.
• battlestation schedule installs a launchd agent that runs that check hourly, daily, or weekly and posts a macOS notification when something has moved. --uninstall removes it.

The agent only ever notifies — it never applies anything, because a background job that silently changed system settings would be a trap rather than a feature. Its stderr goes to ~/Library/Logs/battlestation-drift-check.log, so a broken agent is diagnosable instead of silent.

battlestation diff --exit-code || echo "settings drifted"
battlestation schedule --interval weekly --file ~/dotfiles/battlestation.toml

Pass an absolute --file path when scheduling: the agent runs outside your shell, with a different working directory.

Install

npx battlestation@0.2.0 capture

Standalone macOS executables are attached below.

v0.1.0

First working release of battlestation — capture macOS system preferences to an auditable TOML file and restore them on a new machine.

Highlights

• ~145 curated settings across keyboard, trackpad, Dock, Mission Control, hot corners, Finder, screenshots, appearance, region formats, menu bar, Control Center, window management, and system behavior — including hidden preferences System Settings doesn't expose
• Structured settings as native TOML: system keyboard shortcuts, text replacements, input sources, Finder view options, default app handlers, and Dock pinned apps
• Declarative apply with diff preview, confirmation prompt, automatic undo snapshots, and process restarts
• doctor validation with auto-fix, plus data-driven value domains (choices/ranges) that generate the file's legend comments
• Agent-friendly: list/get/set/unset file editing, --json output on diff and apply, and a STDIO MCP server (battlestation mcp)
• Dual Node/Bun builds, a full programmatic API, and per-command --help

Install

npx battlestation capture   # or: bun x battlestation capture

Standalone macOS executables (no runtime required) are attached below: battlestation-darwin-arm64.tar.gz (Apple Silicon) and battlestation-darwin-x64.tar.gz (Intel).