Configuration

Customize CLI behavior with .wseng configuration files at personal and project levels.

Configuration Files

The CLI uses JSON configuration files stored in two locations:

Personal Configuration

Location: ~/.wseng (your home directory)

This file contains your user-specific settings that apply across all projects:

• awsProfile: Default AWS profile to use
• emailAddress: Your work email address
• localPaths: Where your repositories are cloned
• commandConfigurations: User-specific command defaults
• extensionVersions: VSCode extension versions
• obsSettings: OBS Studio settings for demo recording

Project Configuration

Location: .wseng (in each project root directory)

This file contains project-specific settings:

• contextFolder: Where context files are stored (default: .context)
• specs: List of spec documents to pull
• pullRequestTemplate: PR template using Handlebars syntax
• commandConfigurations: Project-specific command defaults
• stagingBranch: Staging branch name for the project

Creating Configuration Files

Run wseng init in any repository to create/update configuration files:

cd /path/to/your/project
wseng init

What this creates:

• Personal config at ~/.wseng (if it doesn't exist)
• Project config at .wseng in the current directory
• Context folder (typically .context/)

You can run wseng init multiple times. It updates existing configs without losing custom settings.

Command Configurations

Both personal and project configs support commandConfigurations to set default parameter values for any command.

Structure

{
  "commandConfigurations": {
    "command-name": {
      "defaultInputs": {
        "parameterName": value
      }
    }
  }
}

Example: Personal Configuration

Configure start-ticket to always use current branch as base:

{
    "awsProfile": "wseng-dev",
    "emailAddress": "you@trilogy.com",
    "localPaths": ["/Users/you/code"],
    "commandConfigurations": {
        "start-ticket": {
            "defaultInputs": {
                "currentBranchAsBase": true
            }
        }
    }
}

Now wseng start-ticket LAMBDA-12345 automatically uses your current branch as the base instead of main.

Example: Project Configuration

Configure commit command for a specific project:

{
    "contextFolder": ".context",
    "stagingBranch": "staging",
    "commandConfigurations": {
        "commit": {
            "defaultInputs": {
                "push": false,
                "check": true
            }
        }
    }
}

Now commits in this project won't auto-push and will run pre-commit checks.

Configuration Precedence

When the CLI looks up a parameter value:

1. Explicit command-line argument (highest priority)
2. Project configuration (.wseng in project root)
3. Personal configuration (~/.wseng in home directory)
4. Command default (defined in CLI code)

Example

# Project config sets: "currentBranchAsBase": true
# Personal config sets: "currentBranchAsBase": false

# This uses project config (true)
wseng start-ticket LAMBDA-12345

# This overrides everything (false)
wseng start-ticket LAMBDA-12345 --no-current-branch-as-base

Model Selection for Large Diffs (infer-breakdown)

When using the infer-breakdown command on tickets with large PR diffs, you may need to use a model with a larger context window. The CLI will automatically detect if your input is too large and suggest alternatives.

Available Models by Context Window

Using a Specific Model

Command line:

# Claude with 1M context (via Bedrock)
wseng --model claude-4-5-sonnet ws infer-breakdown TICKET-123

# Gemini with 1M context
wseng --model gemini-pro ws infer-breakdown TICKET-123
wseng --model gemini-2.5-pro ws infer-breakdown TICKET-123

Configuration file (~/.wseng):

{
    "model": "gemini-pro"
}

Token Limit Errors

If your input exceeds the model's context window, the CLI will:

1. Stop before making the API call
2. Show the estimated token count vs. model's context window
3. Suggest models with larger context windows (1M tokens)

Model Tracking

The model_used field in the estimation YAML output records which model was used for inference, helping with reproducibility and debugging.

Default Model

The default model is claude-4-5-sonnet which has a 1M token context window via AWS Bedrock.

Common Configuration Patterns

Always Stage Changes Before Commit

Personal ~/.wseng:

{
    "commandConfigurations": {
        "commit": {
            "defaultInputs": {
                "stage": true
            }
        }
    }
}

Skip Git Sync for Fast Workflows

Personal ~/.wseng:

{
    "commandConfigurations": {
        "start-ticket": {
            "defaultInputs": {
                "gitSync": false
            }
        }
    }
}

Custom Context Folder Location

Project .wseng:

{
    "contextFolder": "docs/context"
}

Configure Multiple Commands

Personal ~/.wseng:

{
    "commandConfigurations": {
        "commit": {
            "defaultInputs": {
                "push": true,
                "stage": true
            }
        },
        "start-ticket": {
            "defaultInputs": {
                "clearContext": true,
                "gitSync": true
            }
        },
        "review-work": {
            "defaultInputs": {
                "includeSubtasks": true
            }
        }
    }
}

Disabling Personal Defaults

Sometimes you want to ignore personal configuration for a single command:

wseng commit --no-personal-defaults

This uses only project config and CLI defaults, skipping your personal commandConfigurations.

Interactive Configuration

Instead of manually editing JSON, use the interactive configuration command:

wseng ws configure-command-defaults <command-name> --scope personal
# or
wseng ws configure-command-defaults <command-name> --scope project

Example:

wseng ws configure-command-defaults commit --scope personal

This opens an interactive prompt for each parameter where you can:

• Skip (keep current value)
• Set/modify default value
• Remove default (if one exists)

The CLI validates your inputs and updates the appropriate config file automatically.

Common Configuration Issues

❌ Bad: Invalid JSON syntax

{
    "commandConfigurations": {
        "commit": {
            "defaultInputs": {
                "push": true // Comments not allowed in JSON!
            }
        }
    }
}

Solution: Use a JSON validator. No trailing commas, no comments.

❌ Bad: Wrong parameter names

{
    "commandConfigurations": {
        "commit": {
            "defaultInputs": {
                "autoPush": true // Wrong! Parameter is "push"
            }
        }
    }
}

Solution: Check command help for exact parameter names:

wseng commit --help

❌ Bad: Wrong value types

{
    "commandConfigurations": {
        "commit": {
            "defaultInputs": {
                "push": "true" // Wrong! Should be boolean true, not string "true"
            }
        }
    }
}

Solution: Use correct JSON types: true/false for booleans, numbers without quotes, strings with quotes.

Configuration Files in Git

✅ Good: Commit project config

git add .wseng
git commit -m "chore: add project configuration"

Project .wseng files should be committed so all team members share project defaults.

❌ Bad: Commit personal config

Never commit ~/.wseng to Git. It's user-specific and lives outside repositories.

✅ Good: Document project config

Add comments to your PR when changing project .wseng:

Updated project config:
- Disabled auto-push for commits (requires explicit push)
- Enabled pre-commit checks by default

Related Docs

Configuration Reference

Auto-generated reference for .wseng configuration file properties.

Command Reference

See all available commands and their configurable parameters.