vshot

The tiny release CLI for Node.js.

Version + build metadata + Git release in one command.

npm install -g vshot

vshot p "fix auth bug"

1.2.3 → 1.2.4

✓ package.json
✓ build metadata
✓ git commit
✓ git tag
✓ git push
✓ changelog

Installation

Global

npm install -g vshot

vshot p "fix login bug"

Local

npm install -D vshot

{
  "scripts": {
    "v": "vshot"
  }
}

npm run v p "fix login bug"
pnpm v  p "fix login bug"
yarn v  p "fix login bug"

Why vshot?

If npm version is too basic and release-it is too much, vshot gives you a tiny release workflow with build metadata. No config file, no plugins, no dependencies.

• Zero dependencies — just Node.js and Git
• Build metadata — buildNumber, buildEpoch, gitHash, and gitCommitEpoch injected into package.json
• Git workflow — commit, tag, and push in one command
• Changelog — auto-prepend release entries to CHANGELOG.md
• Dry run — preview every step before writing
• Interactive mode — prompts when run without arguments

vshot vs alternatives

| Feature | vshot | npm version | bumpp | release-it | | ----------------- | ----: | ----------: | ----: | ---------: | | Semver bump | ✓ | ✓ | ✓ | ✓ | | Build metadata | ✓ | — | — | — | | Git commit | ✓ | ✓ | ✓ | ✓ | | Tag | ✓ | ✓ | ✓ | ✓ | | Push | ✓ | — | ✓ | ✓ | | Changelog | ✓ | — | — | ✓ | | Zero dependencies | ✓ | — | ✓? | — | | Tiny CLI | ✓ | — | — | — |

Usage

vshot <type> "<message>" [flags]

Version Types

| Type | Bump | Example | | ---- | ----- | ----------------- | | p | Patch | 1.2.3 → 1.2.4 | | mi | Minor | 1.2.3 → 1.3.0 | | ma | Major | 1.2.3 → 2.0.0 |

Flags

| Flag | Description | | --------------- | ----------------------------------------- | | --tag | Create an annotated Git tag (vX.Y.Z) | | --push | Push commit and tag to origin | | --no-commit | Skip all Git operations | | --changelog | Prepend a release entry to CHANGELOG.md | | --dry-run | Preview everything without writing | | -v, --version | Print vshot version | | -h, --help | Show help screen |

Interactive Mode

If you run vshot without a type argument, it enters interactive mode and prompts you:

vshot

  No type given — interactive mode

  Bump type (ma/mi/p) → p
  Commit message → fix null pointer in auth

What It Does

1. Bumps the Version

Reads package.json, applies the semver bump, and writes it back.

2. Injects Build Metadata

Adds or updates buildInfo in package.json:

{
  "buildInfo": {
    "buildNumber": "260831.1420",
    "buildEpoch": "1787429400",
    "gitHash": "b1d887f",
    "gitCommitEpoch": "1787429000"
  }
}

| Field | Description | | ---------------- | ---------------------------------------- | | buildNumber | Build date and time in YYMMDD.HHmm UTC | | buildEpoch | Build timestamp as Unix time | | gitHash | Short hash of the current HEAD | | gitCommitEpoch | Timestamp of the current HEAD commit |

3. Commits

Stages and commits changes automatically.

| Scenario | Behavior | | -------------------- | ---------------------------------------------- | | Nothing staged | Stages everything and commits | | Files already staged | Commits only the staged files + package.json | | --changelog active | Also stages CHANGELOG.md | | --no-commit | Writes files only — no Git operations |

4. Tags

--tag creates an annotated Git tag:

vshot mi "add dark mode" --tag

Annotated tag  v1.3.0

If the tag already exists, it is skipped with a warning instead of failing.

5. Push

--push pushes the branch and (if --tag is set) the tag to origin:

vshot mi "add dark mode" --tag --push

Requires a remote named origin. vshot validates this during pre-flight checks and exits early if it is missing.

6. Changelog

--changelog prepends a release entry to CHANGELOG.md (created if it does not exist):

vshot mi "add dark mode" --changelog

## [1.3.0] - 2026-08-31

### Minor

- Add dark mode

New entries are always inserted above existing entries, preserving history.

7. Dry Run

--dry-run runs the entire pipeline and prints every step without writing anything to disk or Git:

vshot ma "rewrite core" --tag --push --changelog --dry-run

  DRY RUN — nothing will be written

  [1/6] Pre-flight checks
     ✓ package.json  v1.2.3
     ✓ Git  main @ b1d887f

  [2/6] Computing version bump
     build:  major  1.2.3 → 2.0.0

  [3/6] Writing package.json  [dry-run]
     ✓ version   1.2.3 → 2.0.0

  [4/6] Updating CHANGELOG.md  [dry-run]
     ✓ [2.0.0] entry prepended  2026-08-31

  [5/6] Committing changes  [dry-run]
     ✓ Would commit: "2.0.0: Rewrite core"

  [6/6] Creating annotated tag  [dry-run]
     ✓ Would create annotated tag v2.0.0

Pre-flight Checks

Before writing anything, vshot validates:

• package.json exists and contains a valid semver version
• Git is available and reports the current branch and hash
• The working tree state (dirty/clean) is displayed
• A remote named origin exists when --push is used

npm Lifecycle Hooks

If package.json defines preversion or postversion scripts, vshot runs them automatically at the appropriate points (skipped in --dry-run mode).

Examples

vshot p  "fix auth null pointer"
vshot mi "add dark mode" --tag --push
vshot ma "rewrite core" --tag --push --changelog
vshot p  "test change" --dry-run
vshot mi "bump deps" --no-commit

Git Fallback

If Git is not available, gitHash and gitCommitEpoch fall back to safe defaults:

{
  "gitHash": "no-git",
  "gitCommitEpoch": "0"
}

The version bump and buildInfo are still written. Git operations (--tag, --push, commit) are silently disabled.

Requirements

• Node.js >= 18
• Git for commit, tag, and push operations

License

MIT