smooth-cli 0.4.0
SmoothDev CLI tool for PR generation, commit message generation, and documentation management
Requires Python: <4.0,>=3.12

# SmoothDev CLI

🤖 AI-powered development tools for commit messages, pull requests, release notes, and documentation generation.

[![PyPI Version](https://img.shields.io/pypi/v/smooth-cli.svg)](https://pypi.org/project/smooth-cli/)
[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

## Overview

SmoothDev CLI provides intelligent assistance for your development workflow:

- **📝 Smart Commit Messages** - Generate conventional commit messages from staged changes
- **📋 Automated PR Documentation** - Create professional PR titles and summaries
- **📦 Release Notes Generation** - Generate comprehensive release notes from git history
- **📚 Documentation Generation** - AI-powered repository documentation creation
- **🔐 Flexible Authentication** - Auth0 JWT and API key authentication
- **⚙️ Smart Configuration** - Auto-detection reduces CLI flags by 80%
- **🤖 GitHub Actions Integration** - Automated workflows for PR and release documentation

## Quick Start

### Installation

```bash
pip install smooth-cli
```

### Authentication

```bash
# Interactive login (recommended for personal use)
smooth auth login

# API key authentication (ideal for CI/CD)
smooth auth apikey-set your_api_key_here
```

### First Use

```bash
# Generate a commit message
git add .
smooth commit generate --commit

# Generate PR documentation
smooth pr generate --pr-number 42

# Generate release notes
smooth release generate
```

## Features

### Commit Messages

Generate conventional commit messages that follow best practices:

```bash
# Generate from staged changes
smooth commit generate

# Generate and commit immediately
smooth commit generate --commit

# Associate with issue number
smooth commit generate --issue ENG-123
```

**Features:**

- Conventional Commits specification compliance
- Automatic issue number detection from branch names (e.g., `feature/ENG-123`)
- Multiple latency profiles (fast/balanced/quality)
- Issue key automatically appended to commit footer

### Pull Request Documentation

Create professional PR titles and summaries:

```bash
# Auto-detect from git context
smooth pr generate

# Specify PR number
smooth pr generate --pr-number 42

# Update PR on GitHub
smooth pr generate --pr-number 42 --push
```

**Features:**

- Smart auto-detection of owner/repo/PR number
- Structured summaries with overview, changes, testing sections
- Breaking change detection and migration guidance
- JSON output for automation

### Release Notes

Generate comprehensive release notes between tags:

```bash
# Auto-detect latest tags
smooth release generate

# Specify tag range
smooth release generate --from-tag v1.0.0 --to-tag v1.1.0

# Create GitHub Release
smooth release generate --push --tag v1.1.0

# Create draft GitHub Release
smooth release generate --push --tag v1.1.0 --draft
```

**Features:**

- Semantic versioning support
- Categorized changes (features, fixes, documentation, etc.)
- Breaking change detection with migration steps
- Contributor statistics and acknowledgments
- Draft release support for review before publishing

### Documentation Generation

AI-powered repository documentation:

```bash
# Check documentation status
smooth docs status

# Generate LITE documentation (quick overview)
smooth docs generate

# Generate FULL documentation (comprehensive)
smooth docs generate --full --write

# Validate existing documentation
smooth docs validate
```

**Features:**

- LITE and FULL generation modes
- Documentation validation and quality checks
- PR-focused documentation generation
- Integration with CI/CD workflows

## Authentication

### Auth0 Device Flow (Interactive)

For personal development and interactive use:

```bash
smooth auth login
```

This opens a browser for secure authentication and stores a JWT token.

### API Key Authentication (CI/CD)

For automated workflows and CI/CD:

```bash
# Set API key
smooth auth apikey-set your_api_key_here

# Show current key
smooth auth apikey-show

# Switch to API key mode
smooth auth mode-set api-key
```

### Authentication Modes

```bash
# Show current mode
smooth auth mode-show

# Available modes
smooth auth mode-set jwt    # Auth0 (interactive)
smooth auth mode-set api-key # API key (CI/CD)
smooth auth mode-set auto    # Auto-detect
```

## Configuration

The CLI uses a four-tier configuration system for smart defaults:

1. **CLI Flags** - Explicit command-line arguments
2. **Git Context** - Auto-detected from your repository
3. **Repository Config** - Team settings in `.smoothdev.json`
4. **User Config** - Personal defaults in `~/.smoothdevio/config.json`

### Quick Setup

```bash
# Initialize user config
smooth config init --owner your-username --output text

# Show current configuration
smooth config show

# Set specific values
smooth config set defaults.output json
```

### GitHub Token

For commands that interact with GitHub:

```bash
# Set in config
smooth config set github_token ghp_your_token_here

# Or use environment variable
export GITHUB_TOKEN=ghp_your_token_here
```

## GitHub Actions Integration

Automate your workflow with our GitHub Actions:

### PR Summary Action

Generate PR titles and summaries automatically:

```yaml
- uses: smoothdev-io/pr-summary-action@v1
  with:
    api_key: ${{ secrets.SMOOTHDEV_API_KEY }}
    push_to_pr: true
```

**Repository:** [smoothdev-io/pr-summary-action](https://github.com/smoothdev-io/pr-summary-action)

### Release Notes Action

Create comprehensive release notes on tag push:

```yaml
- uses: smoothdev-io/release-notes-action@v1
  with:
    api_key: ${{ secrets.SMOOTHDEV_API_KEY }}
    push_to_github: true
    release_tag: ${{ github.ref_name }}
```

**Repository:** [smoothdev-io/release-notes-action](https://github.com/smoothdev-io/release-notes-action)

## Command Reference

### Core Commands

- `smooth commit` - Generate commit messages
- `smooth pr` - Generate PR documentation
- `smooth release` - Generate release notes
- `smooth docs` - Generate repository documentation
- `smooth config` - Manage configuration
- `smooth auth` - Manage authentication

### Global Options

- `--help` - Show help information
- `--version` - Show version information
- `--verbose` - Enable verbose output
- `--output <format>` - Output format: `text` or `json`

## Getting Help

- **Documentation**: [docs.smoothdev.io](https://docs.smoothdev.io)
- **GitHub Issues**: [smoothdev-io/sd-smooth-cli](https://github.com/smoothdev-io/sd-smooth-cli/issues)
- **Support**: engineering@smoothdev.io

## License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

---

**Built with ❤️ by the SmoothDev Team** | [smoothdev.io](https://smoothdev.io)