slim-cli 2.0.0

Automation of the application of software lifecycle best practices to your GitHub repositories

---

SLIM CLI Tool

Automate the application of best practices to your git repositories

SLIM CLI is a command-line tool designed to infuse SLIM best practices seamlessly with your development workflow. It fetches and applies structured SLIM best practices directly into your Git repositories. The tool leverages artificial intelligence capabilities to customize and tailor the application of SLIM best practices based on your repository's specifics.

Website | Docs/Wiki | Discussion Board | Issue Tracker

📺 View demonstration videos and detailed tutorials

Features

• Modern CLI Interface: List, patch, and infuse SLIM best practices into your Git repository workflow using a seamless terminal interface
• Rich Terminal Experience: Colored output with emojis, progress indicators, and interactive commands with dry-run mode support
• Fetches the latest SLIM best practices dynamically from SLIM's registry the moment they change
• Patches and pushes, SLIM best practices to your repository and pushes up to your Git remote (i.e. GitHub) - all automatically
• AI Enabled: 100+ AI models to automatically infuse best practices using AI customization for your repository
• Extensible Architecture: Easy-to-extend best practice system with centralized mapping and YAML configuration

Contents

• Features
• Contents
• Quick Start
  • Requirements
  • Setup Instructions via pip (Recommended for most users)
  • Run Instructions
• Generate Documentation
• Discover and Manage AI Models
• MCP Plugin Integration
• Changelog
• Frequently Asked Questions (FAQ)
• Contributing
  • Setup for Local Development (For Contributors)
  • Running Tests
  • Publishing a New Version
• License
• Support

Quick Start

This guide provides a quick way to get started with our project. Please see our docs for a more comprehensive overview.

Requirements

• Python 3.10+ (recommended for MCP server integration)
• Git
• Optional: LiteLLM for enhanced AI model support (automatically installed with slim-cli)
• Optional: API keys for cloud AI models - if using cloud models, set the appropriate environment variable:

  # Use the slim models setup command to see provider-specific instructions
  slim models setup <provider>
  
  # Example: slim models setup openai
  # Example: slim models setup anthropic
  

• Optional: For local AI models (e.g., Ollama), follow the setup instructions:

  slim models setup ollama
  

Setup Instructions via pip (Recommended for most users)

As the SLIM CLI is written in Python, you'll need Python 3.9 or later. Usually, you'll want to create a virtual environment in order to isolate the dependencies of SLIM from other Python-using applications. Install into that environment using pip:

pip install slim-cli

This installs the latest SLIM CLI and its dependencies from the Python Package Index. The new console script slim is now ready for use. Confirm by running either:

slim --version
slim --help

To upgrade:

pip install --upgrade slim-cli

Or select a specific version, such as X.Y.Z:

pip install slim-cli==X.Y.Z

Run Instructions

The following commands demonstrate the core SLIM CLI functionality. Use slim --help for a complete list of options.

Global Options:

• --version, -v: Show version and exit

• --dry-run, -d: Preview operations without making changes

• --logging, -l: Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

  # Using long form
  slim --logging DEBUG apply --best-practice-ids readme
  
  # Using shorthand
  slim -l DEBUG apply -b readme
  
  # Preview changes without executing (dry run)
  slim -d apply -b readme -r <YOUR_GITHUB_REPO_URL>
  

Command Shorthands

SLIM CLI provides convenient shorthand options for commonly used arguments:

• -b for --best-practice-ids - Specify best practice aliases
• -r for --repo-urls - Specify repository URLs
• -d for --dry-run - Preview changes without applying them
• -l for --logging - Set logging level
• -m for --commit-message - Custom commit message (apply-deploy and deploy commands)

Examples:

# Using full argument names
slim apply --best-practice-ids readme --repo-urls https://github.com/user/repo

# Using shorthands (equivalent)
slim apply -b readme -r https://github.com/user/repo

# Multiple values with shorthands
slim apply -b readme -b governance-small -r https://github.com/org/repo1 -r https://github.com/org/repo2

Available Commands:

1. list - List all available best practices from the SLIM registry

   slim list
   

2. apply - Apply best practices to git repositories

   Key Options:

   • --best-practice-ids, -b: Best practice aliases (required)
   • --repo-urls, -r: Repository URLs (cannot be used with --repo-dir)
   • --repo-dir: Local repository directory [no shorthand]
   • --use-ai: AI model for customization [no shorthand]
   • --output-dir: Output directory (required for docs-website) [no shorthand]

   # Basic usage - clone to temp folder and apply README template
   slim apply --best-practice-ids readme --repo-urls <YOUR_GITHUB_REPO_URL>
   
   # Using shorthand for best-practice-ids and repo-urls
   slim apply -b readme -r <YOUR_GITHUB_REPO_URL>
   
   # Apply multiple best practices (repeat -b for each)
   slim apply -b secrets-github -b secrets-precommit -r <YOUR_GITHUB_REPO_URL>
   
   # Apply with AI customization using cloud model
   slim apply -b readme -r <YOUR_GITHUB_REPO_URL> --use-ai anthropic/claude-3-5-sonnet-20241022
   
   # Apply with local AI model
   slim apply -b readme -r <YOUR_GITHUB_REPO_URL> --use-ai ollama/llama3.1
   
   # Apply to multiple repositories
   slim apply -b readme -r https://github.com/org/repo1 -r https://github.com/org/repo2
   
   # Apply using a list of repositories from a file
   slim apply -b governance-small --repo-urls-file repos.txt
   
   # Generate documentation website
   slim apply -b docs-website -r <YOUR_GITHUB_REPO_URL> --output-dir /path/to/docs-site --use-ai openai/gpt-4o
   

3. apply-deploy - Apply and deploy best practices in one step (creates branch and pushes to remote)

   Key Options:

   • --best-practice-ids, -b: Best practice aliases (required)
   • --commit-message, -m: Custom commit message
   • --remote: Remote name or URL (defaults to 'origin') [no shorthand]
   • --repo-urls, -r: Repository URLs

   # Basic usage
   slim apply-deploy --best-practice-ids readme --repo-urls <YOUR_GITHUB_REPO_URL>
   
   # Using shorthand options
   slim apply-deploy -b readme -r <YOUR_GITHUB_REPO_URL>
   
   # With custom commit message using shorthand
   slim apply-deploy -b readme -r <YOUR_GITHUB_REPO_URL> -m "Add comprehensive README documentation"
   
   # Multiple best practices with shorthand
   slim apply-deploy -b readme -b governance-small -r <YOUR_GITHUB_REPO_URL>
   

4. deploy - Deploy previously applied best practices (commit and push)

   Key Options:

   • --best-practice-ids, -b: Best practice aliases (required)
   • --commit-message, -m: Custom commit message
   • --repo-dir: Repository directory [no shorthand]
   • --remote: Remote name (defaults to 'origin') [no shorthand]

   # Basic usage
   slim deploy --best-practice-ids readme --repo-dir /path/to/repo --remote origin --commit-message "Apply SLIM best practices"
   
   # Using shorthand options
   slim deploy -b readme --repo-dir /path/to/repo -m "Apply SLIM best practices"
   
   # Deploy multiple best practices with shorthand
   slim deploy -b readme -b governance-small --repo-dir /path/to/repo
   

5. models - Discover and configure AI models

   # List all available models
   slim models list
   
   # Get model recommendations for specific tasks
   slim models recommend
   slim models recommend --task documentation --tier premium
   
   # Get setup instructions for a provider
   slim models setup anthropic
   slim models setup openai
   
   # Validate model configuration
   slim models validate openai/gpt-4o
   

Generate Documentation

SLIM CLI can generate comprehensive Docusaurus documentation sites for your repositories using AI.

Basic Usage

# Generate documentation with cloud AI (recommended)
slim apply -b docs-website -r <YOUR_GITHUB_REPO_URL> --output-dir /path/to/docs-site --use-ai openai/gpt-4o

# Generate documentation with local AI
slim apply -b docs-website -r <YOUR_GITHUB_REPO_URL> --output-dir /path/to/docs-site --use-ai ollama/llama3.1

AI Model Recommendations

• Cloud Models (Recommended): openai/gpt-4o, anthropic/claude-3-5-sonnet-20241022, openai/gpt-4o-mini
• Local Models: ollama/llama3.1, ollama/gemma3 (lower quality, not recommended for production)

Use slim models recommend --task documentation to get personalized recommendations.

Generated Content

The documentation generator creates:

• Overview: Project description and features
• Installation: Setup instructions
• API Reference: Auto-generated from source code
• Development: Workflow and coding standards
• Contributing: Guidelines for contributors

Viewing Your Documentation

cd /path/to/output
npm install
npm start  # View at http://localhost:3000

📖 For detailed documentation generation guidance, see the SLIM CLI documentation guide

Discover and Manage AI Models

SLIM CLI supports 100+ AI models through LiteLLM integration. Use the models command to discover, configure, and validate AI models.

# List all available models
slim models list
slim models list --provider anthropic

# Get model recommendations
slim models recommend                              # Default: documentation, balanced
slim models recommend --task documentation --tier premium
slim models recommend --task code_generation --tier fast

# Get setup instructions for providers
slim models setup anthropic
slim models setup openai
slim models setup ollama

# Validate model configuration
slim models validate openai/gpt-4o

Supported Providers

• Cloud Premium: OpenAI, Anthropic Claude, Google Gemini
• Cloud Fast: Groq, Together AI, Cohere, Perplexity
• Local/Private: Ollama, VLLM, LM Studio, GPT4All
• Enterprise: Azure OpenAI, AWS Bedrock, Google Vertex AI

Environment Setup

Use slim models setup <provider> to see provider-specific instructions. Common examples:

# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."

# Ollama (local models) - no API key needed
ollama serve

MCP Plugin Integration

SLIM CLI now includes a Model Context Protocol (MCP) plugin that enables seamless integration with AI coding assistants like Claude Code, Aider, and other MCP-compatible tools. This allows you to apply SLIM best practices directly from within your AI coding environment using natural language.

Key Features

• Natural Language Interface: Apply SLIM best practices using conversational AI commands
• Repository Context Awareness: Automatically analyzes your repository structure and customizes templates
• Real-time Best Practices: Fetches the latest SLIM best practices from the live registry
• AI-Powered Customization: Leverages your AI assistant's capabilities for intelligent template customization

Quick Setup for Claude Code

1. Install SLIM CLI (if not already installed):

   pip install slim-cli
   

2. Add the MCP server to Claude Code:

   # Replace /path/to/slim-cli with your actual SLIM CLI installation directory
   # To find it, run: pip show -f slim-cli | grep Location
   claude mcp add slim-cli -s user -- uvx --directory /path/to/slim-cli --from /path/to/slim-cli python /path/to/slim-cli/src/jpl/slim/mcp/server.py
   

   For development/local installations:

   # If you cloned the SLIM CLI repository locally
   claude mcp add slim-cli -s user -- uvx --directory /Users/yourusername/src/slim-cli --from /Users/yourusername/src/slim-cli python /Users/yourusername/src/slim-cli/src/jpl/slim/mcp/server.py
   

3. Verify connection:

   claude mcp list
   # Should show: slim-cli - ✓ Connected
   

4. Use in Claude Code:

   • Simply ask: "Apply the SLIM readme best practice with AI customization"
   • Or: "List all available SLIM best practices"
   • Or: "Apply governance template to this repository"

Troubleshooting MCP Setup

Finding your SLIM CLI installation path:

# For pip installations
python -c "import jpl.slim; print(jpl.slim.__file__.replace('__init__.py', ''))"

# Or check pip installation location
pip show slim-cli | grep Location

Common issues:

• "Failed to connect": Ensure the paths in the uvx command point to your actual SLIM CLI installation
• "uvx not found": Install uv first: curl -LsSf https://astral.sh/uv/install.sh | sh
• "Module not found": Verify SLIM CLI is installed: pip show slim-cli

Working from any directory: The uvx --directory option ensures the MCP server works regardless of which directory you're running Claude Code from. This is the key advantage over previous methods.

Disconnecting/Removing MCP Server

If you need to disconnect or remove the SLIM CLI MCP server from Claude Code:

# Remove the SLIM CLI MCP server
claude mcp remove slim-cli

# Verify removal
claude mcp list
# Should no longer show slim-cli in the list

Available MCP Tools

• slim_list_all_practices - List all SLIM best practices
• slim_apply_practice_with_ai - Apply practices with AI customization
• slim_analyze_repository_context_tool - Analyze repository context
• slim_fetch_template_content - Fetch templates from registry
• slim_models_recommend - Get AI model recommendations

Documentation

For detailed setup instructions and troubleshooting:

• Installation Guide - Complete MCP server setup
• Integration Guide - Using SLIM with AI assistants
• MCP Documentation - Technical details and API reference

💡 Tip: The MCP plugin works with any MCP-compatible AI assistant, not just Claude Code!

Changelog

See our CHANGELOG.md for a history of our changes.

See our releases page for our key versioned releases.

Frequently Asked Questions (FAQ)

Questions about our project? Please see our: FAQ

Contributing

Interested in contributing to our project? Please see our: CONTRIBUTING.md.

For a detailed understanding of the codebase architecture, including component design, data flow, and extension points, see our ARCHITECTURE.md.

Specifically, see our section on architecture and extensions if you'd like to add support for a new best practice from SLIM or a new command.

For guidance on how to interact with our team, please see our code of conduct located at: CODE_OF_CONDUCT.md

For guidance on our governance approach, including decision-making process and our various roles, please see our governance model at: GOVERNANCE.md

Setup for Local Development (For Contributors)

If you're working on slim-cli itself, you'll want to run it in editable mode so your changes are immediately reflected.

Using UV (Recommended for Development)

UV is a fast Python package manager that simplifies dependency management and virtual environment handling. It's our recommended tool for local development.

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repo
git clone https://github.com/NASA-AMMOS/slim-cli.git
cd slim-cli

# UV automatically creates and manages the virtual environment
# Install all dependencies and the package in editable mode
uv sync

# Run the CLI locally with UV
uv run slim --help
uv run slim --version

# Run tests
uv run pytest tests/

Using Traditional pip/venv

If you prefer the traditional approach:

# Clone the repo
git clone https://github.com/NASA-AMMOS/slim-cli.git
cd slim-cli

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in editable mode
pip install --editable .

# Run the CLI locally
slim --help
slim --version

Use this method if:

• You're adding new features or fixing bugs in the CLI
• You're contributing to the SLIM project
• You want to test changes before publishing

Running Tests

We use pytest for testing. For detailed information about our testing framework, test structure, and how to run tests, please refer to our TESTING.md document.

With UV (Recommended)

# Run all tests
uv run pytest tests/

# Run a specific test file
uv run pytest tests/jpl/slim/test_cli.py

# Run tests with verbose output
uv run pytest -v -s

With Traditional Setup

# Install pytest (if not already installed)
pip install pytest

# Run all tests
pytest

# Run tests with verbose output
pytest -v -s

Publishing a New Version

To publish a new version of SLIM CLI to the Python Package Index, typically you'll update the VERSION.txt file; then do:

pip install build wheel twine
python3 -m build .
twine upload dist/*

(Note: this can and should eventually be automated with GitHub Actions.)

License

See our: LICENSE

Support

Key points of contact are: @riverma and @yunks128