Skip to content

CLI Installation & Setup

The SmoothDev CLI (smooth) is a Python-based command-line tool that provides AI-powered assistance for commit messages, pull requests, and release notes.

Requirements

  • Python 3.12 or higher
  • Git installed and configured
  • GitHub account (for PR and release features)
  • SmoothDev account (sign up at smoothdev.io)

Installation

The easiest way to install the SmoothDev CLI is via pip:

pip install smooth-cli

Verify Installation

Check that the CLI is installed correctly:

smooth --version

You should see output showing the installed version (e.g., 0.3.3).

View Available Commands

smooth --help

Authentication

Before using the CLI, you need to authenticate with your SmoothDev account.

Login with Auth0

The CLI uses Auth0 device flow for secure authentication:

smooth auth login

This will:

  1. Display a device code and verification URL
  2. Open your browser automatically (or you can manually visit the URL)
  3. Prompt you to enter the device code
  4. Ask you to authorize the application
  5. Store your authentication token securely at ~/.smoothdevio/token.json

The token is stored with secure file permissions (0600) and will automatically refresh when needed.

Check Authentication Status

To verify you're authenticated:

smooth auth mode-show

This shows your current authentication mode (jwt for Auth0 login, api-key for API key authentication).

Logout

To remove your stored credentials:

smooth auth logout

GitHub Token Setup

For commands that interact with GitHub (e.g., --push flag to create/update PRs and releases), you need a GitHub personal access token.

Create a GitHub Token

  1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Click "Generate new token (classic)"
  3. Give it a descriptive name (e.g., "SmoothDev CLI")
  4. Select scopes:
  5. repo (full control of private repositories)
  6. read:org (read organization data, if using org repos)
  7. Click "Generate token"
  8. Copy the token immediately (you won't be able to see it again)

Configure GitHub Token

Set the token as an environment variable:

export GITHUB_TOKEN=ghp_your_token_here

Or add it to your user configuration:

smooth config set github_token ghp_your_token_here

Security Note: If you add the token to your config file, it will be stored at ~/.smoothdevio/config.json with secure permissions. Never commit this file or add tokens to repository config files.

Configuration

The CLI uses a four-tier configuration system for smart defaults. See the Configuration Guide for details.

Quick Configuration

Initialize your user config with common defaults:

smooth config init --owner your-github-username --output text

This creates ~/.smoothdevio/config.json with your preferences.

Verify Setup

Test that everything is working:

# Navigate to a git repository
cd /path/to/your/repo

# Stage some changes
git add .

# Generate a commit message (without committing)
smooth commit generate

If you see a generated commit message, you're all set!

Troubleshooting

"Authentication required" Error

Problem: You see an authentication error when running commands.

Solution: Run smooth auth login to authenticate.

"No staged changes detected" Error

Problem: The commit command can't find changes.

Solution: Make sure you've staged files with git add before running smooth commit generate.

"GitHub token not found" Error

Problem: Commands with --push flag fail.

Solution: Set your GitHub token as described in the GitHub Token Setup section.

Python Version Error

Problem: Installation fails with Python version error.

Solution: Ensure you have Python 3.12 or higher:

python --version

If needed, install Python 3.12+ from python.org.

Permission Denied Error

Problem: Can't write to config directory.

Solution: Ensure ~/.smoothdevio/ directory has correct permissions:

mkdir -p ~/.smoothdevio
chmod 700 ~/.smoothdevio

Next Steps

Getting Help