Changerawr CLI

The official command-line interface for Changerawr
Special thanks to the Secton Team for advisory and active feedback during development.

✨ Features

• 🔗 Project Linking - Connect your Git repositories to Changerawr projects
• 🔄 Auto-Sync - Automatically sync commits via Git hooks
• 📝 Changelog Generation - Generate beautiful changelogs from your commits
• 🌐 Multi-Instance Support - Work with multiple Changerawr instances
• 🔐 Secure Authentication - Browser-based OAuth flow with token management
• 📊 Status Monitoring - Track sync status and project health
• 🛠️ Troubleshooting - Built-in diagnostics and issue resolution

🚀 Installation

Install the Changerawr CLI globally using npm:

npm install -g changerawr

Or use it with npx without installing:
Not recommended as Changerawr stores your system configuration in your home directory, but do as you prefer.

npx changerawr <command>

Requirements

• Node.js 16.0.0 or higher
• Git (for repository integration)
• A Changerawr account and instance

🎯 Quick Start

1. Initialize your project:

   changerawr init

2. Authenticate with your Changerawr instance:

   changerawr auth login

3. Link to a Changerawr project:

   changerawr link

4. Install Git hooks for auto-sync:

   changerawr hooks install

5. Check everything is working:

   changerawr status

That's it! Your repository is now connected to Changerawr and will automatically sync commits.

📖 Commands

Setup & Configuration

changerawr init

Initialize Changerawr in the current directory.

changerawr init                           # Interactive setup
changerawr init --instance https://my.changerawr.tld
changerawr init --project-id abc123 --force

Options:

• -i, --instance <url> - Changerawr instance URL
• -p, --project-id <id> - Existing project ID to link
• -f, --force - Overwrite existing configuration

Authentication

changerawr auth login

Authenticate with a Changerawr instance using your browser.

changerawr auth login                     # Use configured instance
changerawr auth login --instance https://my.changerawr.tld

changerawr auth logout

Remove authentication credentials.

changerawr auth logout                    # Logout from current instance
changerawr auth logout --all              # Logout from all instances

changerawr auth status

Show authentication status for all instances.

changerawr auth refresh

Refresh expired authentication tokens.

Project Management

changerawr link

Link the current directory to a Changerawr project.

changerawr link                           # Interactive project selection
changerawr link --project-id abc123      # Link to specific project
changerawr link --create "My Project"    # Create and link new project

changerawr unlink

Disconnect the current directory from Changerawr.

changerawr unlink                         # Interactive unlink
changerawr unlink --keep-hooks            # Keep Git hooks installed
changerawr unlink --remove-changelog     # Also remove CHANGELOG.md

Git Integration

changerawr hooks install

Install Git hooks for automatic syncing.

changerawr hooks install                  # Install all hooks
changerawr hooks install --force          # Overwrite existing hooks
changerawr hooks install --quiet          # Silent installation

Installed hooks:

• post-commit - Sync new commits automatically
• pre-push - Update changelog before pushing
• post-merge - Sync commits after merging

changerawr hooks uninstall

Remove Changerawr Git hooks.

changerawr hooks uninstall                # Interactive removal
changerawr hooks uninstall --all          # Remove without confirmation

changerawr hooks status

Show Git hooks installation status.

Changelog Management

changerawr generate

Generate a changelog from your Changerawr project.

changerawr generate                       # Generate to CHANGELOG.md
changerawr generate --output HISTORY.md  # Custom output file
changerawr generate --version v1.2.0     # Specific version
changerawr generate --preview             # Preview before writing
changerawr generate --force               # Overwrite existing file

changerawr pull

Pull the latest changelog from Changerawr to your local file.

changerawr pull                           # Pull to configured changelog file
changerawr pull --force                   # Overwrite without confirmation
changerawr pull --backup                  # Create backup before overwriting
changerawr pull --quiet                   # Silent operation

Monitoring & Diagnostics

changerawr status

Show comprehensive status of your project setup.

changerawr status

Displays:

• Environment information
• Project configuration
• Git repository status
• Authentication status
• Project linking status
• Git hooks status
• Changelog file status

changerawr doctor

Run comprehensive diagnostics and troubleshooting.

changerawr doctor

Checks:

• Environment (Node.js, Git, connectivity)
• Configuration files
• Authentication tokens
• Project linking
• Git hooks installation
• Changelog files
• API connectivity

⚙️ Configuration

Project Configuration

Each project has a local configuration file at .changerawr/config.json:

{
  "projectId": "abc123",
  "instanceUrl": "https://my.changerawr.tld",
  "changelog": {
    "filename": "CHANGELOG.md",
    "includeAuthor": true,
    "groupByType": true,
    "autoGenerate": true
  },
  "sync": {
    "autoSync": true,
    "interval": 5,
    "retryAttempts": 3
  },
  "ui": {
    "showSpinners": true,
    "colorOutput": true,
    "verbose": false
  }
}

Global Configuration

Global settings are stored in ~/.changerawr/config.json and include:

• Multiple instance configurations
• Authentication status
• Default settings
• Cached project data

🔧 Advanced Usage

Working with Multiple Instances

The CLI supports multiple Changerawr instances:

# Configure different projects for different instances
cd project-a
changerawr init --instance https://company-a.changerawr.tld

cd ../project-b  
changerawr init --instance https://company-b.changerawr.tld

# The CLI remembers which instance each project uses
changerawr status  # Shows appropriate instance for each project

Custom Workflows

Automated Release Workflow

# 1. Sync latest commits
changerawr sync

# 2. Generate changelog
changerawr generate --version v1.2.0

# 3. Commit and tag
git add CHANGELOG.md
git commit -m "chore: release v1.2.0"
git tag v1.2.0
git push && git push --tags

Team Collaboration

# New team member setup
git clone https://github.com/company/project
cd project
changerawr auth login                     # Authenticate
changerawr hooks install                  # Enable auto-sync

Conventional Commits

The CLI automatically parses and categorizes Conventional Commits:

git commit -m "feat: add user authentication"
git commit -m "fix: resolve login redirect issue"  
git commit -m "docs: update API documentation"

Supported types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

🐛 Troubleshooting

Common Issues

Authentication not working?

changerawr doctor                         # Run diagnostics
changerawr auth refresh                   # Refresh tokens
changerawr auth login                     # Re-authenticate

Git hooks not triggering?

changerawr hooks status                   # Check installation
changerawr hooks install --force          # Reinstall hooks

Sync not working?

changerawr status                         # Check project status
changerawr doctor                         # Full diagnostics

Connection issues?

changerawr doctor                         # Check connectivity
# Verify instance URL and firewall settings

Debug Mode

Enable verbose logging for troubleshooting:

changerawr --verbose <command>
changerawr -v status

Getting Help

changerawr help                           # General help
changerawr help <command>                 # Command-specific help
changerawr --version                      # Show CLI version

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development

# Clone the repository
git clone https://github.com/changerawr/cli.git
cd cli

# Install dependencies
npm install

# Build the CLI
npm run build

# Run locally
npm start <command>

# Run tests
npm test

📄 License

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

🔗 Links

• 🐛 Issue Tracker
• 💬 Discussions
• 📦 npm Package

📊 Status

• ✅ Stable - Ready for production use
• 🔄 Actively Maintained - Regular updates and bug fixes
• 🛡️ Secure - Regular security audits and updates
• 🌍 Cross-Platform - Windows, macOS, and Linux support

Made with ❤️ by the Changerawr team