Skip to main content

clixaw

A command-line interface tool that translates natural language queries into executable shell commands using the cmd.xaw.me API.

Installation

From PyPI (when published)

pip install xaw

From source

git clone https://github.com/Bandit-HaxUnit/clixaw
cd clixaw
pip install -e .

Usage

Basic Usage

Translate a natural language query to a shell command:

xaw show me big files
# Output: du -ah . | sort -rh | head -n 10

Quoted Queries

For multi-word queries with special characters, use quotes:

xaw "git push new branch"
# Output: git push -u origin $(git branch --show-current)

Execute Commands

Use the --execute or -e flag to execute the translated command:

xaw --execute list files in current directory
# Executes: ls -la

Configuration

Create a configuration file at ~/.config/clixaw/config.toml:

[api]
# Optional: Custom API URL (defaults to https://cmd.xaw.me)
url = "https://cmd.xaw.me"

[provider]
# Optional: Provider name (e.g., "openai", "gemini")
# If not specified, uses default (Groq) - no headers needed
name = "openai"

# Optional: API key (required if provider is set)
api_key = "sk-xxx"

# Optional: Model override (e.g., "gemini-pro", "gpt-4")
model = "gemini-pro"

Using Environment Variables

Set configuration using environment variables:

export XAW_API_URL="http://localhost:8000"
export XAW_PROVIDER="openai"
export XAW_API_KEY="sk-xxx"
export XAW_MODEL="gpt-4"
xaw show files

Using Command-Line Flags

Override configuration via command-line flags:

xaw --api-url http://localhost:8000 --provider openai --api-key sk-xxx --model gpt-4 show files

Configuration Priority

Configuration values are resolved in the following order (highest to lowest priority):

  1. Command-line flags (--provider, --api-key, --model, --api-url)
  2. Environment variables (XAW_PROVIDER, XAW_API_KEY, XAW_MODEL, XAW_API_URL)
  3. Config file (~/.config/clixaw/config.toml)
  4. Defaults (Groq provider, no headers needed)

Safety Features

By default, clixaw only prints commands without executing them. When using --execute:

  • Dangerous commands (like rm -rf, format, etc.) require confirmation
  • Use --no-confirm to skip confirmation (use with caution)
xaw --execute remove all files
# Warning: This command may be dangerous!
# Command: rm -rf *
# Do you want to proceed? [y/N]:

Command-Line Options

Usage: xaw [OPTIONS] QUERY...

  Translate natural language queries to shell commands using cmd.xaw.me API.

Options:
  -e, --execute          Execute the translated command instead of just printing it
  --api-url TEXT         API URL (defaults to XAW_API_URL env var, config file, or https://cmd.xaw.me)
  --provider TEXT        Provider name (e.g., openai, gemini). Overrides config file and env var.
  --api-key TEXT         API key for custom provider. Overrides config file and env var.
  --model TEXT           Model override (e.g., gemini-pro, gpt-4). Overrides config file and env var.
  --no-confirm           Skip confirmation for dangerous commands (use with caution)
  --version              Show the version and exit
  --help                 Show this message and exit

Examples

# Find large files
xaw show me big files

# Git operations
xaw "git push new branch"
xaw "create a new git branch"

# File operations
xaw list all python files
xaw find files modified today

# System information
xaw show disk usage
xaw check network connections

# Execute commands
xaw --execute show current directory
xaw -e "list files sorted by size"

API Details

  • Base URL: https://cmd.xaw.me (configurable)
  • Endpoints:
    • GET /?q={query} (query parameter style, preferred)
    • GET /{query} (path-based)
  • Response: Plain text shell command
  • Authentication: None required for default provider (Groq)
  • Custom Providers: Use X-Provider, X-API-Key, and X-Model headers

Provider Examples

# Default (Groq) - no headers needed
xaw "show big files"

# Custom provider with API key (via config.toml or flags)
xaw --provider openai --api-key sk-xxx "show big files"

# With custom model override
xaw --provider gemini --api-key xxx --model gemini-pro "show big files"

Error Handling

The tool handles various error scenarios:

  • Network connection errors
  • API timeouts
  • HTTP errors from the API
  • Invalid or empty responses
  • Command execution errors

Development

Project Structure

clixaw/
├── clixaw/
│   ├── __init__.py
│   ├── cli.py          # Main CLI entry point
│   └── api.py          # API client module
├── pyproject.toml      # Package configuration
├── README.md
└── requirements.txt

Running Tests

pytest

Code Formatting

black clixaw/

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Metadata

Release files for xaw 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xaw 0.1.1
File Size Uploaded Provenance Actions
xaw-0.1.1.tar.gz 15.0 kB Without provenance Details for xaw-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xaw 0.1.1
File Interpreter ABI Platform Actions
xaw-0.1.1-py3-none-any.whl Python 3 none any Details for xaw-0.1.1-py3-none-any.whl

Total release size: 29.5 kB

Release files / xaw-0.1.1.tar.gz

Download URL xaw-0.1.1.tar.gz
Size 15.0 kB
Tags Source
SHA-256 checksum
How to use checksums
5e3e404b80ec08583712fe732c520000d3453f7345d9755c6c8e3afa1ffedd61
BLAKE2b-256 checksum
How to use checksums
767a0feba7c7a9be0b46b13f92b56d6163a71f4e2b4c8a4aa7e44b3cbeb4d713
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Release files / xaw-0.1.1-py3-none-any.whl

Download URL xaw-0.1.1-py3-none-any.whl
Size 14.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3b5e1ab6ab3f0f74c2450f0a7042bf0833e44098976745d786619c3f291d5987
BLAKE2b-256 checksum
How to use checksums
26eb8f0f33a270092d6e91bb1550de86bc15512de61ca08bc41bfc619854efd5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Security for xaw 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page