# tools-alias-cli

**Repository Path**: riag/tools-alias-cli

## Basic Information

- **Project Name**: tools-alias-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-10
- **Last Updated**: 2025-12-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tools Alias CLI

一个用于管理和运行自定义工具别名的命令行工具，支持环境变量配置。

## 特性

- 📋 **工具管理**：定义自定义工具，包含名称、命令和帮助信息
- 🌍 **环境变量**：从配置文件加载环境变量，并支持用户路径展开
- 📝 **字符串模板**：在工具命令中使用 `${VARIABLE}` 语法引用环境变量
- 🎯 **动态子命令**：工具可作为直接子命令使用
- 📖 **帮助系统**：内置 help 命令，支持工具特定的帮助信息
- 📦 **易于安装**：通过 pip 或 uv 安装
- 📂 **配置目录定制**：通过 TOOLS_ALIAS_DIR 环境变量自定义配置目录位置

## 安装

### 使用 uv

```bash
uv pip install tools-alias-cli
```

### 使用 pip

```bash
pip install tools-alias-cli
```

## 配置

### 配置文件

默认情况下，工具会在 `~/.tools-alias/config.toml` 查找配置文件。

### 配置目录定制

你可以通过环境变量 `TOOLS_ALIAS_DIR` 来指定配置文件所在的目录：

```bash
# Linux/Mac
TOOLS_ALIAS_DIR="~/my-tools-alias" tools-alias-cli list

# Windows
set TOOLS_ALIAS_DIR="C:\\my-tools-alias" && tools-alias-cli list
```

如果未设置该环境变量，工具会自动将 `TOOLS_ALIAS_DIR` 设置为默认目录 `~/.tools-alias` 的绝对路径。

### 配置格式

配置文件使用 TOML 格式，结构如下：

```toml
# 环境变量（可选）
[ENV]
HOME_PATH = "~/my-tools"
CONFIG_PATH = "~/.config/tools-alias"
USER = "myuser"

# 工具定义（必填）
[[tool]]
name = "show-home"
command = "echo ${HOME_PATH}"
short_help = "显示用户主目录"
help = "显示展开后的主目录路径"
help_command = "--help"

[[tool]]
name = "list-files"
command = "ls -la"
short_help = "列出当前目录文件"

[[tool]]
name = "grep-pattern"
command = "grep ${PATTERN} *.py"
short_help = "在 Python 文件中搜索模式"
```

### 配置选项

#### 环境变量 (`[ENV]`)

- 定义可用于所有工具命令的环境变量
- 值可以包含用户路径展开（`~` 会被替换为用户主目录）
- 配置文件中的环境变量会覆盖系统环境变量

#### 工具定义 (`[[tool]]`)

- **name**：工具的唯一标识符（必填）
- **command**：要执行的命令（必填）
- **short_help**：帮助输出中显示的简短描述（可选）
- **help**：详细帮助文本（可选）
- **help_command**：使用 `help` 命令时执行的帮助命令（可选）

## 使用方法

### 基本命令

```bash
# 列出所有可用工具
tools-alias-cli list

# 显示特定工具的帮助信息
tools-alias-cli help show-home

# 显示所有工具的帮助信息
tools-alias-cli help

# 使用 run 命令执行工具
tools-alias-cli run show-home

# 直接作为子命令执行工具
tools-alias-cli show-home
```

### 示例

#### 示例 1：列出所有工具

```bash
$ tools-alias-cli list
工具别名列表:
  show-home -> echo C:\Users\user/my-tools ( 显示用户主目录 )
  list-files -> ls -la ( 列出当前目录文件 )
  grep-pattern -> grep ${PATTERN} *.py ( 在 Python 文件中搜索模式 )
```

#### 示例 2：显示所有工具的帮助信息

```bash
$ tools-alias-cli help
所有工具别名:
  show-home - 显示用户主目录
  list-files - 列出当前目录文件
  grep-pattern - 在 Python 文件中搜索模式
```

#### 示例 3：执行工具

```bash
$ tools-alias-cli show-home
执行命令: echo C:\Users\user/my-tools 
C:\Users\user/my-tools
```

#### 示例 4：带参数执行工具

```bash
$ tools-alias-cli run grep-pattern "import"
执行命令: grep import *.py 
__init__.py:import argparse
__init__.py:import os
__init__.py:import sys
__init__.py:from string import Template
__init__.py:from typing import Dict, List, Optional
# 处理 Python 3.10 兼容性
__init__.py:if sys.version_info >= (3, 11):
__init__.py:    import tomllib
__init__.py:else:
__init__.py:    import tomli as tomllib
```

## 环境变量展开

工具支持两种类型的环境变量处理：

1. **用户路径展开**：环境变量中的 `~` 会被替换为用户的主目录
2. **字符串模板**：命令中的 `${VARIABLE}` 会被替换为对应的环境变量值

## 开发

### 要求

- Python 3.10+
- uv（用于开发）

### 设置开发环境

```bash
# 安装依赖
uv install

# 以开发模式安装
uv install -e .

# 运行测试
uv run python -m pytest

# 运行类型检查
uv run mypy src/

# 构建包
uv build
```

## 许可证

Apache License 2.0