AppSwap CLI

A comprehensive, developer-friendly command-line tool for publishing software packages across multiple distribution platforms. AppSwap CLI helps teams standardize release workflows, enforce consistent versioning, and automate multi-target publishing strategies.

🚀 Key Features

🔧 Configuration-Driven

• .appswap/ directory at project root for all configuration
• publish.yaml → defines destinations, branch patterns, and strategies
• version.yaml → versioning rules and defaults
• hooks/ → optional pre/post publish scripts

📦 Multi-Target Publishing

• Publish to multiple providers in one command
• Supported platforms: NPM, GitHub Releases, GitLab Releases, private registries
• Branch-based rules: different destinations per branch
• Extensible plugin system (coming soon)

🌿 Smart Versioning

• Multiple strategies: major, minor, patch, prerelease, branch, calendar
• Automatic detection of latest versions from registries
• Git integration with automatic tagging
• Conventional commits support for changelog generation

🛠 Developer Experience

• Dry-run mode for safe testing
• Health checks with appswap doctor
• Status overview across all destinations
• Interactive setup with appswap init
• CI/CD friendly non-interactive mode

📋 Quick Start

Installation

npm install -g @appswap/cli

Initialize Project

# Interactive setup
appswap init

# Quick non-interactive setup
appswap init --no-interactive

Basic Usage

# Check project health
appswap doctor

# Bump version
appswap version patch

# Publish based on branch configuration
appswap publish

# Check status across all destinations
appswap status

🌟 Commands Overview

appswap init

Bootstrap AppSwap configuration for your project

• Interactive setup with smart defaults
• Template support for team consistency
• Automatic project analysis

appswap version [strategy]

Calculate and update package version

• Strategies: major, minor, patch, prerelease, branch, calendar
• Git integration with automatic tagging
• Branch-aware versioning based on configuration

appswap publish

Publish package based on branch configuration

• Multi-target publishing to npm, GitHub, GitLab
• Automated hooks for build and test steps
• Pre-flight checks for clean git state
• Selective publishing with --target override

appswap status

Show currently published versions across all destinations

• Version comparison between local and published
• Detailed mode with URLs and timestamps
• JSON output for automation

appswap doctor

Validate configuration and check project health

• Comprehensive health checks
• Auto-fix mode for common issues
• CI/CD environment validation

🎯 Advanced Usage

Branch-Based Publishing

# .appswap/publish.yaml
branches:
  main:
    destinations: [npm, github]
    versionStrategy: minor
  
  'feature/*':
    destinations: [npm]
    versionStrategy: branch
    
  'hotfix/*':
    destinations: [npm, github]
    versionStrategy: patch

Multiple Registries

destinations:
  npm:
    type: npm
    registry: https://registry.npmjs.org
    
  private-npm:
    type: npm
    registry: https://npm.company.com
    private: true
    
  github:
    type: github
    releaseNotes: true

Custom Hooks

hooks:
  prepublish:
    - npm run build
    - npm test
    - .appswap/hooks/security-scan.sh
    
  postpublish:
    - .appswap/hooks/notify-slack.sh
    - .appswap/hooks/update-docs.sh

Version Strategies

Calendar Versioning

appswap version calendar  # → 2025.09.05

Branch Versioning

# On feature/login branch
appswap version branch    # → 1.0.1-feature-login.0

Prerelease Versioning

appswap version prerelease  # → 1.0.1-alpha.0

🔄 CI/CD Integration

GitHub Actions

name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - run: npm ci
      - run: npx @appswap/cli doctor --fix
      - run: npx @appswap/cli version
      - run: npx @appswap/cli publish
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

release:
  stage: deploy
  script:
    - npm ci
    - npx @appswap/cli doctor
    - npx @appswap/cli version
    - npx @appswap/cli publish
  variables:
    NPM_TOKEN: $CI_NPM_TOKEN
    GITLAB_TOKEN: $CI_JOB_TOKEN
  only:
    - main

🔐 Environment Variables

# Registry Authentication
NPM_TOKEN=npm_xxx
GITHUB_TOKEN=ghp_xxx
GITLAB_TOKEN=glpat_xxx

# Notifications (optional)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

🎨 Examples

Release Workflow

# Check everything is ready
appswap doctor

# See current status
appswap status

# Bump version for release
appswap version minor

# Publish to configured destinations
appswap publish

# Or test first
appswap publish --dry-run

Feature Development

# Create feature branch version
appswap version branch  # 1.0.1-feature-xyz.0

# Publish to npm only (per branch config)
appswap publish

Hotfix Release

# Quick patch version
appswap version patch

# Emergency publish (skip some checks)
appswap publish --force --skip-hooks

Multi-Target Override

# Publish to specific targets only
appswap publish --target npm,github

# Skip build if already done
appswap publish --skip-build

🛡 Safety Features

• Dry-run mode for all operations
• Pre-flight checks for git cleanliness
• Version validation before publishing
• Registry connectivity verification
• Build verification before publish

🔧 Configuration Reference

publish.yaml

branches:
  <branch-pattern>:
    destinations: [<destination-names>]
    versionStrategy: <strategy>
    buildCommand: <command>
    skipHooks: <boolean>

destinations:
  <name>:
    type: npm|github|gitlab|custom
    registry: <url>          # for npm type
    token: <env-var>         # override default
    owner: <github-owner>    # for github/gitlab
    repo: <repo-name>        # for github/gitlab
    releaseNotes: <boolean>  # generate release notes
    private: <boolean>       # npm access level

hooks:
  prepublish: [<commands>]
  postpublish: [<commands>]
  preversion: [<commands>]
  postversion: [<commands>]

version.yaml

defaultStrategy: patch|minor|major|prerelease|branch|calendar
tagPrefix: v
changelog:
  enabled: true
  format: conventional|custom
  file: CHANGELOG.md
overrides:
  <branch>: <strategy>

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

📜 License

MIT License - see LICENSE file for details.

🆘 Support

• Documentation: Check .appswap/README.md after running appswap init
• Health Check: Run appswap doctor for diagnostics
• Issues: GitHub Issues
• Discussions: GitHub Discussions