Configuration Guide

Learn how to configure the SmoothDev CLI for smart defaults and optimal workflow.

Overview

The SmoothDev CLI uses a four-tier configuration precedence system that automatically resolves settings from multiple sources. This eliminates the need to specify the same flags repeatedly while maintaining flexibility for overrides.

Four-Tier Precedence

Settings are resolved in this order (highest to lowest priority):

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

Example:

# Without configuration - requires all flags
smooth pr generate --owner my-org --repo my-repo --pr-number 42 --output text

# With smart defaults - auto-detected!
smooth pr generate  # On branch "pr-42" in a git repo

This reduces required flags by 80% while maintaining full control when needed.

Configuration Files

User Config

Location: ~/.smoothdevio/config.json

Purpose: Personal defaults that apply across all repositories

Scope: User-specific settings (not committed to repositories)

Example:

{
  "github_token": "ghp_your_token_here",
  "defaults": {
    "owner": "my-github-username",
    "output": "text",
    "verbose": false
  }
}

Repository Config

Location: .smoothdev.json (in repository root)

Purpose: Team settings shared across all contributors

Scope: Repository-specific settings (committed to git)

Example:

{
  "owner": "my-org",
  "repo": "my-repo",
  "defaults": {
    "output": "text",
    "verbose": false
  }
}

Security Note: Repository config cannot contain credentials like github_token to prevent accidental commits of sensitive data.

Configuration Commands

Initialize Configuration

Create a new configuration file with defaults:

# Initialize user config
smooth config init --owner my-org --output text

# Initialize repository config
smooth config init --scope repo --owner my-org --repo my-repo

View Configuration

Display current configuration settings:

# Show all configurations
smooth config show

# Show only user config
smooth config show --scope user

# Show only repository config
smooth config show --scope repo

# Show as JSON
smooth config show --format json

Example Output (Text):

📁 User Configuration
   Location: /Users/username/.smoothdevio/config.json

   github_token: ghp_****
   defaults.owner: my-org
   defaults.output: text
   defaults.verbose: false

📦 Repository Configuration
   Location: .smoothdev.json

   owner: my-org
   repo: my-repo
   defaults.output: text

Get Specific Value

Retrieve a single configuration value:

# Get user's default owner
smooth config get defaults.owner

# Get repo's output format
smooth config get defaults.output --scope repo

# Get GitHub token (masked)
smooth config get github_token

Set Configuration Value

Update a configuration value:

# Set default owner (user config)
smooth config set defaults.owner my-org

# Set output format (repo config)
smooth config set defaults.output json --scope repo

# Set GitHub token
smooth config set github_token ghp_your_token_here

# Set verbose mode
smooth config set defaults.verbose true

Show Config File Path

Display the path to configuration files:

# Show user config path
smooth config path
# Output: /Users/username/.smoothdevio/config.json

# Show repo config path
smooth config path --scope repo
# Output: /path/to/repo/.smoothdev.json

Git Context Auto-Detection

The CLI automatically detects context from your git repository:

Owner and Repository

Detected from git remote URLs:

# Git remote: git@github.com:smoothdev-io/my-repo.git
# Auto-detects: owner=smoothdev-io, repo=my-repo

# Git remote: https://github.com/smoothdev-io/my-repo.git
# Auto-detects: owner=smoothdev-io, repo=my-repo

Supported Remote Formats:

• SSH: git@github.com:owner/repo.git
• HTTPS: https://github.com/owner/repo.git
• Git: git://github.com/owner/repo.git

PR Number

Detected from branch names:

# Branch: pr-42        → PR #42
# Branch: 42-feature   → PR #42
# Branch: feature-pr-42 → PR #42

Supported Patterns:

• pr-<number>
• <number>-<description>
• <description>-pr-<number>

Tags

Detected for release notes:

# Automatically finds latest two tags
# Tags: v1.0.0, v1.1.0, v1.2.0
# Auto-detects: from=v1.1.0, to=v1.2.0

Current Branch

Detected from git HEAD:

# Current branch: feature/add-auth
# Auto-detects: branch=feature/add-auth

Configuration Options

Available Settings

Setting	Description	Scope	Default
owner	GitHub owner/organization	User, Repo	None
repo	GitHub repository name	Repo	None
github_token	GitHub personal access token	User only	None
defaults.output	Output format (text or json)	User, Repo	text
defaults.verbose	Enable verbose mode	User, Repo	false

Setting Paths

Use dot notation to access nested settings:

# Top-level setting
smooth config get owner

# Nested setting
smooth config get defaults.output
smooth config get defaults.verbose

Precedence Examples

Example 1: Owner Detection

Scenario: Determine GitHub owner for a command

Sources:

1. CLI Flag: --owner cli-org
2. Git Context: git-org (from remote)
3. Repo Config: repo-org
4. User Config: user-org

Resolution: cli-org (CLI flag has highest priority)

Example 2: Output Format

Scenario: Determine output format

Sources:

1. CLI Flag: (not specified)
2. Git Context: (not applicable)
3. Repo Config: json
4. User Config: text

Resolution: json (repo config overrides user config)

Example 3: PR Number

Scenario: Determine PR number

Sources:

1. CLI Flag: (not specified)
2. Git Context: 42 (from branch pr-42)
3. Repo Config: (not applicable)
4. User Config: (not applicable)

Resolution: 42 (git context auto-detected)

Example 4: Verbose Mode

Scenario: Determine if verbose mode is enabled

Sources:

1. CLI Flag: --verbose
2. Git Context: (not applicable)
3. Repo Config: false
4. User Config: true

Resolution: true (CLI flag overrides all)

Verbose Mode

Enable verbose mode to see where configuration values come from:

smooth pr generate --pr-number 42 --verbose

Output:

📋 Context Resolution:
  owner: smoothdev-io (from git remote)
  repo: my-repo (from git remote)
  pr_number: 42 (from CLI flag)
  output: text (from user config)
  verbose: true (from CLI flag)

Fetching PR data from GitHub...
Generating PR title...
Generating PR summary...

This helps debug configuration issues and understand where values are coming from.

Common Configurations

Personal Developer Setup

For individual developers working across multiple repositories:

User Config (~/.smoothdevio/config.json):

{
  "github_token": "ghp_your_token_here",
  "defaults": {
    "owner": "my-username",
    "output": "text",
    "verbose": false
  }
}

Benefits:

• GitHub token stored securely
• Default owner set to your username
• Consistent output format across repos

Team Repository Setup

For teams sharing configuration:

Repository Config (.smoothdev.json):

{
  "owner": "company-org",
  "repo": "product-repo",
  "defaults": {
    "output": "json",
    "verbose": false
  }
}

Benefits:

• Team-wide owner/repo settings
• Consistent output format for CI/CD
• Committed to git for all contributors

CI/CD Setup

For automated pipelines:

Environment Variables:

export GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}

Command:

# All context auto-detected from git
smooth pr generate --pr-number $PR_NUMBER --push

Benefits:

• Secrets managed by CI/CD platform
• No config files needed
• Auto-detection from git context

Security Best Practices

Protecting Credentials

1. Never commit tokens - Keep github_token in user config only
2. Use environment variables - For CI/CD and shared environments
3. Secure file permissions - Config files are created with 0600 permissions
4. Rotate tokens regularly - Update tokens periodically

File Permissions

Config files are automatically created with secure permissions:

# User config
chmod 600 ~/.smoothdevio/config.json

# Repository config (safe to commit)
chmod 644 .smoothdev.json

Token Storage

GitHub tokens are stored in user config with restricted permissions:

# View permissions
ls -la ~/.smoothdevio/config.json
# Output: -rw------- 1 user group 256 Nov 15 10:00 config.json

Troubleshooting

"Could not find config file"

Problem: Config file doesn't exist.

Solution:

# Initialize user config
smooth config init --owner my-org

# Or create manually
mkdir -p ~/.smoothdevio
echo '{"defaults": {}}' > ~/.smoothdevio/config.json

"Permission denied" when writing config

Problem: Can't write to config directory.

Solution:

# Fix permissions
mkdir -p ~/.smoothdevio
chmod 700 ~/.smoothdevio

"Invalid JSON in config file"

Problem: Config file has syntax errors.

Solution:

# Validate JSON
cat ~/.smoothdevio/config.json | python -m json.tool

# Or recreate
smooth config init --owner my-org

Config not being applied

Problem: Settings don't seem to take effect.

Solution:

1. Check precedence - CLI flags override config
2. Verify scope - ensure setting is in correct config file
3. Use verbose mode to see resolution:

smooth pr generate --verbose

"Cannot set github_token in repo config"

Problem: Trying to add token to repository config.

Solution:

# Use user config instead
smooth config set github_token ghp_your_token_here

# Or set environment variable
export GITHUB_TOKEN=ghp_your_token_here

Migration Guide

From No Config to User Config

# Before: Specify flags every time
smooth pr generate --owner my-org --repo my-repo --pr-number 42

# Setup: Initialize user config
smooth config init --owner my-org

# After: Auto-detected!
smooth pr generate --pr-number 42

From User Config to Repo Config

# Create repo config with team settings
smooth config init --scope repo --owner company-org --repo product-repo

# Commit to git
git add .smoothdev.json
git commit -m "chore: add smoothdev config"
git push

From Environment Variables to Config

# Before: Set environment variable
export GITHUB_TOKEN=ghp_your_token_here

# After: Store in user config
smooth config set github_token ghp_your_token_here

Advanced Usage

Multiple Profiles

Use different configs for different contexts:

# Work profile
smooth config set defaults.owner work-org
smooth pr generate  # Uses work-org

# Personal profile
smooth config set defaults.owner personal-username
smooth pr generate  # Uses personal-username

Config Validation

Validate configuration before using:

# Show all configs
smooth config show --format json | python -m json.tool

Backup and Restore

Backup your configuration:

# Backup user config
cp ~/.smoothdevio/config.json ~/.smoothdevio/config.json.backup

# Restore from backup
cp ~/.smoothdevio/config.json.backup ~/.smoothdevio/config.json

See Also

• CLI Reference - Complete command reference
• Installation Guide - Setup and installation
• Commit Messages - Generate commit messages
• Pull Requests - Generate PR documentation
• Release Notes - Generate release notes