dotty

module

v0.2.6 Latest Latest Go to latest Published: Jul 22, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/bitwise-media-group/dotty

Links

Open Source Insights

README ¶

dotty

Utilities for a terminal-driven workflow and dotfiles: system profiles that travel across machines, reproducible Homebrew Brewfiles, named aliases for hardware security keys, and SSH signing keys that live on YubiKeys — including git commit signing.

Every command follows dotty <noun> <verb>:

dotty profile new --name=work        # create a profile (and offer to activate it)
dotty profile activate               # fuzzy-pick and activate a profile
dotty brewfile add --cask ghostty    # add to the Brewfile and install
dotty brewfile sync                  # make the machine match the Brewfile
dotty security-key add --name=work   # alias a YubiKey serial
dotty signing-key new                # enroll a resident SSH signing key

The generated command reference lives in docs/cli.

Install

brew install bitwise-media-group/tap/dotty

or with the Go toolchain:

go install github.com/bitwise-media-group/dotty/cmd@latest

or download an archive from the releases page. External tools dotty drives: brew (with brew bundle), ykman, fido2-token (libfido2), and ssh-keygen (OpenSSH 8.2+ with FIDO support).

Where things live

dotty splits its state for privacy:

$XDG_CONFIG_HOME/dotty (~/.config/dotty) — profiles and the active-profile symlink. Shareable configuration, safe for a public dotfiles repository.
$XDG_DATA_HOME/dotty (~/.local/share/dotty) — security-key aliases and signing-key stubs, created 0700/0600. PII-adjacent; manage it from a private repository if you sync it at all. The stubs are FIDO2 key handles, not private keys — the secrets never leave the hardware, and resident keys can be re-downloaded with ssh-keygen -K.

Git commit signing

Enroll a key, then print the ready-to-paste configuration:

dotty signing-key new
dotty signing-key sign --print-git-config

That configures gpg.format=ssh, points gpg.ssh.program at dotty, and uses dotty signing-key get --format=key as gpg.ssh.defaultKeyCommand. Signing a commit then costs one PIN entry — the key was enrolled verify-required + no-touch-required, and ssh-keygen locates the right YubiKey from the key handle automatically.

Static alternative (no dotty on the signing path): set user.signingKey to the stub path printed by dotty signing-key get.

Development

make pr    # the full local gate: tidy fmt lint test build commit

Go developer CLIs are pinned by the shared Makefile library (the make/ submodule's .<tool>-version files) and installed on demand into .bin/; Node tooling is pinned in package.json. CI, security analysis, and releases run through the org's reusable GitHub Actions workflows (bitwise-media-group/github-workflows). Releases are driven by release-please: merging its release PR cuts the vX.Y.Z tag and draft release, then GoReleaser publishes signed archives, checksums, SBOMs, and the Homebrew cask.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd Command dotty provides common utilities for operating a terminal-driven workflow and dotfiles: machine profiles, Brewfile management, hardware security-key aliases, and SSH signing keys on YubiKeys.	Command dotty provides common utilities for operating a terminal-driven workflow and dotfiles: machine profiles, Brewfile management, hardware security-key aliases, and SSH signing keys on YubiKeys.
internal
brewfile Package brewfile drives `brew bundle` and `brew trust` to keep a profile's Brewfile — and the machine — reproducible.	Package brewfile drives `brew bundle` and `brew trust` to keep a profile's Brewfile — and the machine — reproducible.
cli Package cli provides the cross-area plumbing every dotty command builds on: IO streams, an exec runner for the external tools dotty orchestrates (brew, ykman, fido2-token, ssh-keygen), XDG path resolution with dotty's public-config / private-data split, $EDITOR round-trips, and argv helpers for proxy commands.	Package cli provides the cross-area plumbing every dotty command builds on: IO streams, an exec runner for the external tools dotty orchestrates (brew, ykman, fido2-token, ssh-keygen), XDG path resolution with dotty's public-config / private-data split, $EDITOR round-trips, and argv helpers for proxy commands.
env Package env stores generic credentials in the operating system keychain and injects them into templates and processes, the way the 1Password CLI does but with no external service.	Package env stores generic credentials in the operating system keychain and injects them into templates and processes, the way the 1Password CLI does but with no external service.
fonts Package fonts installs the fonts dotty's terminal output leans on — currently the lobe-icons glyph font that supplies the AI-brand icons in tmux window names.	Package fonts installs the fonts dotty's terminal output leans on — currently the lobe-icons glyph font that supplies the AI-brand icons in tmux window names.
git Package git drives git from dotty: commit re-signing and signature-preserving stacked branches for fork workflows.	Package git drives git from dotty: commit re-signing and signature-preserving stacked branches for fork workflows.
linker Package linker symlinks a dotfiles repository's trees into their live targets: whole files and directories are linked folded, existing real directories are descended into and their children linked individually, and stale symlinks are replaced in place.	Package linker symlinks a dotfiles repository's trees into their live targets: whole files and directories are linked folded, existing real directories are descended into and their children linked individually, and stale symlinks are replaced in place.
macos Package macos applies macOS system preferences: curated groups of `defaults write` settings, the desktop wallpaper, and PIV smart-card enforcement.	Package macos applies macOS system preferences: curated groups of `defaults write` settings, the desktop wallpaper, and PIV smart-card enforcement.
profile Package profile manages dotty's system profiles: per-machine configuration sets (Brewfile, and later prompt/terminal themes) that live under $XDG_CONFIG_HOME/dotty/<name> and travel across machines via a public dotfiles repository.	Package profile manages dotty's system profiles: per-machine configuration sets (Brewfile, and later prompt/terminal themes) that live under $XDG_CONFIG_HOME/dotty/<name> and travel across machines via a public dotfiles repository.
scaffold Package scaffold renders the dotfiles template embedded in the dotty binary into a net-new dotfiles repository.	Package scaffold renders the dotfiles template embedded in the dotty binary into a net-new dotfiles repository.
securitykey Package securitykey manages hardware security keys: named aliases for YubiKey serial numbers (kept in a private JSON store under $XDG_DATA_HOME/dotty/security-key) and the device discovery and selection flows shared by the security-key and signing-key commands.	Package securitykey manages hardware security keys: named aliases for YubiKey serial numbers (kept in a private JSON store under $XDG_DATA_HOME/dotty/security-key) and the device discovery and selection flows shared by the security-key and signing-key commands.
signingkey Package signingkey creates and uses SSH signing keys that live as resident FIDO2 credentials on hardware security keys.	Package signingkey creates and uses SSH signing keys that live as resident FIDO2 credentials on hardware security keys.
tmux Package tmux drives tmux for agent-centric development: dev sessions laid out with an editor, a shell, and a window per installed coding agent, and a per-window @agent_status indicator that agent lifecycle hooks set and the tmux theme renders.	Package tmux drives tmux for agent-centric development: dev sessions laid out with an editor, a shell, and a window per installed coding agent, and a per-window @agent_status indicator that agent lifecycle hooks set and the tmux theme renders.
tui Package tui provides dotty's interactive surface: a shared huh theme, prompt helpers (confirm, input, fuzzy select) that refuse to run without a terminal, styled notice printers, and the custom bubbletea models the security-key and signing-key commands use.	Package tui provides dotty's interactive surface: a shared huh theme, prompt helpers (confirm, input, fuzzy select) that refuse to run without a terminal, styled notice printers, and the custom bubbletea models the security-key and signing-key commands use.
version Package version exposes build metadata stamped into the binary at link time.	Package version exposes build metadata stamped into the binary at link time.
wizard Package wizard collects the dotty init answers: the profile, the repository paths, and the what-goes-on-this-machine-class selections.	Package wizard collects the dotty init answers: the profile, the repository paths, and the what-goes-on-this-machine-class selections.
worktree Package worktree holds the pure logic of the agent-worktree lifecycle — root resolution, name sanitization, identifier derivation, and hook-JSON parsing — with no I/O, so it is exhaustively unit-testable.	Package worktree holds the pure logic of the agent-worktree lifecycle — root resolution, name sanitization, identifier derivation, and hook-JSON parsing — with no I/O, so it is exhaustively unit-testable.