cli-dev

cli-dev is an internal TypeScript CLI for routine developer and CI workflows across company repositories.

It is designed to:

• standardize pull request, branching, release, validation, and environment checks
• run the same way for local developers and Jenkins jobs
• execute from compiled JavaScript in dist/, not directly from TypeScript

Requirements

• Node.js 18+
• Git
• GitHub CLI (gh) for PR-related commands
• Linux or macOS shell environment

Installation

Install dependencies and build the compiled output:

npm install
npm run build

The package bin points to compiled output:

"bin": {
  "cli-dev": "./dist/index.js"
}

Run it locally after build:

node dist/index.js --help

For package publishing, prepack rebuilds dist/ automatically so the published tarball contains compiled JavaScript only.

Package Publishing

The package is configured for internal registry distribution:

• only dist/ and README.md are published
• the CLI binary resolves to compiled output in dist/index.js
• source files, tests, local config, and staging notes are not included in the package tarball
• publishConfig.access=restricted keeps the package aligned with private distribution flows

Typical publish flow:

npm publish

Typical install flow from an internal registry:

npm install -g cli-dev
cli-dev --help

Local Development With npm link

To use the CLI globally from your workstation during development:

npm install
npm run build
npm link

After linking, run:

cli-dev --help
cli-dev doctor

When you change TypeScript source, rebuild before using the linked CLI:

npm run build

Configuration

cli-dev looks for .cli-dev.json in the current directory and then walks upward until it finds one. If no file exists, built-in defaults are used.

Minimal repository example:

{
  "baseBranch": "main",
  "defaultPrDraft": true,
  "ticketPattern": "[A-Z]{2,}-\\d+",
  "allowedBranchPrefixes": ["feature", "fix", "chore", "release", "hotfix"],
  "releaseTagPrefix": "v",
  "git": {
    "user": {
      "name": "John Doe",
      "email": "[email protected]",
      "scope": "local"
    }
  },
  "scan": {
    "commands": {
      "lint": "npm run lint",
      "test": "npm test",
      "build": "npm run build"
    }
  }
}

This repository includes that sample as /mnt/T7/projects/under_tree_e/addons/ute-cli.npm/.cli-dev.json. Commands fall back to built-in defaults for fields not present in the file, so the minimal example is enough for branch, pr, release, scan, and doctor.

Commands

pr

Create or inspect pull requests.

Examples:

cli-dev pr --summary "Add API timeout handling"
cli-dev pr --summary "Add API timeout handling" --push
cli-dev pr
cli-dev pr create --summary "Release 1.2.0" --base main --head release/1.2.0 --draft
cli-dev pr status

Notes:

• cli-dev pr is the smart create entrypoint. If the required inputs are already provided, it creates the PR directly. If not, local interactive mode asks only the minimal follow-up questions.
• cli-dev pr create runs the same create flow explicitly.
• In local interactive mode, cli-dev can prompt for missing summary text, draft mode, base branch when no default is configured, and whether to push the branch when required.
• In CI, with --non-interactive, or in any non-interactive terminal, prompts are disabled. Pass --summary or both --title and --body, plus any other required flags such as --base.
• cli-dev pr never pushes implicitly. If the branch is missing on origin or is ahead of origin, push it yourself first or pass --push.
• If a PR already exists for the current branch, cli-dev prints the existing PR and exits successfully instead of creating a duplicate.
• gh must be installed and authenticated.

branch

Generate a standardized branch name, with optional checkout.

Examples:

cli-dev branch AX-142 improve timeout handling
cli-dev branch AX-142 improve timeout handling --type fix --checkout
cli-dev branch AX-142 prepare release branch --type release --checkout --base main

git setup

Configure git user.name and git user.email with an explicit local or global scope.

Examples:

cli-dev git setup
cli-dev git setup --name "John Doe" --email "[email protected]"
cli-dev git setup --global --name "John Doe" --email "[email protected]"
cli-dev git setup --from-config

Notes:

• local scope is the default and is recommended for repository-specific setup
• global scope is only used when --global is passed, or when --from-config reads "scope": "global"
• cli-dev git setup never changes git identity silently; interactive mode confirms before applying changes
• --from-config reads git.user.name, git.user.email, and git.user.scope from .cli-dev.json
• CI and other non-interactive environments must pass --name and --email, or use --from-config

release

Create and push an annotated git tag from the current commit.

Examples:

cli-dev release --version 1.2.0
cli-dev release --version 1.2.0 --rc 1
cli-dev release --version 1.2.0 --dry-run

Notes:

• the git working tree must be clean
• the tag must not already exist locally or on origin

scan

Run repository validation commands defined in .cli-dev.json.

Examples:

cli-dev scan --lint
cli-dev scan --test --build
cli-dev scan --all

Notes:

• scan only runs commands that are configured under scan.commands
• missing task configuration causes a fast failure

doctor

Check whether the local or CI environment is ready to use cli-dev.

Examples:

cli-dev doctor
cli-dev doctor --scope git
cli-dev doctor --scope github --strict
cli-dev doctor --format json
cli-dev doctor --json

doctor checks items such as:

• core: required runtime basics such as node, git, and config readability
• git: repository state such as git worktree presence, branch safety, origin, and whether git identity is configured
• github: gh availability and authentication
• scan: scan command presence and optional tooling such as sonar-scanner and docker
• ci: CI detection and prompt policy

By default, doctor runs a broad health check across all scopes but only fails the command for enforced scopes. Local default enforcement is intentionally narrow so advisory issues in git, github, scan, or ci still show up without making the command unusable outside those contexts.

Use --scope to focus on one or more capability areas and make those checks blocking:

cli-dev doctor --scope git
cli-dev doctor --scope git --scope github
cli-dev doctor --scope git,github

Use --strict when doctor should act as an enforcement gate, such as in CI:

cli-dev doctor --strict

Local Developer Examples

Create a branch and open a PR:

cli-dev branch AX-142 improve timeout handling --checkout
git push -u origin "$(git branch --show-current)"
cli-dev pr --summary "Improve timeout handling"

Validate a repository before pushing:

cli-dev doctor
cli-dev scan --all

Create a release tag:

cli-dev release --version 1.2.0 --dry-run
cli-dev release --version 1.2.0

Jenkins Examples

Assume cli-dev is already installed and available on PATH in the Jenkins build environment.

cli-dev doctor

pipeline {
  agent any

  stages {
    stage('Doctor') {
      steps {
        sh 'cli-dev doctor --strict'
      }
    }
  }
}

cli-dev scan --all

pipeline {
  agent any

  stages {
    stage('Scan') {
      steps {
        sh 'cli-dev scan --all'
      }
    }
  }
}

cli-dev release --version 1.2.0 --dry-run

pipeline {
  agent any

  stages {
    stage('Release Dry Run') {
      steps {
        sh 'cli-dev release --version 1.2.0 --dry-run'
      }
    }
  }
}

CI behavior:

• prompts are disabled when CI=true or JENKINS_URL is set
• commands return non-zero exit codes on failure
• use explicit flags for anything that would otherwise require input

Typical Setup Flow

For a new developer, the shortest path is:

npm install
npm run build
npm link
cli-dev doctor

If the repository needs custom scan tasks or PR defaults, add .cli-dev.json before using scan or automated PR flows.