DEV Community

Cover image for I Was Tired of Broken Deployments, So I Built This CLI Tool
Mayur Pawar
Mayur Pawar

Posted on

I Was Tired of Broken Deployments, So I Built This CLI Tool

I Built an npm CLI Tool That Checks If Your Project Is Deployment Ready

Deployments often fail for the smallest reasons.

A missing .env file.

A forgotten build script.

A missing Dockerfile.

An incomplete Vercel configuration.

Or accidentally exposing secrets inside the project.

Most developers discover these issues only after pushing to production.

After running into these problems repeatedly while building projects, I decided to build a tool that checks deployment readiness before deployment even happens.

So I built:

πŸš€ mayur-deploy-ready

A zero-config CLI tool that analyzes your project, detects deployment issues, scans for security risks, validates platform configurations, and even auto-generates missing deployment files.


πŸ“¦ What is mayur-deploy-ready?

mayur-deploy-ready is a deployment readiness analyzer for Node.js projects.

It performs automated checks across multiple categories including:

  • package configuration
  • Docker setup
  • security validation
  • framework detection
  • platform deployment configs
  • CI/CD readiness

The goal is simple:

Catch deployment issues locally before they break production.


⚑ Installation

Global Install

npm install -g mayur-deploy-ready
Enter fullscreen mode Exit fullscreen mode

Run the Tool

mayur-deploy-ready
Enter fullscreen mode Exit fullscreen mode

🎯 Example Output

When you run the CLI:

mayur-deploy-ready
Enter fullscreen mode Exit fullscreen mode

You get a deployment analysis report like this:

━━━━━━━━━━━━━━━━━━━━━━
πŸš€ DEPLOY READY
━━━━━━━━━━━━━━━━━━━━━━

βœ” package.json found
⚠ Build script missing
⚠ Dockerfile missing
⚠ .env missing

━━━━━━━━━━━━━━━━━━━━━━
πŸ“Š Deployment Score: 75/100
━━━━━━━━━━━━━━━━━━━━━━

🟑 Needs Attention
Enter fullscreen mode Exit fullscreen mode

The tool also provides:

  • suggestions
  • categorized scoring
  • warnings
  • deployment readiness status

πŸ”₯ Features

βœ… Weighted Deployment Scoring

One of the most interesting parts of the project was designing the scoring architecture.

The tool calculates a deployment readiness score out of 100 using weighted categories like:

PACKAGE: 20/20
SCRIPTS: 10/20
SECURITY: 25/25
DOCKER: 5/10
FRAMEWORK: 0/10
Enter fullscreen mode Exit fullscreen mode

Instead of only showing warnings, this gives developers a much clearer picture of how deployment-ready their project actually is.

The scoring system categorizes projects into:

Score Status
85–100 🟒 Production Ready
60–84 🟑 Needs Attention
0–59 πŸ”΄ Unsafe Deployment

πŸ” Advanced Security Scanning

I wanted the tool to do more than just check missing files.

So I implemented recursive security scanning that detects:

  • OpenAI API keys
  • MongoDB URIs
  • JWT secrets
  • AWS access keys

Example:

⚠ Potential OpenAI API Key detected in src/test-secret.js
⚠ Potential MongoDB URI detected in config/api.js
Enter fullscreen mode Exit fullscreen mode

While building this feature, I learned that security scanning is much harder than it initially looks.

At first, the scanner even detected secrets inside the tool’s own internal files.

That forced me to redesign the scanner architecture with:

  • configurable ignore paths
  • recursive traversal
  • extension filtering
  • smarter regex matching
  • production-style exclusions

This ended up becoming one of the most educational parts of the project.


πŸ›  Auto Fix Mode

Another feature I really enjoyed building was automatic repair mode.

Run:

mayur-deploy-ready fix
Enter fullscreen mode Exit fullscreen mode

The tool can automatically generate missing deployment files such as:

  • .gitignore
  • .dockerignore
  • Dockerfile
  • .env.example
  • vercel.json
  • railway.json

This helps developers bootstrap deployment configurations much faster.


πŸ€– JSON Mode for CI/CD

I also added structured JSON output.

mayur-deploy-ready --json
Enter fullscreen mode Exit fullscreen mode

This makes the tool easy to integrate into:

  • GitHub Actions
  • Jenkins
  • GitLab CI
  • dashboards
  • automation scripts

Example:

{
  "score": 85,
  "stats": {
    "passed": 6,
    "warnings": 2,
    "errors": 0
  }
}
Enter fullscreen mode Exit fullscreen mode

βš™οΈ CI/CD Support

The tool also supports CI mode:

mayur-deploy-ready --ci
Enter fullscreen mode Exit fullscreen mode

Exit codes:

  • 0 β†’ deployment ready
  • 1 β†’ deployment unsafe

This allows deployments to fail automatically inside CI pipelines if critical deployment issues are detected.

I also added example integrations for:

  • GitHub Actions
  • GitLab CI
  • Jenkins

inside the README documentation.


🧠 What I Learned Building This

This project taught me much more than I expected.

1. CLI Development Is Different From Web Development

Building CLI tools requires thinking about:

  • terminal UX
  • output formatting
  • developer experience
  • command parsing
  • readable logs
  • automation compatibility

2. npm Publishing Has Real-World Edge Cases

While publishing the package, I ran into:

  • npm authentication issues
  • 2FA requirements
  • package publishing permissions
  • README caching
  • Shields.io badge caching
  • npm session expiration

These are things you rarely encounter while building normal frontend projects.


3. Security Tooling Requires Careful Design

The security scanner taught me an important lesson:

Naive scanning creates too many false positives.

To make the tool useful, I had to redesign the scanner with:

  • ignore systems
  • configurable exclusions
  • smarter recursion
  • safer matching logic

That experience gave me a much better understanding of developer tooling architecture.


πŸ“ Project Structure

The project is organized into:

  • checks/ β†’ validation logic
  • fixes/ β†’ auto-generated deployment fixes
  • utils/ β†’ scoring, logging, stats
  • frameworks/ β†’ framework-specific validations
  • bin/index.js β†’ CLI orchestration

The architecture became much larger than I originally planned, but it also helped me understand how production-style CLI tools are structured.


πŸš€ Open Source

The project is fully open source.

GitHub:

https://github.com/mayurCoder2004/mayur-deploy-ready
Enter fullscreen mode Exit fullscreen mode

npm:

https://www.npmjs.com/package/mayur-deploy-ready
Enter fullscreen mode Exit fullscreen mode

Final Thoughts

This started as a small utility to help me avoid deployment mistakes.

But while building it, I learned:

  • CLI architecture
  • npm publishing workflows
  • deployment tooling
  • security scanning
  • scoring systems
  • CI/CD integration
  • developer experience design

Honestly, this became one of the most educational projects I’ve built so far.

If you try it out, I’d genuinely love feedback from other developers πŸš€

Top comments (2)

Collapse
 
harjjotsinghh profile image
Harjot Singh

"Tired of broken deployments" is the best reason to build a tool - the pain is real, recurring, and specific. The deploys that break are almost never the code itself, they're the environment drift: a missing env var, a dependency that's there locally but not in CI, a migration that didn't run, a config that's right on your machine and wrong in prod. So the highest-value thing a deploy CLI can do is catch those preconditions before it ships, not just automate the push - a tool that validates "everything this deploy needs is actually present and correct" turns a 2am rollback into a pre-flight failure you see in 10 seconds.

That preflight-verify instinct is exactly what I build around - check the deploy's preconditions before acting, don't deploy and pray. It's core to Moonshift, the thing I work on - a multi-agent pipeline that takes a prompt to a deployed SaaS on your own GitHub + Vercel, where the deploy/runtime wiring is handled as verified defaults so the last mile doesn't break. Same fight you're picking with broken deploys, automated end to end. Multi-model routing keeps a build ~$3 flat, first run free no card. Nice tool. Does it validate the environment/preconditions pre-deploy (env vars, deps, migrations), or mainly orchestrate the steps? The preflight checks are where a deploy tool earns the most trust.

Collapse
 
mayur_pawar_9b0a092ca0f41 profile image
Mayur Pawar

Thankyou for your comment. My tool validates environment/preconditions before deploying