Workspace Tools CLI

A comprehensive command-line interface for managing Node.js workspaces and monorepos with changeset-based version management.

Overview

workspace (Workspace Tools CLI) provides:

Configuration Management: Initialize and validate workspace configurations
Changeset Workflow: Create, update, list, show, edit, and remove changesets
Version Management: Intelligent version bumping with preview mode and multiple strategies
Dependency Upgrades: Detect, apply, and rollback dependency updates
Audit System: Comprehensive health checks with actionable insights
Change Analysis: Detect affected packages from Git changes
CI/CD Integration: JSON output modes and silent operation for automation

Installation & Quick Start

For installation instructions and quick start guide, see the main README.

Documentation

This README provides complete CLI documentation based on the actual source code.

Available Commands

workspace init                        # Initialize project configuration
workspace config <subcommand>         # Manage configuration
workspace changeset <subcommand>      # Manage changesets
workspace bump [options]              # Bump package versions
workspace upgrade <subcommand>        # Manage dependency upgrades
workspace audit [options]             # Run project health audit
workspace changes [options]           # Analyze repository changes
workspace version [options]           # Display version information
workspace clone <url> [destination]   # Clone repository with workspace setup

Commands Reference

`init` - Initialize Project Configuration

Creates a new configuration file for changeset-based version management.

Usage:

workspace init [OPTIONS]

Options:

--changeset-path <PATH> - Changeset directory path (default: .changesets)
--environments <LIST> - Comma-separated list of environments (e.g., dev,staging,prod)
--default-env <LIST> - Comma-separated list of default environments
--strategy <STRATEGY> - Versioning strategy (independent or unified)
--registry <URL> - NPM registry URL (default: https://registry.npmjs.org)
--config-format <FORMAT> - Configuration file format (json, toml, or yaml)
--force - Overwrite existing configuration
--non-interactive - Use default values without prompting

Examples:

# Interactive initialization
workspace init

# Non-interactive with specific options
workspace init --non-interactive --strategy independent --config-format yaml

# Force overwrite existing config
workspace init --force --environments "dev,staging,prod"

`config` - Manage Configuration

View and validate project configuration.

`config show` - Display Current Configuration

Shows all configuration values from the detected config file.

Usage:

workspace config show

Examples:

# Show configuration (human-readable)
workspace config show

# Show configuration as JSON
workspace --format json config show

`config validate` - Validate Configuration File

Checks that the configuration file is valid and all required fields are present.

Usage:

workspace config validate

Examples:

# Validate configuration
workspace config validate

# Validate with detailed logging
workspace --log-level debug config validate

`changeset` - Manage Changesets

Create, update, list, and manage changesets for version control.

`changeset create` - Create New Changeset

Creates a changeset for the current branch.

Usage:

workspace changeset create [OPTIONS]

Options:

--bump <TYPE> - Bump type (major, minor, or patch)
--env <LIST> - Comma-separated list of environments
--branch <NAME> - Branch name (defaults to current Git branch)
--message <TEXT> - Optional description of changes
--packages <LIST> - Comma-separated list of packages (auto-detected if not provided)
--non-interactive - Use provided flags without prompting

Examples:

# Interactive creation
workspace changeset create

# Non-interactive with specific options
workspace changeset create --bump minor --env "staging,prod" --non-interactive

# Create with message
workspace changeset create --bump patch --message "Fix critical bug"

`changeset update` - Update Existing Changeset

Adds commits or packages to an existing changeset.

Usage:

workspace changeset update [ID] [OPTIONS]

Arguments:

<ID> - Changeset ID or branch name (defaults to current branch)

Options:

--commit <HASH> - Add specific commit hash
--packages <LIST> - Comma-separated list of packages to add
--bump <TYPE> - Update bump type (major, minor, or patch)
--env <LIST> - Comma-separated list of environments to add

Examples:

# Update changeset for current branch
workspace changeset update

# Update specific changeset
workspace changeset update feature/new-api --bump major

# Add specific commit
workspace changeset update --commit abc123def

`changeset list` - List All Changesets

Shows all active changesets with optional filtering and sorting.

Usage:

workspace changeset list [OPTIONS]

Options:

--filter-package <NAME> - Filter by package name
--filter-bump <TYPE> - Filter by bump type (major, minor, or patch)
--filter-env <ENV> - Filter by environment
--sort <FIELD> - Sort by field (date, bump, or branch; default: date)

Examples:

# List all changesets
workspace changeset list

# Filter by package
workspace changeset list --filter-package "@myorg/core"

# Filter and sort
workspace changeset list --filter-bump major --sort bump

`changeset show` - Show Changeset Details

Displays detailed information about a specific changeset.

Usage:

workspace changeset show <BRANCH>

Arguments:

<BRANCH> - Branch name or changeset ID

Examples:

# Show changeset for branch
workspace changeset show feature/new-api

# Show as JSON
workspace --format json changeset show feature/new-api

`changeset edit` - Edit Changeset

Opens the changeset file in your editor ($EDITOR).

Usage:

workspace changeset edit [BRANCH]

Arguments:

<BRANCH> - Branch name (defaults to current Git branch)

Examples:

# Edit changeset for current branch
workspace changeset edit

# Edit changeset for specific branch
workspace changeset edit feature/new-api

`changeset delete` - Delete Changeset

Removes a changeset from active changesets.

Usage:

workspace changeset delete <BRANCH> [OPTIONS]

Arguments:

<BRANCH> - Branch name

Options:

--force - Skip confirmation prompt

Examples:

# Delete with confirmation
workspace changeset delete feature/old-branch

# Delete without confirmation
workspace changeset delete feature/old-branch --force

`changeset history` - Query Changeset History

Searches archived changesets with filtering options.

Usage:

workspace changeset history [OPTIONS]

Options:

--package <NAME> - Filter by package name
--since <DATE> - Since date (ISO 8601, e.g., 2024-01-01)
--until <DATE> - Until date (ISO 8601)
--env <ENV> - Filter by environment
--bump <TYPE> - Filter by bump type
--limit <N> - Limit number of results

Examples:

# Show all history
workspace changeset history

# Filter by package and date range
workspace changeset history --package "@myorg/core" --since "2024-01-01"

# Limit results
workspace changeset history --limit 10

`changeset check` - Check if Changeset Exists

Checks if a changeset exists for the current or specified branch. Useful for Git hooks.

Usage:

workspace changeset check [OPTIONS]

Options:

--branch <NAME> - Branch name (defaults to current Git branch)

Examples:

# Check current branch
workspace changeset check

# Check specific branch
workspace changeset check --branch feature/new-api

`bump` - Bump Package Versions

Calculates and applies version bumps according to active changesets and the configured versioning strategy.

Usage:

workspace bump [OPTIONS]

Options:

--dry-run - Preview changes without applying (safe, default behavior)
--execute - Apply version changes (required for actual changes)
--snapshot - Generate snapshot versions
--snapshot-format <FORMAT> - Snapshot format template (variables: {version}, {branch}, {short_commit}, {commit})
--prerelease <TAG> - Pre-release tag (alpha, beta, or rc)
--packages <LIST> - Comma-separated list of packages to bump (overrides changeset packages)
--git-tag - Create Git tags for releases (format: package@version)
--git-push - Push Git tags to remote (requires --git-tag)
--git-commit - Commit version changes
--no-changelog - Skip changelog generation/updates
--no-archive - Keep changesets active after bump
--force - Skip confirmations
--show-diff - Show detailed version diffs (preview mode only)

Examples:

# Preview version bumps (safe, no changes)
workspace bump --dry-run

# Apply version bumps
workspace bump --execute

# Full release workflow
workspace bump --execute --git-commit --git-tag --git-push

# Snapshot version for testing
workspace bump --snapshot --execute

# Pre-release version
workspace bump --prerelease beta --execute

# Show detailed diffs in preview
workspace bump --dry-run --show-diff

`upgrade` - Manage Dependency Upgrades

Check for available upgrades and apply them to workspace packages.

`upgrade check` - Check for Available Upgrades

Detects outdated dependencies in workspace packages.

Usage:

workspace upgrade check [OPTIONS]

Options:

--major / --no-major - Include/exclude major version upgrades (default: include)
--minor / --no-minor - Include/exclude minor version upgrades (default: include)
--patch / --no-patch - Include/exclude patch version upgrades (default: include)
--dev - Include dev dependencies (default: true)
--peer - Include peer dependencies (default: false)
--packages <LIST> - Comma-separated list of packages to check
--registry <URL> - Override registry URL

Examples:

# Check all upgrades
workspace upgrade check

# Check only non-breaking upgrades
workspace upgrade check --no-major

# Check specific packages
workspace upgrade check --packages "@myorg/core,@myorg/utils"

# Include peer dependencies
workspace upgrade check --peer

`upgrade apply` - Apply Dependency Upgrades

Updates dependencies to newer versions.

Usage:

workspace upgrade apply [OPTIONS]

Options:

--dry-run - Preview without applying
--patch-only - Only apply patch upgrades
--minor-and-patch - Only apply minor and patch upgrades (non-breaking)
--packages <LIST> - Comma-separated list of packages to upgrade
--auto-changeset - Automatically create changeset for upgrades
--changeset-bump <TYPE> - Changeset bump type (major, minor, or patch; default: patch)
--no-backup - Skip backup creation
--force - Skip confirmations

Examples:

# Preview upgrades
workspace upgrade apply --dry-run

# Apply safe upgrades with automatic changeset
workspace upgrade apply --minor-and-patch --auto-changeset

# Apply patch upgrades only
workspace upgrade apply --patch-only --force

# Apply upgrades for specific packages
workspace upgrade apply --packages "@myorg/core"

`upgrade backups` - Manage Upgrade Backups

List, restore, or clean upgrade backups.

upgrade backups list - List all backups:

workspace upgrade backups list

upgrade backups restore - Restore a backup:

workspace upgrade backups restore <ID> [OPTIONS]

Options:

--force - Skip confirmation prompt

Example:

workspace upgrade backups restore backup_20240115_103045

upgrade backups clean - Clean old backups:

workspace upgrade backups clean [OPTIONS]

Options:

--keep <N> - Number of recent backups to keep (default: 5)
--force - Skip confirmation prompt

Example:

workspace upgrade backups clean --keep 3 --force

`audit` - Run Project Health Audit

Analyzes project health including upgrades, dependencies, version consistency, and breaking changes.

Usage:

workspace audit [OPTIONS]

Options:

--sections <LIST> - Comma-separated list of sections to audit (default: all)
- Options: all, upgrades, dependencies, version-consistency, breaking-changes
--output <PATH> - Write output to file
--min-severity <LEVEL> - Minimum severity level (default: info)
- Options: critical, high, medium, low, info
--verbosity <LEVEL> - Detail level (default: normal)
- Options: minimal, normal, detailed
--no-health-score - Skip health score calculation
--export <FORMAT> - Export format (html or markdown; requires --export-file)
--export-file <PATH> - File path for exported report (requires --export)

Examples:

# Full audit
workspace audit

# Specific sections
workspace audit --sections upgrades,dependencies

# High severity issues only
workspace audit --min-severity high

# Export to markdown
workspace audit --export markdown --export-file audit-report.md

# JSON output for CI/CD
workspace --format json audit

`changes` - Analyze Repository Changes

Detects which packages are affected by changes in the working directory or between commits.

Usage:

workspace changes [OPTIONS]

Options:

--since <REF> - Since commit/branch/tag (analyzes changes since this Git reference)
--until <REF> - Until commit/branch/tag (default: HEAD)
--branch <NAME> - Compare against branch
--staged - Only staged changes (cannot be used with --unstaged)
--unstaged - Only unstaged changes (cannot be used with --staged)
--packages <LIST> - Comma-separated list of packages to filter

Examples:

# Analyze working directory changes
workspace changes

# Changes since specific commit
workspace changes --since HEAD~5

# Changes between commits
workspace changes --since v1.0.0 --until v1.1.0

# Only staged changes
workspace changes --staged

# Compare against branch
workspace changes --branch main

# Filter specific packages
workspace changes --packages "@myorg/core"

`version` - Display Version Information

Shows the CLI version and optionally detailed build information.

Usage:

workspace version [OPTIONS]

Options:

--verbose - Show detailed version information (includes Rust version, dependencies, and build info)

Examples:

# Show version
workspace version

# Show detailed information
workspace version --verbose

`clone` - Clone Repository with Workspace Setup

Clones a Git repository and automatically initializes or validates workspace configuration for immediate development.

Usage:

workspace clone <URL> [DESTINATION] [OPTIONS]

Arguments:

<URL> - Repository URL to clone from (HTTPS or SSH)
[DESTINATION] - Optional destination path (defaults to repository name)

Options:

Clone Options:

--force - Overwrite destination if it exists
--depth <N> - Create shallow clone with specified depth
--skip-validation - Skip configuration validation (even if config exists)
--non-interactive - Skip interactive prompts

Init Options (used if no config found):

--changeset-path <PATH> - Changeset directory path (default: .changesets)
--environments <LIST> - Comma-separated list of environments
--default-env <LIST> - Comma-separated list of default environments
--strategy <STRATEGY> - Versioning strategy (independent or unified)
--registry <URL> - NPM registry URL (default: https://registry.npmjs.org)
--config-format <FORMAT> - Config file format (json, toml, or yaml)

Behavior:

The clone command follows this workflow:

Clone repository - Downloads the repository with progress indication
Detect configuration - Searches for existing workspace configuration
Path A: Configuration exists
- Validates configuration file structure
- Checks required directories exist (.changesets/, .changesets/history/, .workspace-backups/)
- Verifies .gitignore entries
- Reports validation results
Path B: No configuration
- Automatically runs init command
- Creates workspace configuration
- Sets up directory structure
- Updates .gitignore

Examples:

# Clone to default location (repository name)
workspace clone https://github.com/org/repo.git

# Clone to specific directory
workspace clone https://github.com/org/repo.git ./my-project

# Clone with SSH
workspace clone git@github.com:org/repo.git

# Clone and force overwrite existing directory
workspace clone https://github.com/org/repo.git --force

# Shallow clone (faster, less disk space)
workspace clone https://github.com/org/repo.git --depth 1

# Clone with init configuration (non-interactive)
workspace clone https://github.com/org/repo.git \
  --non-interactive \
  --strategy independent \
  --environments "dev,staging,prod" \
  --default-env "prod"

# Clone and skip validation
workspace clone https://github.com/org/repo.git --skip-validation

# Clone for CI/CD with JSON output
workspace --format json clone https://github.com/org/repo.git ./workspace

Error Scenarios:

The clone command handles various error scenarios with helpful messages:

# Network/DNS failure
workspace clone https://github.com/org/invalid.git
# Error: Network error: Could not resolve host for URL
# Suggestions:
#   - Check your internet connection
#   - Verify the repository URL is correct

# Authentication failure (SSH)
workspace clone git@github.com:private/repo.git
# Error: Authentication error: Failed to authenticate
# Suggestions:
#   - Ensure your SSH key is added to your SSH agent
#   - Verify your SSH key is registered with GitHub
#   - Try: ssh -T git@github.com to test connection

# Authentication failure (HTTPS)
workspace clone https://github.com/private/repo.git
# Error: Authentication error: Failed to authenticate
# Suggestions:
#   - Verify you have access to this repository
#   - Ensure authentication is configured
#   - Check if your access token is valid

# Destination exists (without --force)
workspace clone https://github.com/org/repo.git ./existing-dir
# Error: Destination already exists: ./existing-dir
# Use --force to overwrite

# Repository not found
workspace clone https://github.com/org/nonexistent.git
# Error: Repository not found
# Suggestions:
#   - Verify the repository URL is correct
#   - Check if the repository exists
#   - Ensure you have access if repository is private

# Disk space error
workspace clone https://github.com/large/repository.git
# Error: Insufficient disk space to clone repository
# Suggestions:
#   - Free up disk space
#   - Choose a different destination with more space
#   - Consider using --depth 1 for a shallow clone

# Validation failure (existing config)
workspace clone https://github.com/org/broken-config.git
# Clone succeeds
# Validation detects:
#   ✗ Changeset directory
#     Error: Directory '.changesets' does not exist
#     Suggestion: Run 'workspace init --force' to create directory
#   ✗ .gitignore entries
#     Error: Missing .gitignore entries for workspace directories
#     Suggestion: Run 'workspace init --force' to update .gitignore

Integration Examples:

CI/CD Pipeline (GitHub Actions):

name: Setup Development Environment

on:
  workflow_dispatch:
    inputs:
      repository:
        description: 'Repository to clone'
        required: true
      branch:
        description: 'Branch to checkout'
        default: 'main'

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - name: Clone and setup workspace
        run: |
          workspace clone ${{ github.event.inputs.repository }} \
            --non-interactive \
            --strategy independent \
            --config-format yaml

      - name: Checkout specific branch
        working-directory: ./repo-name
        run: git checkout ${{ github.event.inputs.branch }}

      - name: Verify setup
        working-directory: ./repo-name
        run: workspace config validate

Developer Onboarding Script:

#!/bin/bash
# onboard.sh - Quick setup for new developers

REPO_URL="https://github.com/myorg/monorepo.git"
DEST_DIR="$HOME/projects/monorepo"

echo "Setting up development environment..."

# Clone with workspace setup
workspace clone "$REPO_URL" "$DEST_DIR" \
  --non-interactive \
  --strategy independent \
  --environments "dev,staging,production" \
  --default-env "production" \
  --config-format toml

cd "$DEST_DIR" || exit 1

# Verify setup
echo "Verifying workspace configuration..."
workspace config validate

echo "Setup complete! You can now:"
echo "  cd $DEST_DIR"
echo "  workspace changeset create"
echo "  workspace bump --dry-run"

Automated Testing Environment:

#!/bin/bash
# test-setup.sh - Create isolated test environment

TEST_DIR=$(mktemp -d)
REPO="https://github.com/org/repo.git"

# Clone with shallow depth for faster setup
workspace clone "$REPO" "$TEST_DIR/workspace" \
  --depth 1 \
  --non-interactive \
  --skip-validation \
  --force

cd "$TEST_DIR/workspace" || exit 1

# Run tests
npm install
npm test

# Cleanup
rm -rf "$TEST_DIR"

Mirror Repository Setup:

#!/bin/bash
# mirror.sh - Setup repository mirror

SOURCE="https://github.com/upstream/original.git"
MIRROR_DIR="/var/repos/mirror"

# Clone original repository
workspace clone "$SOURCE" "$MIRROR_DIR" \
  --force \
  --config-format json

cd "$MIRROR_DIR" || exit 1

# Add mirror remote
git remote add mirror https://git.mycompany.com/mirror.git

# Validate workspace setup
workspace config validate && echo "Mirror setup complete"

Global Options

All commands support these global options that control behavior across the entire application:

Options:

-r, --root <PATH> - Project root directory (default: current directory)
- Changes working directory before executing the command
- All file operations will be relative to this path
-l, --log-level <LEVEL> - Logging level (default: info)
- Controls verbosity of operation logs written to stderr
- Does NOT affect command output (stdout)
- Levels: silent, error, warn, info, debug, trace
-f, --format <FORMAT> - Output format (default: human)
- Controls format of command output written to stdout
- Does NOT affect logging (stderr)
- Formats: human, json, json-compact, quiet
--no-color - Disable colored output
- Removes ANSI color codes from both logs (stderr) and output (stdout)
- Also respects the NO_COLOR environment variable
- Useful for CI/CD environments and file redirection
-c, --config <PATH> - Path to config file
- Override default config file location
- Path can be relative or absolute
- Default: Auto-detect (.changesets.{toml,json,yaml,yml})

Stream Separation:

The CLI maintains strict separation between:

stderr: Logs only (controlled by --log-level)
stdout: Command output only (controlled by --format)

This ensures JSON output is never contaminated with logs, enabling reliable piping and parsing in scripts.

Examples:

# Clean JSON output with no logs (perfect for automation)
workspace --format json --log-level silent bump --dry-run

# JSON output with debug logs (logs to stderr, JSON to stdout)
workspace --format json --log-level debug bump --dry-run > output.json 2> debug.log

# Change working directory
workspace --root /path/to/project changeset list

# Use custom config file
workspace --config custom-config.toml config show

Configuration

The CLI uses a configuration file (repo.config.toml, repo.config.json, or repo.config.yaml) to control all aspects of workspace management. This file is typically created by running workspace init.

Configuration File Location

The CLI automatically detects configuration files in this order:

Path specified via --config flag
repo.config.toml in project root
repo.config.yaml or repo.config.yml in project root
repo.config.json in project root

Configuration Structure

The configuration is organized into logical sections under the [package_tools] namespace:

[package_tools.changeset]
# Changeset storage and management

[package_tools.version]
# Versioning strategy

[package_tools.dependency]
# Dependency propagation

[package_tools.upgrade]
# Dependency upgrade detection

[package_tools.changelog]
# Changelog generation

[package_tools.git]
# Git integration

[package_tools.audit]
# Health checks and audits

[package_tools.workspace]
# Monorepo workspace patterns (optional)

Complete Example Configuration

[package_tools.changeset]
path = ".changesets"
history_path = ".changesets/history"
available_environments = ["development", "staging", "production"]
default_environments = ["production"]

[package_tools.version]
strategy = "independent"  # or "unified"
default_bump = "patch"
snapshot_format = "{version}-{branch}.{timestamp}"

[package_tools.dependency]
propagation_bump = "patch"
propagate_dependencies = true
propagate_dev_dependencies = false
propagate_peer_dependencies = true
max_depth = 10
fail_on_circular = true
skip_workspace_protocol = true
skip_file_protocol = true
skip_link_protocol = true
skip_portal_protocol = true

[package_tools.upgrade]
auto_changeset = true
changeset_bump = "patch"

[package_tools.upgrade.registry]
default_registry = "https://registry.npmjs.org"
scoped_registries = {}
auth_tokens = {}
timeout_secs = 30
retry_attempts = 3
retry_delay_ms = 1000
read_npmrc = true

[package_tools.upgrade.backup]
enabled = true
backup_dir = ".workspace-backups"
keep_after_success = false
max_backups = 5

[package_tools.changelog]
enabled = true
format = "keep-a-changelog"  # or "conventional" or "custom"
filename = "CHANGELOG.md"
include_commit_links = true
include_issue_links = true
include_authors = false
repository_url = "https://github.com/your-org/your-repo"
monorepo_mode = "per-package"  # or "root" or "both"
version_tag_format = "{name}@{version}"
root_tag_format = "v{version}"

[package_tools.changelog.conventional]
enabled = true
breaking_section = "Breaking Changes"

[package_tools.changelog.conventional.types]
feat = "Features"
fix = "Bug Fixes"
perf = "Performance Improvements"
refactor = "Code Refactoring"
docs = "Documentation"
build = "Build System"
ci = "Continuous Integration"
test = "Tests"
chore = "Chores"

[package_tools.changelog.exclude]
patterns = []
authors = []

[package_tools.changelog.template]
header = "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n"
version_header = "## [{version}] - {date}"
section_header = "### {section}"
entry_format = "- {description} ({hash})"

[package_tools.git]
merge_commit_template = "chore(release): {version}\n\nRelease version {version}\n\n{changelog_summary}"
monorepo_merge_commit_template = "chore(release): {package_name}@{version}\n\nRelease {package_name} version {version}\n\n{changelog_summary}"
include_breaking_warning = true
breaking_warning_template = "\n⚠️  BREAKING CHANGES: {breaking_changes_count}\n"

[package_tools.audit]
enabled = true
min_severity = "warning"  # "critical", "warning", or "info"

[package_tools.audit.sections]
upgrades = true
dependencies = true
breaking_changes = true
categorization = true
version_consistency = true

[package_tools.audit.upgrades]
include_patch = true
include_minor = true
include_major = true
deprecated_as_critical = true

[package_tools.audit.dependencies]
check_circular = true
check_missing = false
check_unused = false
check_version_conflicts = true

[package_tools.audit.breaking_changes]
check_conventional_commits = true
check_changelog = true

[package_tools.audit.version_consistency]
fail_on_inconsistency = false
warn_on_inconsistency = true

[package_tools.audit.health_score_weights]
critical_weight = 15.0
warning_weight = 5.0
info_weight = 1.0
security_multiplier = 1.5
breaking_changes_multiplier = 1.3
dependencies_multiplier = 1.2
version_consistency_multiplier = 1.0
upgrades_multiplier = 0.8
other_multiplier = 1.0

# Optional: Only for monorepo projects with workspace patterns
[package_tools.workspace]
patterns = ["packages/*", "apps/*"]

Configuration Reference

`[package_tools.changeset]` - Changeset Management

Controls where changesets are stored and what environments are available.

Field	Type	Default	Description
`path`	String	`".changesets"`	Directory for active changesets
`history_path`	String	`".changesets/history"`	Directory for archived changesets
`available_environments`	Array	`["production"]`	Valid environment names for deployment targeting
`default_environments`	Array	`["production"]`	Environments used when none are specified

Example:

[package_tools.changeset]
path = ".changesets"
history_path = ".changesets/history"
available_environments = ["dev", "staging", "prod"]
default_environments = ["prod"]

`[package_tools.version]` - Versioning Strategy

Defines how package versions are calculated and applied.

Field	Type	Default	Description
`strategy`	String	`"independent"`	Versioning strategy: `"independent"` (each package has own version) or `"unified"` (all packages share same version)
`default_bump`	String	`"patch"`	Default version bump when not specified in changeset: `"major"`, `"minor"`, `"patch"`, or `"none"`
`snapshot_format`	String	`"{version}-{branch}.{timestamp}"`	Format template for snapshot versions. Placeholders: `{version}`, `{branch}`, `{timestamp}`, `{short_hash}`

Example:

[package_tools.version]
strategy = "unified"
default_bump = "minor"
snapshot_format = "{version}-snapshot.{short_hash}"

`[package_tools.dependency]` - Dependency Propagation

Controls how version changes propagate through the dependency graph.

Field	Type	Default	Description
`propagation_bump`	String	`"patch"`	Version bump type for propagated updates: `"major"`, `"minor"`, `"patch"`, or `"none"`
`propagate_dependencies`	Boolean	`true`	Propagate version updates to regular dependencies
`propagate_dev_dependencies`	Boolean	`false`	Propagate version updates to devDependencies
`propagate_peer_dependencies`	Boolean	`true`	Propagate version updates to peerDependencies
`max_depth`	Integer	`10`	Maximum depth for dependency propagation (0 = unlimited)
`fail_on_circular`	Boolean	`true`	Fail when circular dependencies are detected
`skip_workspace_protocol`	Boolean	`true`	Skip dependencies using workspace protocol (`workspace:*`)
`skip_file_protocol`	Boolean	`true`	Skip dependencies using file protocol (`file:../path`)
`skip_link_protocol`	Boolean	`true`	Skip dependencies using link protocol (`link:../path`)
`skip_portal_protocol`	Boolean	`true`	Skip dependencies using portal protocol (`portal:../path`)

Example:

[package_tools.dependency]
propagation_bump = "minor"
propagate_dependencies = true
propagate_dev_dependencies = true
max_depth = 5
fail_on_circular = false

`[package_tools.upgrade]` - Dependency Upgrades

Settings for detecting and applying external dependency upgrades.

Field	Type	Default	Description
`auto_changeset`	Boolean	`true`	Automatically create changeset for upgrades
`changeset_bump`	String	`"patch"`	Version bump type for automatic changeset: `"major"`, `"minor"`, `"patch"`, or `"none"`

Example:

[package_tools.upgrade]
auto_changeset = true
changeset_bump = "patch"

`[package_tools.upgrade.registry]` - Registry Configuration

NPM registry communication settings.

Field	Type	Default	Description
`default_registry`	String	`"https://registry.npmjs.org"`	Default NPM registry URL
`scoped_registries`	Map	`{}`	Scoped registry mappings (scope → URL, without `@` prefix)
`auth_tokens`	Map	`{}`	Authentication tokens (registry URL → token)
`timeout_secs`	Integer	`30`	HTTP request timeout in seconds
`retry_attempts`	Integer	`3`	Number of retry attempts for failed requests
`retry_delay_ms`	Integer	`1000`	Delay between retry attempts in milliseconds
`read_npmrc`	Boolean	`true`	Read configuration from `.npmrc` files (workspace root + user home directory). Workspace `.npmrc` takes precedence over user `~/.npmrc`

.npmrc File Support:

When read_npmrc is enabled, the system automatically reads NPM registry configuration from:

User home directory: ~/.npmrc (lower precedence)
Workspace root: .npmrc (higher precedence, overrides user settings)

The .npmrc file format supports:

Registry URLs: registry=https://registry.npmjs.org
Scoped registries: @myorg:registry=https://npm.myorg.com
Authentication tokens: //npm.myorg.com/:_authToken=npm_AbCdEf123456
Environment variables: //npm.myorg.com/:_authToken=${NPM_TOKEN}
Comments: Lines starting with # or inline comments

Example .npmrc:

# Default registry
registry=https://registry.npmjs.org

# Scoped registry for @myorg packages
@myorg:registry=https://npm.myorg.com

# Authentication token using environment variable
//npm.myorg.com/:_authToken=${NPM_TOKEN}

Example repo.config.toml:

[package_tools.upgrade.registry]
default_registry = "https://registry.npmjs.org"
timeout_secs = 60
retry_attempts = 5
read_npmrc = true  # Reads from ~/.npmrc and workspace .npmrc

[package_tools.upgrade.registry.scoped_registries]
myorg = "https://npm.myorg.com"  # Note: scope without @ prefix

[package_tools.upgrade.registry.auth_tokens]
"npm.myorg.com" = "npm_token_here"  # Can also use "https://npm.myorg.com"

Precedence Order (highest to lowest):

auth_tokens and scoped_registries in repo.config.toml
Workspace .npmrc (project root)
User ~/.npmrc (home directory)

`[package_tools.upgrade.backup]` - Backup Configuration

Backup and rollback settings for upgrade operations.

Field	Type	Default	Description
`enabled`	Boolean	`true`	Enable automatic backups before upgrades
`backup_dir`	String	`".workspace-backups"`	Directory where backups are stored
`keep_after_success`	Boolean	`false`	Keep backups after successful operations
`max_backups`	Integer	`5`	Maximum number of backups to retain

Example:

[package_tools.upgrade.backup]
enabled = true
backup_dir = ".backups"
keep_after_success = true
max_backups = 10

`[package_tools.changelog]` - Changelog Generation

Controls how changelogs are generated and formatted.

Field	Type	Default	Description
`enabled`	Boolean	`true`	Enable changelog generation
`format`	String	`"keep-a-changelog"`	Changelog format: `"keep-a-changelog"`, `"conventional"`, or `"custom"`
`filename`	String	`"CHANGELOG.md"`	Changelog filename
`include_commit_links`	Boolean	`true`	Include links to commits
`include_issue_links`	Boolean	`true`	Include links to issues (e.g., #123)
`include_authors`	Boolean	`false`	Include author attribution
`repository_url`	String	`None`	Repository URL for generating links (auto-detected from git remote if not set)
`monorepo_mode`	String	`"per-package"`	Changelog location: `"per-package"`, `"root"`, or `"both"`
`version_tag_format`	String	`"{name}@{version}"`	Format for version tags in monorepo. Placeholders: `{name}`, `{version}`
`root_tag_format`	String	`"v{version}"`	Format for root version tags. Placeholder: `{version}`

Example:

[package_tools.changelog]
enabled = true
format = "conventional"
include_authors = true
repository_url = "https://github.com/myorg/myrepo"
monorepo_mode = "both"

`[package_tools.changelog.conventional]` - Conventional Commits

Conventional commits parsing configuration.

Field	Type	Default	Description
`enabled`	Boolean	`true`	Enable conventional commits parsing
`breaking_section`	String	`"Breaking Changes"`	Title for breaking changes section
`types`	Map	See below	Map of commit types to display titles

Default Types:

[package_tools.changelog.conventional.types]
feat = "Features"
fix = "Bug Fixes"
perf = "Performance Improvements"
refactor = "Code Refactoring"
docs = "Documentation"
build = "Build System"
ci = "Continuous Integration"
test = "Tests"
chore = "Chores"

`[package_tools.changelog.exclude]` - Exclusion Rules

Defines which commits to exclude from changelogs.

Field	Type	Default	Description
`patterns`	Array	`[]`	Regex patterns for commit messages to exclude
`authors`	Array	`[]`	Authors whose commits should be excluded

Example:

[package_tools.changelog.exclude]
patterns = ["^chore\\(release\\):", "^Merge branch"]
authors = ["dependabot[bot]"]

`[package_tools.changelog.template]` - Custom Templates

Templates for changelog generation.

Field	Type	Default	Description
`header`	String	See default	Template for changelog header
`version_header`	String	`"## [{version}] - {date}"`	Template for version headers. Placeholders: `{version}`, `{date}`
`section_header`	String	`"### {section}"`	Template for section headers. Placeholder: `{section}`
`entry_format`	String	`"- {description} ({hash})"`	Template for individual entries. Placeholders: `{description}`, `{hash}`

`[package_tools.git]` - Git Integration

Git commit message templates and breaking change warnings.

Field	Type	Default	Description
`merge_commit_template`	String	See default	Template for single-package release commits
`monorepo_merge_commit_template`	String	See default	Template for monorepo release commits
`include_breaking_warning`	Boolean	`true`	Include breaking change warnings in merge commits
`breaking_warning_template`	String	`"\n⚠️ BREAKING CHANGES: {breaking_changes_count}\n"`	Template for breaking change warnings

Available Placeholders:

{version} - New version being released
{previous_version} - Previous version
{package_name} - Package name
{bump_type} - Version bump type (Major, Minor, Patch, None)
{date} - Release date (YYYY-MM-DD)
{breaking_changes_count} - Number of breaking changes
{features_count} - Number of new features
{fixes_count} - Number of bug fixes
{changelog_summary} - Brief summary from changelog
{author} - Current git user

Default Templates:

[package_tools.git]
merge_commit_template = """chore(release): {version}

Release version {version}

{changelog_summary}"""

monorepo_merge_commit_template = """chore(release): {package_name}@{version}

Release {package_name} version {version}

{changelog_summary}"""

`[package_tools.audit]` - Audit Configuration

Settings for project health checks and audits.

Field	Type	Default	Description
`enabled`	Boolean	`true`	Enable audit system
`min_severity`	String	`"warning"`	Minimum severity level for reporting: `"critical"`, `"warning"`, or `"info"`

`[package_tools.audit.sections]` - Audit Sections

Controls which audit sections to execute.

Field	Type	Default	Description
`upgrades`	Boolean	`true`	Run upgrade availability audits
`dependencies`	Boolean	`true`	Run dependency health audits
`breaking_changes`	Boolean	`true`	Check for breaking changes
`categorization`	Boolean	`true`	Categorize dependencies
`version_consistency`	Boolean	`true`	Check version consistency

`[package_tools.audit.upgrades]` - Upgrade Audit

Controls which upgrade types to include in audits.

Field	Type	Default	Description
`include_patch`	Boolean	`true`	Include patch version upgrades
`include_minor`	Boolean	`true`	Include minor version upgrades
`include_major`	Boolean	`true`	Include major version upgrades
`deprecated_as_critical`	Boolean	`true`	Treat deprecated packages as critical issues

`[package_tools.audit.dependencies]` - Dependency Audit

Controls which dependency checks to perform.

Field	Type	Default	Description
`check_circular`	Boolean	`true`	Detect circular dependencies
`check_missing`	Boolean	`false`	Check for missing dependencies
`check_unused`	Boolean	`false`	Check for unused dependencies
`check_version_conflicts`	Boolean	`true`	Check for version conflicts

`[package_tools.audit.breaking_changes]` - Breaking Changes Audit

Controls how breaking changes are detected.

Field	Type	Default	Description
`check_conventional_commits`	Boolean	`true`	Check for breaking changes in conventional commits
`check_changelog`	Boolean	`true`	Check for breaking changes in changelogs

`[package_tools.audit.version_consistency]` - Version Consistency

Controls how version inconsistencies are handled.

Field	Type	Default	Description
`fail_on_inconsistency`	Boolean	`false`	Fail when version inconsistencies are detected
`warn_on_inconsistency`	Boolean	`true`	Warn when version inconsistencies are detected

`[package_tools.audit.health_score_weights]` - Health Score Weights

Controls how issues affect the overall health score calculation.

Field	Type	Default	Description
`critical_weight`	Float	`15.0`	Points deducted per critical issue
`warning_weight`	Float	`5.0`	Points deducted per warning issue
`info_weight`	Float	`1.0`	Points deducted per info issue
`security_multiplier`	Float	`1.5`	Multiplier for security issues
`breaking_changes_multiplier`	Float	`1.3`	Multiplier for breaking changes issues
`dependencies_multiplier`	Float	`1.2`	Multiplier for dependency issues
`version_consistency_multiplier`	Float	`1.0`	Multiplier for version consistency issues
`upgrades_multiplier`	Float	`0.8`	Multiplier for upgrade issues
`other_multiplier`	Float	`1.0`	Multiplier for other issues

Example:

[package_tools.audit.health_score_weights]
critical_weight = 20.0
warning_weight = 10.0
security_multiplier = 2.0
breaking_changes_multiplier = 1.5

`[package_tools.workspace]` - Workspace Configuration (Optional)

Project-specific workspace patterns for monorepo projects. This section is optional and only used for monorepo projects.

Field	Type	Default	Description
`patterns`	Array	`[]`	Workspace patterns from package.json (e.g., `["packages/", "apps/"]`)

Example:

[package_tools.workspace]
patterns = ["packages/*", "apps/*", "libs/*"]

Note: This represents the actual workspace patterns declared in your project's package.json. For single-package projects, this section is omitted entirely.

Configuration Management

View Configuration

# Show current configuration
workspace config show

# Show as JSON
workspace --format json config show

Validate Configuration

# Validate configuration file
workspace config validate

# Validate with detailed logging
workspace --log-level debug config validate

Initialize Configuration

# Interactive initialization
workspace init

# Non-interactive with defaults
workspace init --non-interactive

# Specify options
workspace init --strategy unified --config-format yaml

Architecture

Error Handling

The CLI uses a unified CliError enum that wraps all error types:

Configuration: Config file errors
Validation: Argument/state validation errors
Execution: Command execution failures
Git: Git operation errors
Package: Package/package.json errors
Io: File system errors
Network: Network/registry errors
User: User-caused errors (invalid input, cancelled operations)

Each error maps to appropriate exit codes following sysexits conventions and includes user-friendly messages with actionable suggestions.

Output System

The CLI separates logging from output:

Logging (--log-level): Controls stderr output for debugging

Levels: silent, error, warn, info, debug, trace
Always goes to stderr
Independent from output format

Output (--format): Controls stdout for command results

Formats: human, json, json-compact, quiet
Always goes to stdout
Independent from logging

This separation ensures JSON output is never mixed with logs, perfect for CI/CD pipelines.

Contributing

This is an active development project. Please follow the established patterns:

Check STORY_MAP.md for planned work
Follow the implementation guidelines in PLAN.md
Read the PRD.md for feature requirements
Ensure 100% Clippy compliance
Document all public APIs with examples
Write comprehensive tests
Use conventional commits for automatic releases

See ../../CONTRIBUTING.md for detailed contribution guidelines.

License

This project is licensed under the MIT License - see the ../../LICENSE-MIT file for details.

sublime_cli_tools 0.0.14

Workspace Tools CLI

Overview

Installation & Quick Start

Documentation

Available Commands

Commands Reference

init - Initialize Project Configuration

config - Manage Configuration

config show - Display Current Configuration

config validate - Validate Configuration File

changeset - Manage Changesets

changeset create - Create New Changeset

changeset update - Update Existing Changeset

changeset list - List All Changesets

changeset show - Show Changeset Details

changeset edit - Edit Changeset

changeset delete - Delete Changeset

changeset history - Query Changeset History

changeset check - Check if Changeset Exists

bump - Bump Package Versions

upgrade - Manage Dependency Upgrades

upgrade check - Check for Available Upgrades

upgrade apply - Apply Dependency Upgrades

upgrade backups - Manage Upgrade Backups

audit - Run Project Health Audit

changes - Analyze Repository Changes

version - Display Version Information

clone - Clone Repository with Workspace Setup

Global Options

Configuration

Configuration File Location

Configuration Structure

Complete Example Configuration

Configuration Reference

[package_tools.changeset] - Changeset Management

[package_tools.version] - Versioning Strategy

[package_tools.dependency] - Dependency Propagation

[package_tools.upgrade] - Dependency Upgrades

[package_tools.upgrade.registry] - Registry Configuration

[package_tools.upgrade.backup] - Backup Configuration

[package_tools.changelog] - Changelog Generation

[package_tools.changelog.conventional] - Conventional Commits

[package_tools.changelog.exclude] - Exclusion Rules

[package_tools.changelog.template] - Custom Templates

[package_tools.git] - Git Integration

[package_tools.audit] - Audit Configuration

[package_tools.audit.sections] - Audit Sections

[package_tools.audit.upgrades] - Upgrade Audit

[package_tools.audit.dependencies] - Dependency Audit

[package_tools.audit.breaking_changes] - Breaking Changes Audit

[package_tools.audit.version_consistency] - Version Consistency

[package_tools.audit.health_score_weights] - Health Score Weights

[package_tools.workspace] - Workspace Configuration (Optional)

Configuration Management

View Configuration

Validate Configuration

Initialize Configuration

Architecture

Error Handling

Output System

Contributing

License

Links

Planning Documents (Historical)

`init` - Initialize Project Configuration

`config` - Manage Configuration

`config show` - Display Current Configuration

`config validate` - Validate Configuration File

`changeset` - Manage Changesets

`changeset create` - Create New Changeset

`changeset update` - Update Existing Changeset

`changeset list` - List All Changesets

`changeset show` - Show Changeset Details

`changeset edit` - Edit Changeset

`changeset delete` - Delete Changeset

`changeset history` - Query Changeset History

`changeset check` - Check if Changeset Exists

`bump` - Bump Package Versions

`upgrade` - Manage Dependency Upgrades

`upgrade check` - Check for Available Upgrades

`upgrade apply` - Apply Dependency Upgrades

`upgrade backups` - Manage Upgrade Backups

`audit` - Run Project Health Audit

`changes` - Analyze Repository Changes

`version` - Display Version Information

`clone` - Clone Repository with Workspace Setup

`[package_tools.changeset]` - Changeset Management

`[package_tools.version]` - Versioning Strategy

`[package_tools.dependency]` - Dependency Propagation

`[package_tools.upgrade]` - Dependency Upgrades

`[package_tools.upgrade.registry]` - Registry Configuration

`[package_tools.upgrade.backup]` - Backup Configuration

`[package_tools.changelog]` - Changelog Generation

`[package_tools.changelog.conventional]` - Conventional Commits

`[package_tools.changelog.exclude]` - Exclusion Rules

`[package_tools.changelog.template]` - Custom Templates

`[package_tools.git]` - Git Integration

`[package_tools.audit]` - Audit Configuration

`[package_tools.audit.sections]` - Audit Sections

`[package_tools.audit.upgrades]` - Upgrade Audit

`[package_tools.audit.dependencies]` - Dependency Audit

`[package_tools.audit.breaking_changes]` - Breaking Changes Audit

`[package_tools.audit.version_consistency]` - Version Consistency

`[package_tools.audit.health_score_weights]` - Health Score Weights

`[package_tools.workspace]` - Workspace Configuration (Optional)