Crate sublime_cli_tools

Expand description

§Workspace Tools CLI

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

§Supported Platforms

macOS (Apple Silicon and Intel)
Linux (x64 glibc, x64 musl, ARM64 glibc)
Windows (x64)

§What

This crate provides the workspace CLI tool that offers:

Configuration management (init, config)
Changeset workflow (changeset add, list, show, etc.)
Version bumping (bump)
Dependency upgrades (upgrade)
Audit and health checks (audit)
Change analysis (changes)

§How

The CLI is built using:

clap for argument parsing and command dispatch
tokio for async runtime
Internal crates (sublime-package-tools, sublime-standard-tools, sublime-git-tools)
Multiple output formats (human-readable, JSON, compact JSON)
Comprehensive error handling with user-friendly messages

§Why

This CLI provides a unified interface for managing complex Node.js workspaces, supporting both single-package repositories and monorepos with multiple versioning strategies. It follows a changeset-based workflow for better change tracking and version management.

§Examples

use sublime_cli_tools;

// The CLI is primarily used as a binary, but the library exports
// command execution functions for testing and integration purposes.

§Architecture

The crate is organized into the following modules:

cli: CLI definition, argument parsing, and command dispatch
commands: Command implementations
error: Error types and user-friendly error messages
output: Output formatting (human, JSON, tables, progress bars)
interactive: Interactive prompts and user input (future)
utils: Shared utilities (future)

§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

§Quick Install (Recommended)

macOS/Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/websublime/workspace-tools/releases/latest/download/sublime_cli_tools-installer.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://github.com/websublime/workspace-tools/releases/latest/download/sublime_cli_tools-installer.ps1 | iex"

§Alternative Installation Methods

From crates.io:

cargo install sublime_cli_tools

From source:

git clone https://github.com/websublime/workspace-tools.git
cd workspace-tools
cargo install --path crates/cli

For more details, 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 status                      # Display workspace status information
workspace execute [options]           # Execute commands across packages
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
--force - Overwrite existing changeset if one exists for the branch

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"

# Overwrite existing changeset
workspace changeset create --bump major --force

§`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:

--filter-package <NAME> - Filter by package name
--since <DATE> - Since date (ISO 8601, e.g., 2024-01-01)
--until <DATE> - Until date (ISO 8601)
--filter-env <ENV> - Filter by environment
--filter-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 --filter-package "@myorg/core" --since "2024-01-01"

# Filter by environment and bump type
workspace changeset history --filter-env production --filter-bump major

# 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 (mutually exclusive with --prerelease)
--snapshot-format <FORMAT> - Snapshot format template (variables: {version}, {branch}, {short_commit}, {commit})
--prerelease <TAG> - Pre-release tag (alpha, beta, or rc) (mutually exclusive with --snapshot)
--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)

Note: The --snapshot and --prerelease flags cannot be used together as they represent different versioning strategies.

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

§Changeset Archive Policies

When bumping versions, the CLI can automatically archive processed changesets based on configurable policies. This prevents changesets from being reused in future bumps while maintaining a complete history.

Available Policies:

Policy	Flags	Behavior	Use Case
Auto	(none)	Archives only stable versions	Default behavior - keeps prereleases active for iterative development
Never	`--no-archive`	Never archives changesets	Keep all changesets for review or manual cleanup
Always	`--always-archive`	Always archives changesets	Archive every bump, including prereleases

Policy Behavior:

Auto Policy (Default)

workspace bump --execute
# Stable version: 1.2.3 → 1.3.0
# Result: Changesets are ARCHIVED ✅

workspace bump --execute --prerelease beta.create
# Prerelease version: 1.2.3 → 1.3.0-beta.0
# Result: Changesets are NOT archived ❌ (kept for next bump)

Never Policy

workspace bump --execute --no-archive
# Any version: 1.2.3 → 1.3.0
# Result: Changesets are NOT archived ❌ (manual cleanup required)

Always Policy

workspace bump --execute --always-archive
# Stable version: 1.2.3 → 1.3.0
# Result: Changesets are ARCHIVED ✅

workspace bump --execute --prerelease beta.create --always-archive
# Prerelease version: 1.2.3 → 1.3.0-beta.0
# Result: Changesets are ARCHIVED ✅ (even for prereleases)

Prerelease Workflow Example:

The Auto policy enables clean prerelease workflows:

# Phase 1: Create initial beta (changesets NOT archived)
workspace bump --execute --prerelease beta.create
# 1.2.3 → 1.3.0-beta.0
# Changesets remain active ✓

# Phase 2: Increment beta (changesets NOT archived)
workspace bump --execute --prerelease beta.increment
# 1.3.0-beta.0 → 1.3.0-beta.1
# Changesets remain active ✓

# Phase 3: Create release candidate (changesets NOT archived)
workspace bump --execute --prerelease rc.create
# 1.3.0-beta.1 → 1.3.0-rc.0
# Changesets remain active ✓

# Phase 4: Promote to stable (changesets ARCHIVED)
workspace bump --execute --prerelease rc.promote
# 1.3.0-rc.0 → 1.3.0
# Changesets archived automatically ✓

Conflict Protection:

The --no-archive and --always-archive flags are mutually exclusive. The CLI prevents using both flags simultaneously:

workspace bump --execute --no-archive --always-archive
# Error: The argument '--no-archive' cannot be used with '--always-archive'

When to Use Each Policy:

Auto (recommended): Standard workflow with prerelease support
Never: Auditing, manual changeset management, or keeping full history active
Always: Strict cleanup even for prereleases, or when changesets are single-use

§`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:

--no-major - Exclude major version upgrades from results (default: included)
--no-minor - Exclude minor version upgrades from results (default: included)
--no-patch - Exclude patch version upgrades from results (default: included)
--no-dev - Exclude dev dependencies from results (default: included)
--peer - Include peer dependencies in results (default: excluded)
--packages <LIST> - Comma-separated list of packages to check
--registry <URL> - Override registry URL (must be valid HTTP/HTTPS URL)

Examples:

# Check all upgrades
workspace upgrade check

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

# Check only patch and minor upgrades
workspace upgrade check --no-major

# Exclude dev dependencies
workspace upgrade check --no-dev

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

# Include peer dependencies
workspace upgrade check --peer

# Use custom registry
workspace upgrade check --registry "https://npm.mycompany.com"

§`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 (use with caution! recommended for CI/CD or when using Git for version control)
--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"

# Apply without backup (CI/CD scenario with Git version control)
git add . && git commit -m "Pre-upgrade commit"
workspace upgrade apply --no-backup --force

§`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"

§`status` - Display Workspace Status

Shows comprehensive workspace information including repository type, package manager, active branch, pending changesets, and all workspace packages.

Usage:

workspace status

Output Includes:

Repository Type: simple (single package) or monorepo (with type: npm, yarn, pnpm, bun)
Package Manager: Detected package manager (npm, yarn, pnpm, bun) and lock file
Git Branch: Current branch name (if in a Git repository)
Pending Changesets: List of active changeset IDs
Packages: Table with name, version, and path for all workspace packages

Examples:

# Display workspace status (human-readable)
workspace status

# Display as JSON (for automation)
workspace --format json status

# Quiet mode (minimal output)
workspace --quiet status

JSON Output Structure:

{
  "success": true,
  "data": {
    "repository": {
      "kind": "monorepo",
      "monorepoType": "npm"
    },
    "packageManager": {
      "name": "npm",
      "lockFile": "package-lock.json"
    },
    "branch": {
      "name": "feature/new-api"
    },
    "changesets": [
      { "id": "feature-new-api" }
    ],
    "packages": [
      { "name": "@myorg/core", "version": "1.2.0", "path": "packages/core" },
      { "name": "@myorg/utils", "version": "1.0.5", "path": "packages/utils" }
    ]
  }
}

§`execute` - Execute Commands Across Packages

Runs commands across workspace packages with optional filtering, affected package detection, and parallel execution. Supports both npm scripts and system commands.

Usage:

workspace execute --cmd <COMMAND> [OPTIONS]

Options:

--cmd <COMMAND> - Command to execute (required)
- npm:<script> - Run npm script (e.g., npm:lint, npm:build, npm:test)
- Plain command - Run system command (e.g., echo hello, ls -la)
--filter-package <PACKAGES> - Comma-separated list of packages to run on (default: all). Cannot be used with --affected.
--affected - Execute only on packages affected by changes. Cannot be used with --filter-package.
--since <REF> - Since commit/branch/tag for affected detection (requires --affected)
--until <REF> - Until commit/branch/tag for affected detection (requires --affected, default: HEAD)
--branch <NAME> - Compare against branch for affected detection (requires --affected)
--parallel - Run commands in parallel across packages (default: sequential)
-- <ARGS> - Additional arguments to pass to the command

Command Formats:

Format	Description	Example
`npm:<script>`	Runs npm script via detected package manager	`npm:lint`, `npm:build`
Plain command	Runs system command directly	`echo hello`, `ls -la`

Affected Package Detection:

The --affected flag enables intelligent package detection based on Git changes. It supports three modes:

Mode	Flags	Description
Working Directory	`--affected`	Analyzes uncommitted changes (staged + unstaged)
Commit Range	`--affected --since <REF>`	Analyzes changes between commits
Branch Comparison	`--affected --branch <NAME>`	Compares current branch against target branch

Examples:

# Run npm lint script in all packages
workspace execute --cmd npm:lint

# Run npm test in specific packages
workspace execute --cmd npm:test --filter-package "@myorg/core,@myorg/utils"

# Run commands in parallel (faster for independent packages)
workspace execute --cmd npm:build --parallel

# Run system command in all packages
workspace execute --cmd "echo hello"

# Pass extra arguments to npm script
workspace execute --cmd npm:test -- --coverage --watch

# Run lint only in core package
workspace execute --cmd npm:lint --filter-package "@myorg/core"

# JSON output for CI/CD
workspace --format json execute --cmd npm:test

# --- Affected Package Examples ---

# Run tests only on packages with uncommitted changes
workspace execute --cmd npm:test --affected

# Run lint on packages changed since main branch (great for PRs)
workspace execute --cmd npm:lint --affected --branch main

# Run build on packages changed in last 5 commits
workspace execute --cmd npm:build --affected --since HEAD~5

# Run tests on affected packages in parallel
workspace execute --cmd npm:test --affected --parallel

# CI/CD: Run tests on affected packages comparing with main
workspace execute --cmd npm:test --affected --branch main --parallel

Execution Behavior:

Sequential (default): Commands run one package at a time, with streaming output
Parallel (--parallel): Commands run concurrently, output collected and displayed per package
npm Scripts: Validates script exists in package.json before execution
Failure Handling: Continues on failure, reports all failures at end with summary
Affected Mode: When no packages are affected, exits successfully with “No affected packages” message

JSON Output Structure:

{
  "success": true,
  "data": {
    "command": "npm:test",
    "results": [
      {
        "package": "@myorg/core",
        "success": true,
        "duration_ms": 1234,
        "exit_code": 0
      },
      {
        "package": "@myorg/utils",
        "success": true,
        "duration_ms": 567,
        "exit_code": 0
      }
    ],
    "summary": {
      "total": 2,
      "succeeded": 2,
      "failed": 0,
      "duration_ms": 1801
    }
  }
}

Use Cases:

# CI/CD: Run tests across all packages
workspace execute --cmd npm:test --parallel

# CI/CD: Run tests only on affected packages (faster CI)
workspace execute --cmd npm:test --affected --branch main --parallel

# Development: Lint before commit (only changed packages)
workspace execute --cmd npm:lint --affected

# PR Validation: Test only what changed
workspace execute --cmd npm:test --affected --branch origin/main

# Build specific packages
workspace execute --cmd npm:build --filter-package "@myorg/core"

# Run custom script with arguments
workspace execute --cmd npm:test -- --updateSnapshot

# Release: Build only packages changed since last release
workspace execute --cmd npm:build --affected --since v1.0.0

§`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, verbose
- Note: verbose is an alias for info level
-q, --quiet - Suppress all output
- Shortcut that sets both --log-level silent and --format quiet
- Useful for scripts that only care about exit codes
-v, --verbose - Enable verbose output
- Shortcut that sets --log-level debug
- Useful for debugging and troubleshooting
-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.

§Links

Root Project README - Project overview and features

§Planning Documents (Historical)

Product Requirements - Feature requirements and initial design
Implementation Plan - Detailed technical plan
Story Map - Development roadmap
CLI Draft - Initial CLI design concepts

Contributing • Issues

Part of Workspace Tools

Re-exports§

pub use cli::Cli;
pub use cli::Commands;
pub use cli::LogLevel;
pub use cli::OutputFormatArg;
pub use error::CliError;
pub use error::Result;
pub use interactive::prompts;
pub use output::JsonResponse;
pub use output::MultiProgress;
pub use output::OutputFormat;
pub use output::ProgressBar;
pub use output::Spinner;

Modules§

cli: CLI framework and argument parsing CLI framework module.
commands: Command implementations Command implementations module.
error: Error types and handling Error handling module for the CLI.
interactive: Interactive prompts and user input Interactive prompt module for CLI commands.
output: Output formatting and logging Output formatting and logging module.