Skip to content

cli-documentation.md

Latest commit

 

History

History
685 lines (498 loc) · 21.5 KB

cli-documentation.md

File metadata and controls

685 lines (498 loc) · 21.5 KB

Package Script Writer CLI Documentation

NuGet Downloads .NET

Interactive command-line tool for generating Umbraco CMS installation scripts

Quick Start · Features · Installation · Usage · Contributing

📋 Table of Contents

🎯 Overview

The Package Script Writer CLI (psw) is a powerful command-line tool that brings the full functionality of the Package Script Writer to your terminal. Built with .NET 10.0 and Spectre.Console, it provides a beautiful, interactive experience for generating Umbraco CMS installation scripts.

Why Use the CLI?

  • 🚀 Speed - Generate scripts faster than using the web interface
  • 🤖 Automation - Perfect for CI/CD pipelines and automated workflows
  • 💾 Templates - Save and reuse configurations across projects
  • 📊 History - Track all generated scripts automatically
  • 🔒 Security - Built-in command validation and secure input handling
  • 🎨 Beautiful UI - Rich terminal interface with colors, tables, and progress indicators

Perfect For

  • Developers who prefer the command line
  • CI/CD automation and scripting
  • Team standardization with reusable templates
  • Quick project setup workflows
  • Batch script generation

🚀 Quick Start

Get up and running in seconds:

# Install the tool globally from NuGet
dotnet tool install --global PackageScriptWriter.Cli

# Launch interactive mode
psw

# Or generate a default script immediately
psw --default

# Or automate with specific packages
psw -p "uSync,Diplo.GodMode" -n MyProject

That's it! You're ready to generate Umbraco installation scripts.

✨ Features

🎨 Dual Mode Operation

Interactive Mode - Beautiful terminal UI with step-by-step prompts:

  • Browse and search 500+ Umbraco Marketplace packages
  • Multi-select package picker with search functionality
  • Version selection for templates and packages
  • Complete configuration workflow with validation
  • Live progress indicators during API calls
  • Configuration summary before generation

CLI Mode - Full automation with command-line flags:

  • All configuration options available as flags
  • Perfect for scripts and CI/CD pipelines
  • One-liner script generation
  • Auto-execution capabilities
  • Batch processing support

📦 Script Generation

Generate complete, production-ready installation scripts:

  • Template Installation - Umbraco official and community templates
  • Project Creation - With solution file support
  • Package Management - Install with specific version pinning
  • Starter Kits - Choose from 9 different starter kits
  • Docker Support - Generate Dockerfile and Docker Compose files
  • Unattended Install - Pre-configure database and admin credentials
  • Database Setup - Support for SQLite, LocalDb, SQL Server, SQL Azure
  • Output Formats - Multi-line or one-liner with comment removal

💾 Template System

Save time with reusable configuration templates:

  • Save - Create templates from any configuration
  • Load - Quickly apply saved templates with optional overrides
  • Export/Import - Share templates with your team via YAML files
  • Validation - Built-in template validation before import
  • Organization - Tag and describe templates for easy discovery

📖 Read the Template Guide

📊 History Tracking

Automatic tracking of all generated scripts:

  • View History - See all previously generated scripts
  • Re-run - Regenerate and execute previous scripts
  • Execution Tracking - Track which scripts were executed and their status
  • Audit Trail - Complete record of all script generations
  • Search & Filter - Find scripts by project name, template, or date

📖 Read the History Guide

🔒 Security Features

Built-in security to protect your systems:

  • Command Allowlist - Only approved dotnet commands can be executed
  • Validation - All scripts validated before execution
  • Secure Input - Password fields are hidden during input
  • No Script Storage - Scripts regenerated from config (prevents tampering)
  • Safe Defaults - Secure configurations by default

📖 Read the Security Documentation

🔄 Resilience & Logging

Enterprise-grade reliability:

  • Automatic Retries - Exponential backoff with Polly for transient failures
  • Comprehensive Logging - File and console logging with Serilog
  • Verbose Mode - Detailed diagnostics with --verbose flag
  • Error Handling - User-friendly error messages with guidance
  • API Resilience - Graceful handling of API timeouts and failures

💻 Installation

Install from NuGet (Recommended)

The easiest way to install the CLI tool is from NuGet as a global .NET tool:

# Install globally
dotnet tool install --global PackageScriptWriter.Cli

# Verify installation
psw --version

Update to the latest version:

dotnet tool update --global PackageScriptWriter.Cli

Update to the latest prerelease version:

dotnet tool update --global PackageScriptWriter.Cli --prerelease

Update to a specific version:

dotnet tool update --global PackageScriptWriter.Cli --version 1.2.0

Uninstall:

dotnet tool uninstall --global PackageScriptWriter.Cli

Requirements

  • .NET 10.0 SDK or later (Download)
  • Internet connection (to fetch package information from Umbraco Marketplace)

Build from Source

For development or contributing:

  1. Clone the repository:

    git clone https://github.com/prjseal/Package-Script-Writer.git
cd Package-Script-Writer

  2. Build and pack:

    cd src
dotnet pack PackageCliTool -c Release

  3. Install from local package:

    dotnet tool install --global --add-source ./PackageCliTool/bin/Release PackageScriptWriter.Cli

  4. Run:

    psw

📖 Full Installation Guide

📖 Usage

The CLI tool supports two modes of operation: Interactive Mode and CLI Mode.

Interactive Mode

Launch the interactive terminal UI with a menu-driven interface:

psw

Main Menu Options:

  1. Use default script - Quick setup with sensible defaults
  2. Use local template - Load a saved template
  3. Use community template - Browse community-shared templates
  4. Load script from history - Re-run previous scripts
  5. Create new script - Full custom configuration
  6. Load Umbraco versions table - View version information
  7. Help - Display help information

📖 Complete Interactive Mode Guide

CLI Mode

Use command-line flags for automation and scripting:

# Generate default script
psw --default

# Custom script with packages (latest versions)
psw -p "uSync,Diplo.GodMode" -n MyProject

# Specific package versions
psw -p "uSync|17.0.0,clean|7.0.1" -n MyProject

# Full automation with unattended install
psw -p "uSync|17.0.0" -n MyProject -s MySolution \
    -u --database-type SQLite \
    --admin-email admin@test.com \
    --admin-password "SecurePass123!" \
    --auto-run

# Auto-run with build only (no server start)
psw -d -n MyProject -s MyProject \
    -u --database-type SQLite \
    --admin-email admin@test.com \
    --admin-password "SecurePass123!" \
    --auto-run --build-only

# Save script to file without interactive prompts (for programmatic use)
psw -d -n MyProject -s MyProject \
    -u --database-type SQLite \
    --admin-email admin@test.com \
    --admin-password "SecurePass123!" \
    -p "Umbraco.Forms" \
    --output-file install.sh --save-only

Command Reference

General Commands

psw --help              # Show help information
psw --version           # Show version number
psw versions            # Display Umbraco versions table
psw --default           # Generate default script

Script Configuration Flags

-p, --packages          # Packages: "pkg1|ver1,pkg2|ver2"
-t, --template-package  # Template package name and version
-n, --project-name      # Project name (default: MyProject)
-s, --solution          # Solution name
-k, --starter-kit       # Starter kit package name

Docker Options

--dockerfile            # Include Dockerfile
--docker-compose        # Include Docker Compose file

Unattended Install

-u, --unattended-defaults   # Use unattended install
--database-type             # SQLite, LocalDb, SQLServer, etc.
--connection-string         # Database connection string
--admin-name                # Admin user name
--admin-email               # Admin email address
--admin-password            # Admin password (min 10 chars)

Output Options

-o, --oneliner          # Output as one-liner
-r, --remove-comments   # Remove comments from script
--include-prerelease    # Include prerelease package versions
--verbose               # Enable verbose logging

Execution

--auto-run              # Automatically execute the generated script
--build-only            # Install and build without starting the web server
--run-dir               # Directory to run script in
--output-file <file>    # Output file path for saving the generated script
--save-only             # Save script to file (via --output-file) and exit without prompts

AI Agent & Automation Options

--output <format>       # Output format: json, plain (for machine consumption)
--script-only           # Output only the raw script text, no decoration
--no-interaction        # Suppress all interactive prompts
--dry-run               # Validate inputs and show config without generating script
--help-json             # Show all commands and options as structured JSON

AI Agent / Automation Examples

# Generate script as JSON (for programmatic use)
psw --default --output json

# Generate script with no decoration (pipe-friendly)
psw --default --script-only

# Validate config without generating (dry run)
psw --dry-run -p "uSync|17.0.0" --database-type SQLite

# Get help as JSON (for AI tool discovery)
psw --help-json

# List valid option values as JSON
psw list-options --output json

# List valid database types
psw list-options database-types

# Non-interactive mode (no prompts)
psw --default --no-interaction --script-only

# Save script to file (no prompts, for MCP/CI/CD)
psw --default -p "uSync" --output-file install.sh --save-only

# Get version as plain text
psw --version --output plain

Exit Codes (for scripting and automation):

Code Meaning
0 Success
1 General or unknown error
2 Validation error
3 Network or API error
4 Script execution error
5 File system or permission error

Updating

# Update to the latest stable release
dotnet tool update --global PackageScriptWriter.Cli

# Update to the latest prerelease version
dotnet tool update --global PackageScriptWriter.Cli --prerelease

# Update to a specific version
dotnet tool update --global PackageScriptWriter.Cli --version 1.2.0

# Check current version
psw --version

Template Commands

psw template save <name> [options]      # Save configuration as template
psw template load <name> [options]      # Load and execute template
psw template list                       # List all templates
psw template delete <name>              # Delete template
psw template export <name>              # Export template to YAML
psw template import <file>              # Import template from YAML
psw template validate <file>            # Validate template file

History Commands

psw history list                        # List recent script generations
psw history show <#>                    # Show details of specific entry
psw history rerun <#>                   # Re-run a previous script
psw history delete <#>                  # Delete history entry
psw history clear                       # Clear all history

📖 Complete Usage Guide

📚 Documentation

Comprehensive documentation is available for all aspects of the CLI tool:

Core Documentation

Document Description
README Complete CLI tool documentation with all features and options
Interactive Mode Guide Complete interactive mode walkthrough with all menu options
Release Notes Version history and changelog
Templates Guide Template system documentation with examples
History System History feature documentation (psw history commands)
Security Guide Security features and command allowlist documentation
Community Templates Using and creating community-shared templates
Default Script Guide Quick default script generation
Custom Script Guide Building fully customized scripts
Umbraco Versions Umbraco version reference and support timelines

Related Documentation

Document Description
API Reference REST API endpoints used by the CLI
Architecture System architecture and design patterns
Development Guide Setup, testing, and contributing guidelines

Quick Links

🤝 Contributing

We welcome contributions to the Package Script Writer CLI! Whether it's bug fixes, new features, documentation improvements, or testing, all contributions are appreciated.

How to Contribute

  1. Check Existing Issues - Browse GitHub Issues to see if your idea already exists
  2. Open a Discussion - For new features, open an issue first to discuss the approach
  3. Fork the Repository - Create your own fork to work in
  4. Create a Branch - Use descriptive branch names (e.g., feature/template-validation)
  5. Make Your Changes - Follow the existing code style and patterns
  6. Test Thoroughly - Ensure your changes work as expected
  7. Submit a Pull Request - Provide a clear description of your changes

Development Setup

# Clone the repository
git clone https://github.com/prjseal/Package-Script-Writer.git
cd Package-Script-Writer

# Navigate to CLI project
cd src/PackageCliTool

# Run the CLI in development
dotnet run

# Run with arguments
dotnet run -- --help
dotnet run -- -p "uSync" -n TestProject

# Build and pack
dotnet pack -c Release

# Run tests (if available)
dotnet test

Coding Guidelines

  • Follow C# conventions - Use standard C# naming and formatting
  • Keep it modular - Separate concerns into appropriate services and classes
  • Add comments - Document complex logic and public APIs
  • Handle errors gracefully - Provide user-friendly error messages
  • Test your changes - Ensure nothing breaks and new features work correctly

Areas Where We Need Help

  • 🐛 Bug Fixes - Report or fix issues you encounter
  • ✨ New Features - Add new capabilities to the CLI
  • 📖 Documentation - Improve or expand documentation
  • 🧪 Testing - Add unit tests and integration tests
  • 🎨 UI/UX - Enhance the terminal interface
  • 🌍 Localization - Add support for other languages

📖 Full Contributing Guide

🐛 Reporting Issues

Found a bug or have a feature request? We want to hear from you!

Before Reporting

  1. Check Existing Issues - Search GitHub Issues to avoid duplicates
  2. Try Latest Version - Update to the latest version: dotnet tool update --global PackageScriptWriter.Cli
  3. Enable Verbose Logging - Run with --verbose flag to get detailed diagnostic output
  4. Check Log Files - Review logs in logs/psw-cli-{Date}.log

How to Report an Issue

Create a new issue on GitHub with the following information:

For Bugs:

  • Description - Clear description of the problem
  • Steps to Reproduce - Exact steps to reproduce the issue
  • Expected Behavior - What should happen
  • Actual Behavior - What actually happens
  • Environment - OS, .NET version, CLI tool version
  • Logs - Relevant log entries (use verbose mode)
  • Screenshots - If UI-related, include screenshots

For Feature Requests:

  • Description - Clear description of the feature
  • Use Case - Why is this feature needed?
  • Proposed Solution - How should it work?
  • Alternatives - Any alternative approaches considered?

For Security Issues:

  • DO NOT open a public issue for security vulnerabilities
  • Report privately via GitHub Security Advisories
  • See Security Policy

Issue Templates

When creating an issue on GitHub, select the appropriate template:

  • 🐛 Bug Report - For reporting bugs and errors
  • ✨ Feature Request - For suggesting new features
  • 📖 Documentation - For documentation improvements
  • 🔒 Security Issue - For reporting security vulnerabilities (use private advisory)

Report an Issue on GitHub

💬 Support & Community

Getting Help

  • Documentation - Check this documentation and the README
  • GitHub Issues - Search existing issues or create a new one
  • GitHub Discussions - Ask questions and share ideas
  • Umbraco Community - Connect with other Umbraco developers

Troubleshooting

Common Issues:

Tool not found after installation:

# Ensure .NET tools path is in your PATH
# Linux/macOS: Add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:$HOME/.dotnet/tools"

# Windows: Usually added automatically, or add manually:
# %USERPROFILE%\.dotnet\tools

Package not found:

  • Verify package name is correct
  • Check internet connectivity
  • Try with --verbose flag for detailed API logs
  • Ensure package exists on NuGet or Umbraco Marketplace

API connection issues:

  • The API is only used for fetching package data
  • Script generation is performed locally
  • Check logs in logs/ directory
  • The tool automatically retries failed requests 3 times

Enable verbose logging:

# Option 1: Flag
psw --verbose

# Option 2: Environment variable
export PSW_VERBOSE=1  # Linux/macOS
set PSW_VERBOSE=1     # Windows CMD
$env:PSW_VERBOSE=1    # Windows PowerShell

📖 Full Troubleshooting Guide

Community Resources

📝 License

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

Third-Party Licenses

The CLI tool uses several open-source libraries:

  • Spectre.Console - MIT License
  • Serilog - Apache License 2.0
  • Polly - BSD 3-Clause License
  • YamlDotNet - MIT License

👨‍💻 Author

Paul Seal

🙏 Acknowledgments

  • Umbraco Community - For the amazing CMS and package ecosystem
  • Microsoft - For .NET and excellent tooling
  • Spectre.Console - For the beautiful terminal UI library
  • Contributors - Everyone who has contributed to this project
  • Beta Testers - Thank you for testing and providing feedback!

📊 Project Stats

GitHub stars GitHub forks NuGet Downloads

⭐ If this tool helps you, consider giving it a star! ⭐

Made with ❤️ for the Umbraco Community

Back to Top ↑