dot is a generative project scaffolding tool. Answer a few questions — dot generates a production-ready project.
- Interactive TUI survey → production-ready project on disk
- Works for TypeScript apps, monorepos, microservices, Go backends, and more
- Extensible: publish generators and plugins for any language or pattern
brew install version14/tap/dotcurl -fsSL https://raw.githubusercontent.com/version14/dot/main/install.sh | shInstalls to /usr/local/bin/dot by default. Override with INSTALL_DIR=~/bin sh install.sh.
go install github.com/version14/dot/cmd/dot@latestRequires Go 1.26+. Binary lands in $GOPATH/bin.
git clone https://github.com/version14/dot.git
cd dot
make build # → bin/dot
./bin/dot versiondot self-update# Homebrew
brew uninstall dot
# curl / go install / from source
curl -fsSL https://raw.githubusercontent.com/version14/dot/main/uninstall.sh | shProject .dot/ directories are left untouched — remove them manually if needed.
dot scaffold [flow-id] [-out DIR] # Run an interactive scaffold flow
dot update [PATH] # Re-run generators against an existing project
dot self-update # Update dot to the latest release
dot doctor [PATH] # Diagnose drift between spec and installed tools
dot plugin <list|install|uninstall> # Manage installable plugins
dot flows # List available flows
dot generators # List registered generators
dot gen-bump --all [--bump patch|minor|major] # Bump all generator manifest versions
dot gen-bump --name NAME [--bump patch|minor|major | --set VERSION] # Bump single generator version
dot version # Print version
dot help # Show helpQuick start:
dot scaffold # pick a flow interactively
dot scaffold init # use a specific flow by ID
dot scaffold frontend -out ~/projectsAfter scaffolding, a .dot/ directory is written alongside the project. It stores the full spec (spec.json) and generator manifest (manifest.json) so dot update and dot doctor can work later.
See docs/user/getting-started.md for the full walkthrough. See docs/README.md for the complete documentation index.
| Flow ID | What it builds |
|---|---|
init |
Project wizard — TypeScript app, optional monorepo, Express backend, auth, database, tooling |
frontend |
Frontend project — framework, router, UI library, styling, state, testing, modules |
plugin-template |
A publishable dot plugin repository |
The init flow offers a decorator-based API option for Express backends:
class decorators (@Controller, @Get, @Body, @Response, @Auth),
request/response validation via Zod, and an OpenAPI v3 spec served at
/docs. See docs/user/decorators.md.
Run dot flows to see the up-to-date list with descriptions.
make help # See all available targets
make build # Compile → bin/dot
make dev # Build and run
make validate # fmt → vet → lint → test (run before every PR)
make test # Unit tests with race detector
make test-flows # End-to-end fixture tests (requires pnpm)
make fmt # Format code
make lint # Lint with golangci-lint
make clean # Remove build artifacts
make hooks # Activate git hooks (commit message validation)Or raw Go commands:
go build -o bin/dot ./cmd/dot
go test ./...
golangci-lint run ./...First time setting up? See docs/contributor/getting-started.md — includes a one-command setup script for macOS, Linux, and Windows.
dot uses a flow → spec → generator pipeline architecture.
dot scaffold
└── TUI survey (flow graph)
└── Spec (typed answers)
└── Generator resolver (topological sort)
└── VirtualProjectState (in-memory file tree)
└── Persist → project on disk + .dot/
Package layout:
dot/
├── cmd/dot/ ← main() — thin entry point, imports plugins
├── flows/ ← built-in flow definitions + registry
├── generators/ ← built-in generator packages (one per generator)
├── plugins/ ← in-tree plugins (biome_extras, ...)
├── examples/ ← reference plugin implementations
├── tools/
│ ├── test-flow/ ← end-to-end test runner + fixtures
│ └── dep-checker/ ← generator dependency version analyzer and updater
│
├── internal/
│ ├── cli/ ← command dispatch, Scaffold(), TUI form runner, spinner
│ ├── flow/ ← question DSL, FlowEngine, HookRegistry, FragmentRegistry
│ ├── spec/ ← ProjectSpec, builder, loader
│ ├── generator/ ← registry, executor, resolver, topological sorter, validator
│ ├── state/ ← VirtualProjectState, Persist, JSON/YAML/GoMod helpers
│ ├── commands/ ← post-gen + test command planner and runner
│ ├── dotdir/ ← .dot/ read/write (spec.json, manifest.json)
│ ├── plugin/ ← provider interface, loader, installer
│ ├── render/ ← template rendering (local files, remote GitHub URLs), TAR handling
│ ├── fileutils/ ← path utilities, safe write operations, file tree walking
│ ├── git/ ← git integration utilities
│ └── versioning/ ← semver parser and constraint checker
│
└── pkg/
├── dotapi/ ← public Generator interface, Manifest, Context (stable API)
└── dotplugin/ ← public plugin author API — re-exports from internal
See docs/contributor/architecture.md for a deep-dive into each subsystem.
| Workflow | Trigger | Purpose |
|---|---|---|
| CI | Push / PR | Vet, lint, test, build |
| Commitlint | Push / PR | Validate commit messages |
| Release | v*.*.* tag |
Build multi-platform binaries, create GitHub Release |
| Dep-checker | PR, weekly (Wed 09:00 UTC), manual | Scan generator dependencies for outdated packages |
| Dependency review | PR to main | GitHub dependency vulnerability scanning |
Local checks before pushing:
make validate # fmt → vet → lint → test
make test-flows # end-to-end fixture tests
make hooks # activate git hooks for commit validationContributions are welcome. Read CONTRIBUTING.md before opening a PR.
Key steps:
- Set up your environment:
bash scripts/setup-dev.sh(orscripts/setup-dev.ps1on Windows) - Make changes and write tests
- Run
make validate && make test-flows - Commit with Conventional Commits format
- Open a PR
For contributor orientation (where to look, what to read, how the pipeline works), see docs/contributor/navigation-guide.md.
Distributed under the MIT License.