ute-cli

ute-cli 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": {
  "ute-cli": "./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 ute-cli
ute-cli --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:

ute-cli --help
ute-cli doctor

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

npm run build

Configuration

ute-cli looks for .ute-cli.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/.ute-cli.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:

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

Notes:

• ute-cli 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.
• ute-cli pr create runs the same create flow explicitly.
• In local interactive mode, ute-cli 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.
• ute-cli 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, ute-cli 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:

ute-cli branch AX-142 improve timeout handling
ute-cli branch AX-142 improve timeout handling --type fix --checkout
ute-cli 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:

ute-cli git setup
ute-cli git setup --name "John Doe" --email "[email protected]"
ute-cli git setup --global --name "John Doe" --email "[email protected]"
ute-cli 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"
• ute-cli 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 .ute-cli.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:

ute-cli release --version 1.2.0
ute-cli release --version 1.2.0 --rc 1
ute-cli 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 .ute-cli.json.

Examples:

ute-cli scan --lint
ute-cli scan --test --build
ute-cli 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 ute-cli.

Examples:

ute-cli doctor
ute-cli doctor --scope git
ute-cli doctor --scope github --strict
ute-cli doctor --format json
ute-cli 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:

ute-cli doctor --scope git
ute-cli doctor --scope git --scope github
ute-cli doctor --scope git,github

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

ute-cli doctor --strict

Local Developer Examples

Create a branch and open a PR:

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

Validate a repository before pushing:

ute-cli doctor
ute-cli scan --all

Create a release tag:

ute-cli release --version 1.2.0 --dry-run
ute-cli release --version 1.2.0

Jenkins Examples

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

ute-cli doctor

pipeline {
  agent any

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

ute-cli scan --all

pipeline {
  agent any

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

ute-cli release --version 1.2.0 --dry-run

pipeline {
  agent any

  stages {
    stage('Release Dry Run') {
      steps {
        sh 'ute-cli 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
ute-cli doctor

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