
# Using x-cmd as tools in terminal and agents ( claude-code, codex, gemini-cli )

NOTICE: You can always get this file from https://www.x-cmd.com/llms.txt

## X-CMD Overview

X-CMD is an efficient POSIX shell library that enhances command-line experience with 333+ modules across various categories.

**Key Features:**
- **Modular Architecture**: Functions organized as logical modules for specific tasks
- **Enhanced Commands**: Interactive TUI and structured output for existing commands
- **Package Management**: Portable package system with three usage modes
- **Cross-Platform**: Works on Linux, macOS, Windows, BSD, and mobile platforms
- **Multi-Shell Support**: Compatible with bash, zsh, nushell, powershell, and more
- **Smart Detection**: Prefers existing system binaries, falls back to portable packages

**Synopsis:**
```bash
# As shell library (recommended)
x <module> [subcommand] [args...]

# As external command
x-cmd <module> [subcommand] [args...]
```

**Getting Help:**
Almost all x-cmd help is accessed through:
- `x <module> --help` - Get help for a specific module
- `x <module> [subcommand] --help` - Get help for module subcommands

## X-CMD Architecture

### Modules
X-CMD functions are organized as logical modules:

1. **Command Enhancement Wrappers**:
   - `x id`, `x uname`, `x df` enhance `id`, `uname`, `df`
   - **TTY**: Interactive TUI or colored structured output for easy reading
   - **Piped**: Structured data (TSV or JSON) for machine processing
   - **Bigger commands**: `x docker` provides enhanced Docker with interactive TUI tables
   - **NOTICE**: `x docker` differs from `docker` - not a drop-in replacement

2. **Shell Function Modules**:
   - `x ccal`: Chinese calendar TUI
   - `x tldr`: TLDR-PAGES documentation with fzf-based TUI
   - `x str`: String manipulation utilities

### Package System
X-CMD manages a portable package system with static/dynamic linked packages that don't require root privileges or affect system setup (no sudo required):

**Three Usage Modes:**
- `x env use jq`: Install in user scope, available after x-cmd load
- `x env try jq`: Download on-demand, add to PATH only in current session
- `x snap jq`: Download x-cmd pkg jq on-demand, use directly

**Smart Detection Example (`x jq`):**
- Uses existing jq binary if available (system-wide or user-installed)
- Falls back to `x snap jq` if no jq found
- Enhances jq with interactivity features

### Software Installation
`x install` module simplifies software installation:

**Core Philosophy**: Make installation simple, fast, and reliable

**Addresses Pain Points:**
- Inconsistent package names across managers (apt, dnf, apk, brew, asdf, scoop, winget, chocolatey)
- Complex one-liner commands (e.g., `curl -fsSL https://get.docker.com | sh`)

**Features:**
- Cataloged 1229+ commonly used software packages
- Turns complex one-liners into simple aliases
- Intelligent command recommendations based on environment
- Reduces errors and improves efficiency

## Installation & Usage

### Installation
**Check installation**: Verify `~/.x-cmd.root/X` and `~/.x-cmd.root/bin/x-cmd` exist

**Install methods**:
- **Linux/macOS/BSD**: `eval "$(curl https://get.x-cmd.com)"`
- **Windows**: Download https://get.x-cmd.com/x-cmd.bat and run
- **System packages**: Available via system package managers (apt, brew, etc.)

**Installation location**: Installs to `~/.x-cmd.root` folder

### Invocation
**As shell library** (recommended):
- Add to shell config (~/.bashrc, ~/.zshrc): `[ ! -f "$HOME/.x-cmd.root/X" ] || . "$HOME/.x-cmd.root/X"`
- After loading, use: `x id`, `x ping`, `x docker ps`

**As external command**:
- Direct: `~/.x-cmd.root/bin/x-cmd id`
- With PATH: Add `$HOME/.x-cmd.root/bin` to PATH, then use `x-cmd id`

### Usage Examples
- `x id` - Enhanced system/user information
- `x ping` - Better ping with statistics
- `x docker ps` - Interactive Docker container list

## Function Categories

**System Information**:
- `x id`, `x uname`, `x df` - Enhanced system commands
- `x mac info`, `x mac battery` - macOS-specific utilities
- `x termux` - Android/Termux utilities

**Package Management**:
- `x pkg` - Access 500+ CLI tools
- `x env use`, `x env try`, `x snap` - Package usage modes

**Software Installation**:
- `x install` - Simplified software installation

**Interactive Tools**:
- `x docker` - Enhanced Docker with TUI
- `x tldr` - Documentation browser
- `x ccal` - Chinese calendar TUI

**Development Utilities**:
- `x str` - String manipulation
- Basic shell/awk encapsulation functions

**AI/LLM Integration**:
- Direct command-line access to AI models
- Scriptable AI interactions

## Reference
- **Official Documentation**: https://www.x-cmd.com
- **Installation Guide**: https://www.x-cmd.com/install/get-started
- **Module Reference**: https://www.x-cmd.com/mod
- **Package Catalog**: https://www.x-cmd.com/pkg
