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
Using config.toml (Recommended)
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):
- Command-line flags (
--provider,--api-key,--model,--api-url) - Environment variables (
XAW_PROVIDER,XAW_API_KEY,XAW_MODEL,XAW_API_URL) - Config file (
~/.config/clixaw/config.toml) - 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-confirmto 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, andX-Modelheaders
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.