Tools Alias CLI

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

特性

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

安装

使用 uv

uv pip install tools-alias-cli

使用 pip

pip install tools-alias-cli

配置

配置文件

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

配置目录定制

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

# 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 格式，结构如下：

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

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

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

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

配置选项

环境变量 ([ENV])

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

工具定义 ([[tool]])

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

使用方法

基本命令

# 列出所有可用工具
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：列出所有工具

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

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

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

示例 3：执行工具

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

示例 4：带参数执行工具

$ tools-alias-cli 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（用于开发）

设置开发环境

# 安装依赖
uv install

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

# 运行测试
uv run python -m pytest

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

# 构建包
uv build

许可证

Apache License 2.0