Scaffold polished, full-stack project boilerplates into any directory — straight from a friendly interactive terminal.
________ .__ __
\______ \ ____ ______ | | ____ ___.__. _____ ____ ____ | | __ ______
| | \_/ __ \\____ \| | / _ < | | / \ / _ \ / \| |/ / / ___/
| ` \ ___/| |_> > |_( <_> )___ | | Y Y ( <_> ) | \ < \___ \
/_______ /\___ > __/|____/\____// ____|____|__|_| /\____/|___| /__|_ \/____ >
\/ \/|__| \/ /_____/ \/ \/ \/ \/
DeployMonk is a zero-configuration command line scaffolder. It asks a handful of questions, then writes a complete, runnable, already-tested project into a directory of your choosing — placeholders substituted, dependencies installed, and a manifest written so you always know what generated the tree.
It is deliberately boring and predictable: one replacement engine, no telemetry, no network calls you did not ask for, and an exit code you can rely on in CI.
- Key Features
- Tech Stack
- Requirements
- Installation
- Getting Started
- Usage
- Usage Examples
- Templates
- Programmatic API
- How It Works
- Exit Codes
- Contributing
- License
- Author & Maintainer
- Interactive by default, scriptable when it matters — a friendly prompt flow
in a terminal, and a complete flag-driven mode (
--yes) for CI and automation. - Two production-shaped templates — a Node + Express service and a FastAPI + Tailwind service, both with a health endpoint and their own passing test suite.
- Deterministic placeholder substitution — a single replacement engine with a
hard guarantee that zero
{{ ... }}constructs survive generation. - Safe overwrite handling —
abort,mergeandreplacestrategies, with protection against writing into the filesystem root, your home folder, or a path that already exists as a file. - Dependency installation that reports honestly —
npmandpipare probed before use, PEP 668 systems fall back to a project-local virtual environment, and a failed install is never swallowed. - Correct exit codes everywhere —
0on success,1on any user-correctable or runtime failure. Nothing exits with a surprise code. - Graceful in CI — spinners degrade to plain lines when stdout is not a TTY,
and colour is disabled automatically under
NO_COLORorTERM=dumb. - Reproducible output — two runs on the same input produce byte-identical trees, which is what makes the result reviewable in a pull request.
- Zero-configuration templates — generated projects carry no test-runner
dependency beyond what the language ships with (
node:test/unittest).
| Layer | Choice |
|---|---|
| Runtime | Node.js >= 18, native ESM |
| Language | TypeScript (strict, NodeNext) |
| Build | tsc → dist/, declarations + source maps |
| Prompts | inquirer |
| Spinners | ora (TTY-aware, degrades to plain lines) |
| Colour | chalk (auto-disabled when not a TTY) |
| Filesystem | fs-extra |
| Tests | node:test + tsx loader, zero extra runtime |
| Lint/format | ESLint (@typescript-eslint) + Prettier |
| License | MIT |
- Node.js >= 18 and npm.
- A real terminal for the interactive flow. Otherwise pass
--name(or--yes).
Templates may need extra tooling at runtime. DeployMonk detects and reports it, and never assumes it:
| Template | Requires |
|---|---|
fastapi-tailwind |
Python 3.10+ (pip or venv), optionally Node for the Tailwind build |
node-express |
Node 18+, npm |
npm install -g deploymonkVerify the install:
deploymonk --version
deploymonk --listgit clone https://github.com/monk_mango/deploymonk.git
cd deploymonk
npm install
npm run build
npm link # exposes the `deploymonk` command globallyYou can also skip npm link entirely and invoke the launcher directly:
node bin/deploymonk.cjs --helpDeployMonk has no configuration file and no environment variables to set. Everything is either a prompt answer, a flag, or standard terminal conventions it respects automatically:
| Variable | Effect |
|---|---|
NO_COLOR |
Disables all colour output |
FORCE_COLOR=0 |
Disables all colour output |
TERM=dumb |
Disables colour and animation |
DEPLOYMONK_DEBUG |
Set to 1 to print stack traces on failure |
Run it with no arguments and answer the questions:
deploymonkYou will be asked for:
- Project name — becomes the directory name, the package name and the title.
- Template —
node-expressorfastapi-tailwind. - Target directory — defaults to
./<project-name>. - Author name (optional) — written into the generated manifest.
- Port — pre-filled with the template default.
- Overwrite strategy — only asked when the target already has files in it.
- Dependency install — run it now, or leave it to you.
DeployMonk then creates the project, resolves every placeholder, installs
dependencies, prints a summary and exits 0.
Usage
deploymonk Start the interactive scaffolder
deploymonk --list List the bundled templates
deploymonk -n my-api -t node-express -d ./out --yes
Options
-n, --name <name> Project name (letters, digits, "-", "_")
-t, --template <id> fastapi-tailwind | node-express
-d, --dir <path> Target directory (default: ./<project-name>)
-a, --author <name> Author name written into the project
-p, --port <number> Default port (1-65535)
--overwrite <mode> abort | merge | replace (default: abort)
--force Shorthand for --overwrite replace
--install <mode> always | auto | never (default: auto)
--no-install Shorthand for --install never
-y, --yes Non-interactive run (requires --name)
--dry-run Print the plan without writing anything
--list List the bundled templates
-h, --help Show this help
-v, --version Show the version
--no-color Disable coloured output
--debug Print stack traces
Exit codes
0 success
1 invalid input or a failed operation
Scaffold an Express service into ./my-api with the default port:
deploymonk -n my-api --yesPreview a FastAPI project without writing anything to disk:
deploymonk -n blog -t fastapi-tailwind -d ./blog --no-install --dry-runFully non-interactive, suitable for a CI step:
deploymonk \
--name my-api \
--template node-express \
--dir ./out \
--port 3000 \
--author "Ada Lovelace" \
--no-install \
--yesMerge into a directory that already has your own files (your files are kept):
deploymonk -n my-api --overwrite merge --yesWipe the target directory and regenerate it from scratch:
deploymonk -n my-api --force --yesSee the failure contract — every one of these exits 1:
deploymonk -n "bad name" --yes # invalid project name
deploymonk -n ok --template nope --yes # unknown template
deploymonk -n ok --port 70000 --yes # port out of range
deploymonk --totally-unknown # unknown flagRun deploymonk --list to see the registry at runtime — the CLI, the help text
and the installer all read the same source of truth, so they can never drift.
A convention-over-configuration Express service with JSON logging, a central
error handler, a health endpoint and a dependency-free node:test suite.
my-api/
├── src/
│ ├── index.js process entrypoint, graceful shutdown
│ ├── app.js Express app factory
│ ├── config/index.js environment driven configuration
│ ├── controllers/healthController.js
│ ├── middleware/
│ │ ├── errorHandler.js central JSON error handler
│ │ ├── notFound.js JSON 404
│ │ └── requestLogger.js one JSON line per request
│ ├── routes/
│ │ ├── healthRoutes.js /api/health
│ │ └── index.js root router
│ └── utils/logger.js dependency free logger
├── tests/health.test.js node:test suite
├── .env.example
├── .gitignore
└── package.json
cd my-api
npm install
npm run dev # http://127.0.0.1:3000
npm testA FastAPI service with environment-driven settings, liveness and readiness probes, and a Tailwind CSS build pipeline (optional — the landing page works without Node).
blog/
├── app/
│ ├── __init__.py
│ ├── config.py settings, DEFAULT_PORT 8000
│ ├── landing.py HTML landing page
│ ├── main.py FastAPI application
│ ├── routers/health.py /api/health, /api/health/ready
│ └── static/css/input.css Tailwind entrypoint
├── tests/test_app.py python -m unittest
├── .env.example
├── .gitignore
├── package.json Tailwind build scripts
├── requirements.txt
├── run.py convenience launcher
└── tailwind.config.js
cd blog
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python run.py # http://127.0.0.1:8000
python -m unittest discover -s tests -t .On PEP 668 managed systems (external environments that refuse pip install),
DeployMonk automatically creates a project-local .venv and installs there
instead of failing the run.
Everything the terminal can do is also exported for scripts, tests and custom front-ends. DeployMonk is ESM-only.
import { scaffoldProject, getTemplate, listTemplateIds } from 'deploymonk';
const result = await scaffoldProject({
projectName: 'Analytics Service',
templateId: 'node-express',
targetDir: './out/analytics',
authorName: 'Ada Lovelace',
defaultPort: 4242,
overwrite: 'abort',
install: 'never',
onProgress: (phase, message) => console.log(phase, message),
});
console.log(result.values.packageName); // "analytics-service"
console.log(result.fileCount);Generate files without touching the network at all:
import { generateProject } from 'deploymonk';
const { targetDir, replacementResult, values } = await generateProject({
projectName: 'Analytics Service',
templateId: 'fastapi-tailwind',
targetDir: './out/analytics',
defaultPort: 8000,
});| Export | Purpose |
|---|---|
main(argv?) |
Run the CLI in-process |
TEMPLATES, getTemplate, listTemplateIds |
The template registry |
isTemplateId, DEFAULT_TEMPLATE_ID |
Template id guards |
scaffoldProject, generateProject |
Full pipeline, and generation without installing |
resolveProjectValues, buildReplacements |
Build the placeholder value map |
slugify, toPackageName |
Naming helpers |
replaceInString, replaceInFile |
Single-value and single-file replacement |
replacePlaceholdersInTree |
Walk a tree and rewrite every eligible text file |
assertNoUnresolvedPlaceholders |
Fail loudly if any {{ ... }} survived |
findUnresolvedPlaceholders, extractTokens |
Report leftovers instead of throwing |
isTextFile, looksBinary, PLACEHOLDER_KEYS |
Classification helpers |
prepareTargetDirectory, pathExists, countFiles |
Filesystem helpers |
installDependencies |
Install for a generated project |
probeCommand, runCommand, collectSystemReport |
Environment probing |
DeployMonkError, describeCause |
Error vocabulary |
- Validate — the project name, port and directory are checked before anything is written. Bad input fails immediately, with a hint.
- Prepare — the target directory is created, or the overwrite strategy is applied.
- Copy — the template is copied through
fs-extrawith junk filtering (nonode_modules,.venv,__pycache__, caches). - Rename — dotfiles that npm strips from tarballs (
_gitignore) are restored to their real names. - Replace — one placeholder engine rewrites every text file.
- Manifest —
.deploymonk.jsonrecords the generator, version, template and resolved values. - Verify — the tree is scanned and generation fails if any
{{ ... }}construct remains. - Install — dependencies are installed for the generated project, with a clear report on failure.
| Placeholder | Example value |
|---|---|
{{PROJECT_NAME}} |
My API |
{{PACKAGE_NAME}} |
my-api (npm-safe) |
{{AUTHOR_NAME}} |
Ada Lovelace |
{{DEFAULT_PORT}} |
3000 |
{{PROJECT_SLUG}} |
my-api |
{{PROJECT_YEAR}} |
2026 |
Text files are detected by extension (.js, .ts, .json, .md, .py,
.css, .txt, .yml, .yaml, .toml, ...) plus a set of well-known file
names (Dockerfile, Makefile, _gitignore, ...) and a binary sniff. Files
larger than 2 MB and detected binaries are left untouched, and the original
line endings are preserved.
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Invalid input, or a failed runtime step |
The exit code is written exactly once per process, from a single exit point.
Contributions are welcome — issues, bug reports, template ideas and pull requests alike.
Before you open a pull request:
-
Fork the repository and create a topic branch.
-
Run the full verification suite — it is the same command CI runs:
npm install npm run verify
verifyruns typecheck → format check → lint → build → unit tests → an end-to-end smoke test that scaffolds both templates and runs the generated Node project's own test suite. -
Keep the diff focused, and match the existing style: TypeScript with
import typefor type-only imports, noany, relative imports with an explicit.jsextension, and Prettier-formatted files.
Adding a template:
- Create
src/templates/<id>/. - Register it in
TEMPLATESinsrc/core/copyTemplates.ts(label, description, stack, package manager, default port, next steps). - Ship dotfiles with an underscore prefix (
_gitignore) — npm strips real dotfiles from tarballs. - Use only the documented placeholders. Generation fails loudly if you leave an
unresolved
{{ ... }}, and templates must never contain literal double curly braces. - Add a scaffold test in
tests/scaffold.test.tsand a CLI check inscripts/smoke.mjs.
Commit messages: imperative mood, scoped where it helps — for example
feat(templates): add a Django starter.
Released under the MIT License.
MIT License
Copyright (c) 2026 ArthurJosephLawson
Developer: ArthurJosephLawson (@monk_mango)
Background: Freelance Software Engineer | Lead Developer, Founder, Scriptmonks
ArthurJosephLawson is an independent software development freelancer and the Chief Executive of Scriptmonks. DeployMonk is authored, maintained and released by him.
- GitHub: @monk_mango
- Instagram: @monk_mango
- Issues and feature requests: github.com/monk_mango/deploymonk/issues
Contributions, bug reports and template requests are all welcome.
Scaffolding full-stack projects, one monk at a time.