System Requirements

• Python 3.10 or higher
• pip 26.0 or higher
• 8GB RAM minimum (16GB recommended)
• 5-8GB free disk space
• macOS, Linux, or Windows

Step-by-step guide to install or upgrade Python and pip.

Installation

Method 1: Install from GitHub (Recommended)

If pip is not working then check your pip version:

pip -V

If you have Python 3 installed, try using pip3:

pip3 -V

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 .

Quick Start

After installation, you can immediately start using Axle:

0. Check Your Version

axle -V

1. Launch Interactive Mode (Beta)

axle

No arguments — an arrow-key scrollable tool picker appears. Navigate with ↑↓ or j/k, press Enter to select, type your args, and run.

2. List All Available Tools

axle list

3. Run a Tool Directly by Name or Number

# By tool name
axle competitor_analysis --urls https://rival.com --target-keyword "web developer"

# By number
axle 4 --urls https://rival.com --target-keyword "web developer"

4. See a Tool's Usage Examples

# Type tool name with no args — shows its examples
axle content_optimizer
axle 3

5. Check Your Environment

axle doctor

Adding Your Own Tools

Drop any Python script into your tools directory and run it immediately. No contract required — Axle auto-discovers the tool type.

1. Find Your Tools Directory

axle path

2. Choose a Tool Type

Axle supports three tool types. All are discovered automatically.

Type A — Argparse Tool (recommended for new tools)

Standard Python script with argparse and a main(args) function. Axle passes CLI flags straight through.

"""
My Tool — does something useful.

Usage:
    python my_tool.py --input file.txt --output result.json
    python my_tool.py --input file.txt --verbose
"""
import argparse

def main(args=None):
    parser = argparse.ArgumentParser(description="My tool")
    parser.add_argument("--input", required=True, help="Input file")
    parser.add_argument("--output", default="result.json", help="Output file")
    parser.add_argument("--verbose", action="store_true")
    parsed = parser.parse_args(args)
    # tool logic here
    print(f"Processing {parsed.input}")

# Run it directly
axle my_tool --input data.txt --output out.json

# See usage examples (from the docstring Usage: block)
axle my_tool

Type B — Contract Tool (simple prompt-based)

Implements get_description() and main(prompt: str). Best for tools that take a single text input.

def get_description() -> str:
    return "Brief description of what this tool does"

def main(prompt: str) -> None:
    # Your tool logic here
    print(f"Processing: {prompt}")

# Run it
axle my_contract_tool "your input text here"

Type C — Multi-function Script

Any Python script with multiple top-level functions. Call specific functions by name.

def analyze(text):
    """Analyze the given text."""
    print(f"Analyzing: {text}")

def summarize(url):
    """Fetch and summarize a URL."""
    print(f"Summarizing: {url}")

# List functions
axle my_script

# Call a specific function
axle my_script analyze "some text to analyze"
axle my_script summarize https://example.com

3. Run Your Tool

axle list              # Your tool appears in the list
axle my_tool           # See its usage examples
axle my_tool --flags   # Run it directly

Tips

• ✅ Use numeric prefix for ordering (e.g., 04_my_tool.py)
• ✅ Add a Usage: block in your module docstring for auto-extracted examples
• ✅ No core code changes needed — just drop the file and run
• ✅ File must be valid Python 3.10+

Interactive Mode

Run axle with no arguments in a terminal to launch the interactive arrow-key picker.

axle

Navigation

• ↑ / k — move up
• ↓ / j — move down
• Enter — select tool
• q / Esc / Ctrl+C — cancel and exit

After Selecting a Tool

Axle shows the tool type and prompts for arguments context-aware:

• Argparse tools — shows usage example, prompts for flags. Leave blank to see --help.
• Contract tools — prompts for a free-text prompt string.
• Multi-function tools — lists available functions, prompts for [function] [args].

Before running, Axle echoes the full command so you can see exactly what will execute:

Running: axle competitor_analysis --urls https://rival.com --target-keyword "cloud hosting"

Direct Execution

In v1.3.0, you can run any tool directly without the axle run prefix — just pass the tool name or number followed by its flags.

By Tool Name

axle competitor_analysis --urls https://rival.com --target-keyword "cloud hosting"
axle content_optimizer --file article.html --target-keyword "SaaS"
axle seo_keyword_checker "my keyword phrase"

By Tool Number

axle 4 --urls https://rival.com --target-keyword "cloud hosting"
axle 3 --file article.html --target-keyword "SaaS"
axle 1 "my keyword phrase"

Flags Pass Through Unchanged

All flags are forwarded directly to the tool. Axle does not intercept or modify them.

Per-Tool Usage Examples

Running a tool name or number with no arguments shows that tool's own usage examples instead of erroring.

axle competitor_analysis
axle 4

Example output:

competitor_analysis — Analyze competitor websites for SEO insights

📌 Examples:
  axle competitor_analysis  --urls https://comp1.com --target-keyword "cloud hosting"
  axle competitor_analysis  --files comp1.html --target-keyword "crm software"

Run with --details for full options.

How Examples Are Extracted

Axle reads the Usage: block from each tool's module docstring and automatically converts python tool_name.py --args format into axle tool_name --args format.

Full Options with --details

axle help competitor_analysis --details

This shows the complete argparse help (all flags, types, defaults) plus a list of available functions.

Commands Reference

axle (no arguments)

Launches the interactive arrow-key tool picker when run in a real terminal (TTY). In a non-TTY context (pipes, scripts), shows the tool list and usage tip.

axle

axle <tool_name> or axle <N> (no further args)

Shows the tool's own usage examples and a one-line summary. Does not run the tool.

axle competitor_analysis
axle content_optimizer
axle 4

axle <tool_name> [flags...] or axle <N> [flags...]

Runs the tool directly. All flags are forwarded to the tool unchanged.

# Argparse tools — pass flags directly
axle competitor_analysis --urls https://rival.com --target-keyword "cloud hosting"
axle content_optimizer --file article.html --target-keyword "SaaS"

# Contract tools — pass prompt as positional argument
axle seo_keyword_checker "my keyword phrase"

# By number
axle 4 --urls https://rival.com --target-keyword "cloud hosting"
axle 1 "my keyword phrase"

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

Legacy execution syntax — still works. Optionally enable security validation or code review per run.

# By number
axle run 1 "your prompt"

# By name
axle run seo_keyword_checker "your prompt"

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

axle help [<tool>] [--details / -d]

Show general help or per-tool help. Default shows name, summary, and examples. Use --details for full argparse options and function list.

# General help
axle help

# Tool help (summary + examples)
axle help competitor_analysis

# Full details (all flags + functions)
axle help competitor_analysis --details
axle help 4 --details

axle list

List all available tools in the tools directory with numbers and descriptions.

axle list

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 -V, --version

Show the Axle version number.

axle -V

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

Show or configure security policy and settings.

# Enable security by default
axle security --enable

# Disable security by default
axle security --disable

# Show current configuration
axle security --show

# Set security policy
axle security --policy strict

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

Run code review on tools or configure code review settings.

# Enable code review by default
axle review --enable

# Disable code review by default
axle review --disable

# Review a specific tool
axle review my_tool

# Review with automatic fixes
axle review my_tool --fix

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

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 competitor_analysis

# 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

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

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

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

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.

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?

• Check the FAQ page
• Search GitHub Issues
• Join our community

🎬 Video Tutorial

Watch Axle in action — see adding your own tools, interactive mode, direct execution, and per-tool examples.

Watch on YouTube