https://github.com/kitsunekode/loom-cli
Preview-first dotfiles workflow CLI built on top of chezmoi.
https://github.com/kitsunekode/loom-cli
bun chezmoi cli config-management developer-tools dotfiles linux typescript
Last synced: 3 months ago
JSON representation
Preview-first dotfiles workflow CLI built on top of chezmoi.
- Host: GitHub
- URL: https://github.com/kitsunekode/loom-cli
- Owner: KitsuneKode
- License: mit
- Created: 2026-03-30T17:11:45.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-30T19:02:50.000Z (3 months ago)
- Last Synced: 2026-03-30T19:19:58.855Z (3 months ago)
- Topics: bun, chezmoi, cli, config-management, developer-tools, dotfiles, linux, typescript
- Language: TypeScript
- Homepage: https://github.com/KitsuneKode/loom-cli#readme
- Size: 38.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# loom
`loom` is a preview-first dotfiles workflow CLI built on top of `chezmoi`.
It keeps one repo as the source of truth, lets you keep editing live files, and
helps you discover, inspect, track, ignore, sync back, and apply changes with
explicit control.
[](https://github.com/KitsuneKode/loom-cli/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@kitsunekode/loom)
The npm package name is `@kitsunekode/loom`. The installed executable stays `loom`.
## Why it exists
`chezmoi` is excellent at rendering one source repo onto scattered files in
`$HOME`, but its raw commands are still a bit low-level for day-to-day
"what changed and what should I do with it?" flows.
`loom` adds that missing layer:
- preview-first workflows instead of surprise mutation
- human-readable discovery of managed, unmanaged, ignored, and template-backed files
- stable `--json` output for agents and automation
- `.loomignore` files that can live at the repo root or near noisy subtrees
- no extra tracking database beyond your Git repo and `chezmoi`
## Design goals
- keep `chezmoi` as the engine
- keep `git` as the review and history layer
- default every mutation to preview-first
- avoid partial local file corruption by validating before mutation and using
atomic local file writes where `loom` edits files itself
- keep startup fast and dependencies minimal
## Install locally
```bash
bun install
bun run build
./bin/loom doctor
```
Optional global link:
```bash
bun run link:global
```
## Versioning with Changesets
`loom` uses [Changesets](https://github.com/changesets/changesets) for
release intent and version bumps.
Normal flow:
```bash
bun run changeset
git add .changeset
git commit -m "feat: ..."
```
When you're ready to cut a release version:
```bash
bun run version-packages
git add package.json bun.lock .changeset
git commit -m "chore: version packages"
```
## Publish to npm
The repo is ready for npm-style packaging:
- `package.json` exposes `bin/loom`
- `files` keeps the published package minimal
- `prepack` builds `dist/loom.js`
Before publishing:
```bash
bun run changeset:status
bun run check
npm pack --dry-run --ignore-scripts
bun run release:dry-run
```
The automated publish flow lives in `/.github/workflows/release.yml`.
It is configured for npm trusted publishing with GitHub OIDC, not `NPM_TOKEN`.
Before the first real publish, configure a trusted publisher on npm for:
- GitHub user or org: `KitsuneKode`
- Repository: `loom-cli`
- Workflow filename: `release.yml`
See `docs/releasing.md` for the full release checklist.
Important:
- pending changesets block the automated publish workflow
- trusted publishing requires a GitHub-hosted runner and a matching npm trusted
publisher configuration
- once versions are cut and no changesets are pending, the `main` branch release
workflow can publish the new npm version
## Quick start
Initialize a repo-local config in a dotfiles repo:
```bash
loom init --write
```
Inspect what changed:
```bash
loom status
loom diff ~/.config/zsh ~/.config/hypr
loom discover ~/.config/hypr
```
Sync live edits back into the repo:
```bash
loom pull ~/.config/zsh ~/.config/hypr
loom pull --write ~/.config/zsh ~/.config/hypr
```
Track a new config file:
```bash
loom track ~/.config/zed/settings.json
loom track --write ~/.config/zed/settings.json
```
Add a subtree-local ignore file:
```bash
loom ignore add --scope ~/.config/hypr 'shaders/.compiled.cache.glsl'
loom ignore add --scope ~/.config/hypr --write 'shaders/.compiled.cache.glsl'
```
## Core model
- `git`: review, commit, push, branch, revert
- `chezmoi`: source/destination mapping, add, re-add, apply, templates, encryption
- `loom`: discovery, inspection, ignore ergonomics, preview-first mutation
## Commands
- `loom init [--write]`
- `loom doctor [--json]`
- `loom config show [--json]`
- `loom status [paths...] [--json]`
- `loom diff [paths...]`
- `loom discover [paths...] [--json]`
- `loom inspect [--json]`
- `loom pull [paths...] [--write] [--json]`
- `loom apply [paths...] [--write] [--json]`
- `loom track [--template|--encrypt|--exact|--follow|--interactive] [--write]`
- `loom ignore add --scope [--write]`
- `loom ignore list [--json]`
- `loom source `
- `loom managed [--json]`
- `loom unmanage [--write]`
See `docs/architecture.md`, `docs/config-reference.md`, and `docs/workflow.md`
for the full model.