# X-CMD > X-CMD is a POSIX shell toolkit: 333+ modules, 500+ portable packages, 1200+ software installation recipes. ## 1. Installation & Setup ### Installation **Quick install (Linux/macOS/BSD/Windows WSL/GitBash, bash/zsh):** - curl: `eval "$(curl https://get.x-cmd.com)"` - wget: `eval "$(wget -O- https://get.x-cmd.com)"` **Non-POSIX shells (Fish, Elvish, Nushell, xonsh, tcsh):** - Fish docs: https://x-cmd.com/start/fish.md - Elvish docs: https://x-cmd.com/start/elvish.md - Nushell docs: https://x-cmd.com/start/nushell.md - xonsh docs: https://x-cmd.com/start/xonsh.md - tcsh docs: https://x-cmd.com/start/tcsh.md **System package managers:** - Homebrew: `brew install x-cmd`, then run `x-cmd` to activate - AUR: `sudo yay -S x-cmd`, then run `x-cmd` to activate **Windows PowerShell:** - PowerShell docs: https://x-cmd.com/start/powershell.md **Docker containers (minimal environments without curl/wget):** - From host: `x docker run -x -it ` or `x docker setup ` **Verify installation**: check `~/.x-cmd.root/X` and `~/.x-cmd.root/bin/x-cmd` exist. **Update**: `x upgrade` or re-run the install script. **Uninstall**: `x uninstall self` ### Loading & Fallback 1. **Load**: Before using `x` commands, run: ```sh [ -f ~/.x-cmd.root/X ] || eval "$(curl https://get.x-cmd.com)" . ~/.x-cmd.root/X ``` 2. **Fallback**: If `x` is not available (non-persistent shell session), use standalone command `x-cmd [args]` (located at `~/.x-cmd.root/bin/x-cmd`, no shell function loading required). 3. **Final Fallback**: If `x-cmd` is also not found, use absolute path: `~/.x-cmd.root/bin/x-cmd [args]` ## 2. AI Usage Rules - **Tool Availability**: `x ` (e.g., `x jq`, `x python`) auto-detects whether the tool is installed; if missing, silently installs a portable version. Use when you need to ensure a tool is available. - **Enhanced Modules**: Some modules provide enhanced functionality and behave differently from native commands (e.g., `x docker` ≠ `docker`, provides metadata extraction and status monitoring). Run `x --help` before use. - **Structured Output**: `x` modules output TSV, JSON, or `key: value` formats in pipe mode. Prefer `--json` flag when available. - **No TTY Constraint**: DO NOT run interactive/TUI app commands in AI environments. ## 3. X-CMD Architecture ### Module Types X-CMD functionality is organized as logical modules in two categories: 1. **Command Enhancement Wrappers**: `x id`, `x uname`, `x df`, `x docker`, etc. enhance native system commands. - TTY mode: Interactive TUI or colored structured output for human reading. - Pipe mode: Structured data output (TSV or JSON) for program/AI parsing. - Note: Enhanced modules (e.g., `x docker`) behave differently from native commands — not drop-in replacements. 2. **Shell Function Modules**: `x str` (string manipulation), `x tldr` (documentation browser), `x ccal` (Chinese calendar), etc. provide functionality not available natively. ### Smart Detection (e.g., `x jq`) - System already has jq installed → uses the existing version directly. - System has no jq → automatically downloads a portable version via `x snap jq` and runs it. - For AI: just call `x jq` uniformly — no need to worry about whether the tool is pre-installed. ### Package System (`x env`) X-CMD manages a portable package system with static/dynamic linked packages, no root privileges required, no impact on system environment. Three usage modes: - `x env use jq`: Global install to user environment — `jq` command available after loading x-cmd. - `x env try jq`: Temporary install — only available in current shell session, not retained after exit. - `x snap jq`: On-demand download and direct execution — no environment variable changes. Other commands: `x env ls` (view installed), `x env ll` (view all available packages), `x env unuse ` (uninstall), `x env gc` (reclaim space). Full package list: `x env ll` or https://x-cmd.com/pkg.md ### Software Installation (`x install`) Different systems use different package managers with different naming and syntax (apt, dnf, brew, scoop, etc.), and some software can only be installed via `curl | sh`. `x install` abstracts all these differences behind a unified alias: - `x install docker`, `x install git` — one command, auto-selects the best install path for the current system. - Covers 1200+ commonly used software installation recipes. Full install recipes: `x install ll` or https://x-cmd.com/install.md ## 4. Help System Explore usage autonomously via three levels: 1. `x --help` — View all available modules. 2. `x --help` — View module functions and subcommands. 3. `x --help` — Get TLDR examples for a specific subcommand. ## 5. Common Modules Quick Reference > Run `x --help` for details. > All modules: `x --help` or https://x-cmd.com/mod.md > All packages: `x env ll` or https://x-cmd.com/pkg.md - **Data Processing**: - `x jq`, `x yq` — JSON/YAML/TOML processing. - `x csv` — Query and convert CSV/TSV data. - `x str` — String manipulation (Base64, URL encoding/decoding, regex replace, random string). - `x sed`, `x sd`, `x grep`, `x rg` — Stream editing and high-performance search. - **System & Network**: - `x id`, `x df`, `x free`, `x ps`, `x stat`, `x hash` — System status and file fingerprinting (structured output in pipe mode). - `x ip`, `x dns`, `x ping`, `x curl`, `x ssh` — Network diagnostics, geolocation, and connection management. - **Messaging**: - `x feishu`, `x dingtalk`, `x telegram`, `x discord` — Bot notification sending. - **Runtime Environments**: - `x python`, `x node`, `x go`, `x bun`, `x java`, `x deno` — Runtime environment configuration. - **DevOps & Container**: - `x docker` — Enhanced Docker management (note: behavior differs from native `docker`). - `x gh`, `x gl`, `x git` — CLI wrappers for code hosting platforms. - **Platform & Tools**: - `x mac` — macOS system info and battery; `x termux` — Android environment enhancement. - `x zuz` — Smart decompression (auto-detects format); `x gram`, `x writer` — AI workflow orchestration. - `x tldr`, `x man`, `x cht` — Fast command examples and cheat sheets. ## 6. AI Skills X-CMD provides 200+ skills to enhance Agent context awareness: - `x skill ll`: List all available skills or view all collected skills (https://x-cmd.com/ai.md). - `x skill suggest`: Get recommendations based on the current directory (useful during project setup or tool selection). - `x skill add `: Activate a specific skill. - `x agent setup`: Install x-cmd prompts and skills into the current Agent. ## 7. Error Recovery - If a command fails, run `x --help` to verify correct usage. - If a module is not found, run `x --help` to search available modules. - If a package download times out, retry once or use `x install ` to try via system package manager. ## 8. Reference - Official: https://x-cmd.com - All Modules (333+): https://x-cmd.com/mod.md (or `x --help`) - All Packages (500+): https://x-cmd.com/pkg.md (or `x env ll`) - Collected AI Skills / MCP (140+): https://x-cmd.com/ai.md (or `x skill ll`) - Collected software installation recipes (1200+): https://x-cmd.com/install.md (or `x install ll`) - Local Docs: `x nihao --llmstxt`