cli/readme.md

@git.zone/cli 🚀

The ultimate CLI toolbelt for modern TypeScript development workflows

🎯 What is gitzone?

gitzone is a powerful command-line interface that supercharges your development workflow with automated project management, intelligent code formatting, seamless version control, and development service orchestration. Whether you're bootstrapping a new TypeScript project, maintaining code quality, managing complex multi-repository setups, or spinning up local development databases, gitzone has got you covered.

🏃‍♂️ Quick Start

Installation

# Install globally via npm
npm install -g @git.zone/cli

# Or with pnpm (recommended)
pnpm add -g @git.zone/cli

Once installed, you can use either gitzone or the shorter gzone command from anywhere in your terminal.

Your First Commands

# Create a new TypeScript npm package
gitzone template npm

# Format your entire codebase
gitzone format

# Start local MongoDB and MinIO services
gitzone services start

# Create a semantic commit
gitzone commit

🛠️ Core Features

🐳 Development Services Management (NEW!)

Effortlessly manage local MongoDB and MinIO (S3-compatible) services for your development environment:

gitzone services [command]

Available commands:

• start [service] - Start services (mongo|s3|all)
• stop [service] - Stop services (mongo|s3|all)
• restart [service] - Restart services
• status - Show current service status
• config - Display configuration details
• compass - Get MongoDB Compass connection string with network IP
• logs [service] [lines] - View service logs
• remove - Remove containers (preserves data)
• clean - Remove containers AND data (⚠️ destructive)

Key features:

• 🎲 Smart port assignment - Automatically assigns random ports (20000-30000) to avoid conflicts
• 📦 Project isolation - Each project gets its own containers with unique names
• 💾 Data persistence - Data stored in .nogit/ directories survives container restarts
• 🔗 MongoDB Compass support - Instantly get connection strings for GUI access
• 🌐 Network IP detection - Automatically detects your local network IP for remote connections
• ⚙️ Auto-configuration - Creates .nogit/env.json with smart defaults

Example workflow:

# Start all services for your project
gitzone services start

# Check what's running
gitzone services status

# Get MongoDB Compass connection string
gitzone services compass
# Output: mongodb://defaultadmin:defaultpass@192.168.1.100:27018/myproject?authSource=admin

# View MongoDB logs
gitzone services logs mongo 50

# Stop services when done
gitzone services stop

The services are configured via .nogit/env.json which is automatically created with secure defaults and random ports for each project.

📦 Project Templates

Instantly scaffold production-ready projects with best practices built-in:

gitzone template [template-name]

Available templates:

• npm - TypeScript npm package with testing, CI/CD, and full tooling
• service - Microservice architecture with Docker support
• website - Modern web application with LitElement and service workers
• wcc - Web Component Collection for reusable UI components

Each template comes pre-configured with:

• ✅ TypeScript with modern configurations
• ✅ Automated testing setup
• ✅ CI/CD pipelines (GitLab/GitHub)
• ✅ Code formatting and linting
• ✅ Documentation structure

🎨 Intelligent Code Formatting

The most powerful feature of gitzone - automatically format and standardize your entire codebase:

# Preview changes without applying them
gitzone format --dry-run

# Format with automatic approval
gitzone format --yes

# Save formatting plan for later execution
gitzone format --save-plan format-plan.json

# Execute a saved plan
gitzone format --from-plan format-plan.json

# Enable verbose output for debugging
gitzone format --verbose

Format features:

• 🔄 Smart caching - Only processes changed files
• 🛡️ Rollback support - Undo formatting changes if needed
• 📊 Detailed reporting - See exactly what changed
• ⚡ Parallel execution - Format multiple files simultaneously
• 🎯 Module-specific formatting - Target specific formatters

Rollback capabilities:

# List all available backups
gitzone format --list-backups

# Rollback to the last operation
gitzone format --rollback

# Rollback to a specific operation
gitzone format --rollback [operation-id]

# Clean old backups
gitzone format --clean-backups

Formatters included:

• Prettier - JavaScript/TypeScript code formatting
• License - Ensure proper licensing
• Package.json - Standardize package configurations
• Tsconfig - TypeScript configuration optimization
• Readme - Documentation formatting
• Gitignore - Repository ignore rules
• Templates - Project template updates
• Npmextra - Extended npm configurations

🔀 Semantic Commits & Versioning

Create standardized commits that automatically handle versioning:

gitzone commit

Features:

• 📝 Interactive commit message builder
• 🏷️ Automatic version bumping (major/minor/patch)
• 📜 Changelog generation
• 🚀 Optional auto-push to origin
• 🎯 Conventional commit compliance

The commit wizard guides you through:

1. Type selection (feat/fix/docs/style/refactor/perf/test/chore)
2. Scope definition (component/module affected)
3. Description crafting
4. Breaking change detection
5. Version bump determination

🏗️ Meta Repository Management

Manage multiple related repositories as a cohesive unit:

# Initialize a meta repository
gitzone meta init

# Add a sub-project
gitzone meta add [name] [git-url]

# Update all sub-projects
gitzone meta update

# Remove a sub-project
gitzone meta remove [name]

Perfect for:

• Monorepo management
• Multi-package projects
• Coordinated deployments
• Synchronized versioning

🐳 Docker Management

Streamline your Docker workflow:

# Clean up all Docker resources
gitzone docker prune

This command removes:

• Stopped containers
• Unused images
• Dangling volumes
• Unused networks

🔗 Quick CI/CD Access

Jump directly to your CI/CD configurations:

# Open CI/CD settings
gitzone open ci

# Open pipelines view
gitzone open pipelines

Works with GitLab repositories to provide instant access to your deployment configurations.

📝 Package Deprecation

Smoothly transition users from old to new packages:

gitzone deprecate

Interactive wizard for:

• Setting deprecation notices
• Guiding users to replacements
• Updating registry metadata
• Coordinating migration paths

🚦 Project Initialization

Prepare existing projects for development:

gitzone start

Automatically:

• Checks out master branch
• Pulls latest changes
• Installs dependencies
• Sets up development environment

🔧 Helper Utilities

Quick utilities for common tasks:

# Generate a unique short ID
gitzone helpers shortid

📋 Configuration

npmextra.json Configuration

Customize gitzone behavior through npmextra.json:

{
  "gitzone": {
    "format": {
      "interactive": true,
      "showDiffs": false,
      "autoApprove": false,
      "parallel": true,
      "rollback": {
        "enabled": true,
        "autoRollbackOnError": true,
        "backupRetentionDays": 7
      },
      "modules": {
        "skip": ["prettier"],
        "only": [],
        "order": []
      },
      "cache": {
        "enabled": true,
        "clean": true
      }
    }
  }
}

Environment Variables

• CI - Detect CI environment for automated workflows
• DEBUG - Enable debug output
• GITZONE_FORMAT_PARALLEL - Control parallel formatting

🏆 Best Practices

For New Projects

1. Start with a template: gitzone template npm
2. Set up local services: gitzone services start
3. Customize the generated structure
4. Run initial format: gitzone format
5. Set up CI/CD: gitzone open ci

For Existing Projects

1. Initialize: gitzone start
2. Format codebase: gitzone format --dry-run (preview first!)
3. Apply formatting: gitzone format --yes
4. Set up services: gitzone services start
5. Commit changes: gitzone commit

For Teams

1. Document format preferences in npmextra.json
2. Share .nogit/env.json template for consistent service setup
3. Use --save-plan for reviewable format changes
4. Enable rollback for safety
5. Standardize commit conventions

🎯 Common Workflows

Full-Stack Development Cycle

# 1. Start fresh
gitzone start

# 2. Spin up databases and services
gitzone services start

# 3. Make changes
# ... your development work ...

# 4. Check service logs if needed
gitzone services logs mongo

# 5. Format code
gitzone format

# 6. Commit with semantic versioning
gitzone commit

# 7. Stop services when done
gitzone services stop

Multi-Repository Management

# 1. Set up meta repository
gitzone meta init

# 2. Add all related projects
gitzone meta add frontend https://github.com/org/frontend.git
gitzone meta add backend https://github.com/org/backend.git
gitzone meta add shared https://github.com/org/shared.git

# 3. Synchronize updates
gitzone meta update

Safe Formatting with Rollback

# 1. Preview changes
gitzone format --dry-run

# 2. Save plan for review
gitzone format --save-plan format-changes.json

# 3. Apply formatting
gitzone format --from-plan format-changes.json

# 4. If something goes wrong, rollback
gitzone format --rollback

Database-Driven Development

# 1. Start MongoDB and MinIO
gitzone services start

# 2. Get connection string for your app
gitzone services config

# 3. Connect with MongoDB Compass
gitzone services compass

# 4. Monitor services
gitzone services status

# 5. Clean everything when done
gitzone services clean  # ⚠️ Warning: deletes data

🔌 Integrations

CI/CD Platforms

• GitLab CI - Full pipeline support with templates
• GitHub Actions - Automated workflows
• Docker - Container-based deployments

Development Tools

• TypeScript - First-class support
• Prettier - Code formatting
• ESLint - Linting (via format modules)
• npm/pnpm - Package management
• MongoDB - Local database service
• MinIO - S3-compatible object storage
• MongoDB Compass - Database GUI integration

Version Control

• Git - Deep integration
• Semantic Versioning - Automatic version bumping
• Conventional Commits - Standardized commit messages

💡 Pro Tips

1. Use aliases: Add alias gz='gitzone' to your shell profile
2. Combine commands: gitzone format --yes && gitzone commit
3. Leverage templates: Start projects right with proven structures
4. Enable caching: Dramatically speeds up formatting operations
5. Save format plans: Review changes before applying in production
6. Port management: Let services auto-assign ports to avoid conflicts
7. Use MongoDB Compass: gitzone services compass for visual DB management

🐛 Troubleshooting

Format Command Shows "Cancelled"

If the format command shows cancelled even after confirming:

• Check your npmextra.json configuration
• Try with --yes flag to skip confirmation
• Use --verbose for detailed output

Docker Commands Fail

Ensure Docker daemon is running:

docker info

Services Won't Start

Check for port conflicts:

# Services auto-assign ports, but you can check the config
cat .nogit/env.json

# Verify Docker is running
docker ps

Template Creation Issues

Verify npm/pnpm is properly configured:

npm config get registry

MongoDB Connection Issues

• Ensure services are running: gitzone services status
• Check firewall settings for the assigned ports
• Use gitzone services compass for the correct connection string

📈 Performance

gitzone is optimized for speed:

• Parallel processing for format operations
• Smart caching to avoid redundant work
• Incremental updates for meta repositories
• Minimal dependencies for fast installation
• Isolated services prevent resource conflicts
• Auto port assignment eliminates manual configuration

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.