Frequently Asked Questions

Axle is a modular CLI platform for running Python microtools from a shared tools directory. It provides:

• Built-in security validation before executing any tool
• Automatic tool discovery - just drop Python files in your tools directory
• Simple numbered command system for easy tool execution
• Dependency vulnerability scanning
• Built-in SEO and productivity tools

Think of it as a platform where anyone can add tools without modifying core code.

The easiest way is to install directly from GitHub:

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

For manual installation, see the documentation.

• Python: 3.10 or higher
• RAM: 8GB minimum (16GB recommended)
• Disk Space: 5-8GB free for ML models and dependencies
• Operating System: macOS, Linux, or Windows

You can run tools by number or by name:

# Run by number
axle run 1 "your prompt"

# Run by name
axle run seo_keyword_checker "your prompt"

Use axle list to see all available tools with their numbers.

Axle comes with built-in tools:

• SEO Keyword Checker: Analyze text for keyword density and optimization
• Meta Tag Auditor: Analyze HTML/webpages for meta tag completeness
• Daily Life Hack Generator: Generate personalized productivity tips

Plus, you can easily add your own tools!

Before ANY tool executes, Axle scans it for:

• Dangerous patterns (eval, exec, compile, __import__)
• Hardcoded secrets (API keys, passwords, tokens)
• Unsafe imports (pickle, marshal)
• Subprocess calls with shell=True

If issues are found, execution is blocked based on your security policy.

There are three security policies:

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

Set the policy with:

export AXLE_SECURITY_POLICY=strict

Automatic code review is a feature that helps you maintain high code quality by checking your tools for common issues before they reach CI/CD pipelines. It runs automatically during tool execution and can fix many issues for you.

The system checks for:

• Formatting issues: Code style problems (auto-fixable)
• Import issues: Import statement ordering (auto-fixable)
• Linting issues: Code quality problems (selectively auto-fixable)
• Complexity issues: High code complexity (report only)

Issues are categorized by severity: 🔴 CRITICAL, 🟠 HIGH, 🟡 MEDIUM, 🟢 LOW

Axle provides several 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

Code review also runs automatically during tool execution in "auto" mode (the default).

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)

The system includes safety features like backup creation and validation to ensure fixes don't break your code.

You can configure code review behavior using environment variables:

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

# Automatically fix issues without asking
export AXLE_AUTO_FIX=false

# Enable detailed output
export AXLE_CODE_REVIEW_VERBOSE=false

Recommended settings:

• New users: AXLE_AUTO_FIX=true for seamless experience
• Development: AXLE_CODE_REVIEW=auto to review changed files
• CI/CD: AXLE_CODE_REVIEW=always to fail on any issues

Adding tools is easy!

1. Find your tools directory: axle path
2. Create a Python file (e.g., 04_my_tool.py)
3. Implement two functions:

   def get_description() -> str:
       return "Brief description"
   
   def main(prompt: str) -> None:
       # Your logic here
       pass

4. Run it: axle run my_tool "prompt"

That's it! No changes to core code required.

Absolutely! Simply share your Python file and others can drop it into their tools directory. We also welcome contributions to the main repository. Check out our community page for details on contributing.

Here are a few tools source:

• Agentic AIO: A collection of tools developed by Agentic AIO, Here is the Facebook Group.
• Community Tools: Tools shared by the community on our Facebook Group and GitHub
• Custom Tools: Your own tools that you create for your specific needs

You can mix and match tools from different sources seamlessly.

Use the built-in update command:

# Update to latest version
axle update

# Check for updates without installing
axle update --check

The update command will:

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

Safety features:

• ✅ Detects uncommitted changes and stops
• ✅ Shows exactly what will be updated
• ✅ Provides instructions to stash/commit changes

The update command includes safety checks and will stop if you have uncommitted changes:

⚠️  You have uncommitted changes:
 M CLAUDE.md
 M README.md
 M axle/axle.py

💡 Please commit or stash your changes before updating.
   git stash
   axle update
   git stash pop

This prevents accidental data loss. You can either:

1. Commit your changes - Recommended if you want to keep them
2. Stash your changes - Temporarily save changes, update, then restore
3. Discard changes - If you don't need them anymore

The tool metadata system helps you discover and explore tools without reading source code. It extracts and caches information about:

• 📝 Function names and signatures
• 🔧 Parameters with type annotations
• 🏗️ Class definitions and methods
• 📦 Import statements and dependencies
• 📄 Docstrings and documentation
• ✅ Tool contract compliance (get_description, main)

Common commands:

axle metadata scan      # Build metadata cache
axle metadata list      # List all tools
axle metadata show  # Show tool details
axle metadata search  # Search tools

Use the metadata search command to find tools by name, function, or description:

# Search by keyword
axle metadata search keyword

# Search by function name
axle metadata search extract

# Search by description
axle metadata search "meta tag"

The search matches against:

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

Example output:

🔍 Search Results for 'keyword':
📋 01_seo_keyword_checker
   Analyze text for SEO keyword density...
   Matching functions: extract_keywords

Starting with v1.2.0, security validation and code review are disabled by default for better performance:

• ⚡ 66% faster tool execution (~150ms → ~50ms)
• 🎯 Better experience for trusted tools
• 🔧 User choice - enable when needed

To enable them:

# Per-run (one time)
axle run 1 "prompt" --security --code-review

# Persistent (all runs)
axle security --enable
axle review --enable

Configuration storage: Settings are stored in ~/.axle/config.json for persistent configuration across sessions.

Use the enable commands to persistently activate security and code review:

# Enable security validation by default
axle security --enable

# Enable code review by default
axle review --enable

# Check current configuration
axle security --show
axle review --show

Configuration file:

# View config file
cat ~/.axle/config.json

# Example output:
{
  "security": "enabled",
  "code_review": "enabled"
}

To disable, use the disable commands: axle security --disable or axle review --disable.

Try these solutions:

1. Verify installation: pip show axle-cli
2. Try with Python: python -m axle.axle list
3. Reinstall: pip install -e .
4. Check your PATH includes pip scripts directory

Your tool was blocked by the security policy. You'll see a message explaining why. Options:

• Fix the security issue in your tool
• Use a more permissive policy: export AXLE_SECURITY_POLICY=permissive
• Override for one command: AXLE_SECURITY_POLICY=permissive axle run tool

We welcome contributions! Here's how:

• Report bugs: Open an issue on GitHub
• Suggest features: Start a discussion or issue
• Add tools: Create a pull request with your tool
• Improve docs: Submit documentation updates
• Fix bugs: Submit a pull request

See the contributing guide for details.

Depending on how you want to contribute:

• Adding tools: Basic Python knowledge
• Fixing bugs: Python development skills
• Documentation: Good writing skills
• Testing: Attention to detail

Everyone can contribute! Even reporting bugs helps immensely.