Installation

Method 1: Install from GitHub (Recommended)

pip install git+https://github.com/skpaul82/axle-cli.git

Method 2: Manual Installation

# Clone the repository
git clone https://github.com/skpaul82/axle-cli.git
cd axle-cli

# Install dependencies
pip install -r requirements.txt

# Install the package
pip install -e .

System Requirements

  • Python 3.10 or higher
  • 8GB RAM minimum (16GB recommended)
  • 5-8GB free disk space
  • macOS, Linux, or Windows
💡 Pro Tip: Use a virtual environment to avoid conflicts with other Python packages.

Quick Start

After installation, you can immediately start using Axle:

1. Check Your Version

axle -V

2. List Available Tools

axle list

3. Run a Tool

# Run by number
axle run 1 "your prompt"

# Run by name
axle run seo_keyword_checker "your prompt"

4. Get Tool Information

axle info seo_keyword_checker

5. Check Your Environment

axle doctor

Commands Reference

axle -V, --version

Show the Axle version number.

axle -V

axle list

List all available tools in the tools directory.

axle list

axle run <tool> [prompt] [--security] [--code-review]

Execute a tool by number or name. Optionally enable security validation or code review for this run.

# By number
axle run 1 "your prompt"

# By name
axle run seo_keyword_checker "your prompt"

# With security validation
axle run 1 "your prompt" --security

# With code review
axle run 1 "your prompt" --code-review

# With both
axle run 1 "your prompt" --security --code-review

axle info <tool_name>

Show detailed information about a specific tool.

axle info seo_keyword_checker

axle scan

Run security vulnerability scan on dependencies and scripts.

axle scan

axle doctor

Run environment diagnostics to check system setup.

axle doctor

axle path

Show the current tools folder location.

axle path

axle security [--policy <policy>] [--enable] [--disable] [--show]

Show or configure security policy and settings.

# Show current policy and configuration
axle security

# Set security policy
axle security --policy strict

# Enable security by default
axle security --enable

# Disable security by default
axle security --disable

# Show current configuration
axle security --show

axle review <tool> [--all] [--fix] [--dry-run] [--verbose] [--enable] [--disable] [--show]

Run code review on tools or configure code review settings.

# Review a specific tool
axle review my_tool

# Review all tools
axle review --all

# Review with automatic fixes
axle review my_tool --fix

# Preview changes without applying
axle review my_tool --fix --dry-run

# Detailed output
axle review my_tool --verbose

# Enable code review by default
axle review --enable

# Disable code review by default
axle review --disable

# Show current configuration
axle review --show

axle update [--check]

Update Axle CLI to the latest version from GitHub.

# Update to latest version
axle update

# Check for updates without installing
axle update --check

axle metadata scan | list | show <tool> | search <query>

Manage and explore tool metadata.

# Scan all tools and build metadata cache
axle metadata scan

# List all tools with summaries
axle metadata list

# Show detailed metadata for a tool
axle metadata show 01_seo_keyword_checker

# Search tools by name, function, or description
axle metadata search keyword
axle metadata search "meta tag"

axle uninstall [--keep-tools] [--remove-tools]

Uninstall Axle CLI.

# Preserve tools directory (default)
axle uninstall

# Remove tools directory
axle uninstall --remove-tools

axle help

Show help message and all available commands.

axle help

Adding Your Own Tools

Axle is designed as a platform for tools - you can easily add your own Python scripts!

1. Find Your Tools Directory

axle path

2. Create a New Python File

# Example: tools/04_my_tool.py

3. Implement the Required Functions

def get_description() -> str:
    """Return one-line description of the tool."""
    return "Brief description of what your tool does"

def main(prompt: str) -> None:
    """Main entry point. Called by CLI router."""
    # Your tool logic here
    print(f"Processing: {prompt}")

4. Run Your Tool

axle list              # Your tool appears in the list
axle run 4 "your prompt"  # Run by number
axle run my_tool "your prompt"  # Run by name

Tool Requirements

  • ✅ Must implement get_description() function (returns string)
  • ✅ Must implement main(prompt: str) function (no return value)
  • ✅ File must be valid Python 3.10+
  • ✅ Optional: Use numeric prefix for ordering (e.g., 04_my_tool.py)
⚠️ Security Note: All tools are validated for security issues before execution. Dangerous patterns like eval(), exec(), and shell=True will be blocked unless you override the security policy.

Security (Optional)

Axle includes optional security validation that can run BEFORE executing any tool. Security validation is disabled by default for better performance.

Enabling Security Validation

Per-run (enable for one execution):

axle run 1 "prompt" --security

Persistent (enable for all runs):

axle security --enable

Disable persistent setting:

axle security --disable

What Gets Checked

  • Dangerous patterns (eval, exec, compile, __import__)
  • Hardcoded secrets (API keys, passwords, tokens)
  • Unsafe imports (pickle, marshal, subprocess with shell=True)
  • File operations that could be dangerous

Security Policies

  • strict: Blocks ALL security findings
  • warn: Blocks only CRITICAL findings, warns on others
  • permissive (default): Blocks only CRITICAL/HIGH findings

Setting Security Policy

# Environment variable
export AXLE_SECURITY_POLICY=strict

# Or set via command
axle security --policy strict
⚠️ Important: Security validation is disabled by default in v1.2.0. Enable it with axle security --enable or use --security flag per run.
💡 Best Practice: Use "strict" mode for production environments and "permissive" mode for development. Enable security when working with untrusted tools.

Automatic Code Review (Optional)

Axle includes optional automatic code review that can run AFTER security validation to help you maintain high code quality. Code review is disabled by default for better performance.

Enabling Code Review

Per-run (enable for one execution):

axle run 1 "prompt" --code-review

Persistent (enable for all runs):

axle review --enable

Disable persistent setting:

axle review --disable

What Gets Checked

  • Formatting: Black code style issues (auto-fixable)
  • Imports: isort import sorting issues (auto-fixable)
  • Linting: flake8 code quality issues (selectively auto-fixable)
  • Complexity: High complexity warnings (report only)

Issue Severity Levels

  • 🔴 CRITICAL: Syntax errors, undefined names (must fix)
  • 🟠 HIGH: Major issues that should be fixed
  • 🟡 MEDIUM: Important but not blocking
  • 🟢 LOW: Minor issues (style, unused imports, etc.)

Automatic vs Manual Fixes

Auto-fixable issues:

  • ✅ Black formatting (all code style issues)
  • ✅ isort imports (import statement ordering)
  • ✅ Unused imports and variables (safe to remove)

Manual fixes needed:

  • ❌ Syntax errors and undefined names
  • ❌ Line length issues (may require code restructuring)
  • ❌ High complexity (requires refactoring)

Code Review Commands

# Review a specific tool
axle review my_tool

# Review all tools
axle review --all

# Review with automatic fixes
axle review my_tool --fix

# Preview changes without applying
axle review my_tool --fix --dry-run

# Detailed output
axle review my_tool --verbose

Configuration Options

# When to run code review: always, auto, or never (default)
export AXLE_CODE_REVIEW=auto

# Automatically fix issues without asking
export AXLE_AUTO_FIX=false

# Enable detailed output
export AXLE_CODE_REVIEW_VERBOSE=false
⚠️ Important: Code review is disabled by default in v1.2.0. Enable it with axle review --enable or use --code-review flag per run.
💡 Pro Tip: For development, enable code review persistently to catch issues early: axle review --enable

Update Command

Axle includes a built-in update command to keep your CLI up-to-date with the latest features and bug fixes from GitHub.

Updating Axle CLI

# Update to the latest version
axle update

This will:

  1. Fetch the latest changes from GitHub
  2. Pull updates from the origin/main branch
  3. Update dependencies from requirements.txt
  4. Reinstall the package (pip install -e .)
  5. Show the new version number

Checking for Updates

# Check if updates are available without installing
axle update --check

Safety Features

The update command includes safety checks to prevent data loss:

  • ✅ Detects uncommitted changes and stops
  • ✅ Shows exactly what will be updated
  • ✅ Provides instructions to stash/commit changes
  • ✅ Timeout protection for network operations

Requirements

  • Must be in a git repository
  • No uncommitted changes (or must be committed first)
  • Internet connection for fetching updates
💡 Tip: Run axle update --check first to see if updates are available without installing them.

Tool Metadata System

The tool metadata system helps you discover, explore, and understand tools without reading the source code. Metadata includes function signatures, parameters, imports, and documentation.

Scanning Tools

# Scan all tools and build metadata cache
axle metadata scan

This analyzes all Python files in your tools directory and extracts:

  • Function names and signatures
  • Parameters with type annotations
  • Class definitions and methods
  • Import statements
  • Docstrings and documentation
  • Tool contract compliance (get_description, main)

Listing Tools

# List all tools with summaries
axle metadata list

Shows a concise overview of all tools including:

  • Tool name and status
  • Description
  • Function and class counts
  • Contract compliance status

Viewing Tool Details

# Show detailed metadata for a specific tool
axle metadata show 01_seo_keyword_checker

Displays comprehensive information about a tool:

  • File path, size, and last modified date
  • Tool contract status
  • Description from get_description()
  • Module and function docstrings
  • Complete function signatures with parameters
  • All imports and dependencies

Searching Tools

# Search by tool name, function name, or description
axle metadata search keyword
axle metadata search "meta tag"
axle metadata search extract

Search matches against:

  • Tool names
  • Function names
  • Descriptions and docstrings
  • Class names

Metadata Cache

Metadata is cached in ~/.axle/metadata/tools_metadata.json for instant lookups. Rescan with axle metadata scan after adding or modifying tools.

💡 Use Case: Perfect for discovering what tools are available and understanding their capabilities without reading through source code.

Troubleshooting

"Command not found: axle"

Cause: The installation may not have set up the command properly.

Solutions:

  1. Make sure you ran pip install -e .
  2. Check your PATH includes the pip scripts directory
  3. Try running with python: python -m axle.axle list
  4. Check the package is installed: pip show axle-cli

"Tools directory not found"

Cause: The tools directory doesn't exist yet.

Solution: Axle will automatically create the tools directory during installation. If it's missing, you can create it manually:

mkdir -p $(axle path | grep -o '/.*')

Tool execution blocked

Cause: Security policy blocked the tool.

Solution: Review the security findings and either fix the tool or use a more permissive policy:

export AXLE_SECURITY_POLICY=permissive
axle run your_tool "prompt"

Need More Help?