One command. A ready-to-work macOS project.
mkproject is a modular Zsh scaffolder that spins up a consistent workspace:
Cursor rules, Quarto UML design docs, language init (uv / Go / Rust), optional
Keychain-backed .envrc, and a small project stamp — without hand-building the
same skeleton every time.
mkproject my-toolNew projects often need the same boring setup: editor rules, ignore files,
design notes, a venv or module, secrets wiring. mkproject orchestrates that
from small, reviewable scripts you can extend — not a black-box generator.
my-tool/
├── .cursor/ → shared Cursor rules (symlink)
├── .cursorignore
├── .dockerignore
├── .context/
│ ├── PASSPORT.md → your profile/context passport
│ ├── mkproject.toml
│ └── uml_design_platform/*.qmd
├── .envrc (optional, from macOS Keychain)
└── … language files if you chose Python / Go / Rust
git clone https://github.com/verna-stack/mkproject.git
cd mkproject
./install.shFollow the printed snippet to add the alias and fpath to ~/.zshrc, then open
a new shell.
Default location: ~/.local/bin/mkproject
Override: PREFIX=~/.local ./install.sh
Requirements: macOS + Zsh. Keychain helpers need macOS; scaffolding otherwise
needs only Zsh and the language tools you choose (uv, go, cargo, …).
mkproject my-tool # interactive
mkproject -y --lang 4 demo # empty scaffold, no prompts
mkproject -y --lang 1 --profile 1 --git app
mkproject -n experiment # dry-run
mkproject --doctor # health check
man mkproject| Option | Meaning |
|---|---|
-n, --dry-run |
Print the plan only |
-y, --yes |
Non-interactive (--lang 4, skip API profile unless set) |
--lang N |
1 Python · 2 Go · 3 Rust · 4 None |
--profile N |
1 sandbox · 2 vault Keychain services (names are configurable) |
--git |
git init |
--no-editor / --no-zed |
Do not open an editor |
--editor NAME |
Editor command (default: $MKPROJECT_EDITOR / $VISUAL / $EDITOR) |
--doctor |
Verify scripts, templates, tools, man page |
mkdir -p ~/.config/mkproject
cp config/config.example ~/.config/mkproject/config
cp template/.master_passport/PASSPORT.example.md ~/.config/mkproject/passport.md
# edit both| Variable | Purpose |
|---|---|
MKPROJECT_EDITOR |
Default editor |
MKPROJECT_PASSPORT |
Passport markdown path |
MKPROJECT_KEYCHAIN_SANDBOX / _VAULT |
Keychain service names |
MKPROJECT_CONFIG |
Config file path |
MKPROJECT_NO_EXEC |
Skip final exec zsh (tests / automation) |
Personal passports stay out of git: use ~/.config/mkproject/passport.md, or a
gitignored passport.local.md inside a private clone.
mkproject/
├── mkproject.sh # orchestrator (source this)
├── init_*.sh / setup_*.sh
├── lib/config.zsh
├── config/config.example
├── template/ # Cursor, Docker, passport example
├── man/mkproject.1
├── install.sh
├── tests/
└── packaging/homebrew/ # formula template
zsh tests/test_mkproject.zshinstall.sh— primary installer- Homebrew — tap-ready template in
packaging/homebrew/mkproject.rb
MIT — see LICENSE.
See CONTRIBUTING.md. Issues and small PRs welcome.