CLI 命令参考

TeleScopeX 提供了简洁而强大的命令行界面。

基本命令

telescopex

启动 TeleScopeX 主程序。

telescopex

别名： tsx

tsx

---

命令选项

--version / -v

显示当前安装的 TeleScopeX 版本号。

telescopex --version
# 或
tsx -v

输出示例：

1.0.0

---

--help / -h

显示帮助信息。

telescopex --help
# 或
tsx -h

输出示例：

TeleScopeX - 智能 CLI 自动化工具套件

使用方法:
  telescopex [选项]
  tsx [选项]

选项:
  -v, --version    显示版本号
  -h, --help       显示帮助信息
  --debug          启用调试模式
  --reset          重置配置

示例:
  telescopex       启动自动认证流程
  tsx              使用简短命令启动
  tsx --debug      调试模式运行

---

--debug

启用调试模式，输出详细的运行日志。

telescopex --debug

用途：

• 排查问题
• 查看详细的执行流程
• 开发和测试

输出示例：

[DEBUG] 查找 .npmrc 文件...
[DEBUG] 找到: /Users/user/project/.npmrc
[DEBUG] Registry: https://npm.company.com/repository/npm-group/
[DEBUG] 检查知识库...
[DEBUG] 已知项目: my-project
[DEBUG] 连接浏览器...
[DEBUG] 浏览器已连接: CDP on http://localhost:9222

---

--reset

重置 TeleScopeX 的所有配置和缓存。

telescopex --reset

操作内容：

• 清空知识库 (knowledge.json)
• 清除浏览器数据 (.browser-data/)
• 重置所有保存的配置

警告

此操作不可逆，会删除所有已保存的项目配置！

确认提示：

⚠️  警告：此操作将删除所有已保存的配置！
你确定要继续吗？ (y/N)

---

--config <path>

指定自定义配置文件路径。

telescopex --config /path/to/custom/config.json

用途：

• 使用自定义知识库
• 多环境配置切换
• 团队配置共享

---

--browser-path <path>

指定 Chrome 浏览器可执行文件路径。

telescopex --browser-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

用途：

• 使用特定版本的 Chrome
• 在非标准安装路径下运行
• 使用 Chromium 或其他兼容浏览器

---

--port <number>

指定远程调试端口。

telescopex --port 9223

默认值： 9222

用途：

• 避免端口冲突
• 连接已运行的特定调试实例

---

--timeout <milliseconds>

设置操作超时时间（毫秒）。

telescopex --timeout 60000

默认值： 30000 (30秒)

用途：

• 网络较慢时增加超时时间
• 快速失败时减少超时时间

---

环境变量

除了命令行选项，TeleScopeX 还支持通过环境变量进行配置：

TELESCOPEX_BROWSER_PATH

Chrome 浏览器路径。

export TELESCOPEX_BROWSER_PATH="/usr/bin/chromium"
telescopex

---

TELESCOPEX_DEBUG_PORT

远程调试端口。

export TELESCOPEX_DEBUG_PORT=9223
telescopex

---

TELESCOPEX_TIMEOUT

操作超时时间。

export TELESCOPEX_TIMEOUT=45000
telescopex

---

TELESCOPEX_CONFIG_PATH

配置文件路径。

export TELESCOPEX_CONFIG_PATH="/path/to/config.json"
telescopex

---

退出代码

TeleScopeX 使用标准退出代码表示运行状态：

代码	含义	描述
0	成功	操作成功完成
1	一般错误	未分类的错误
2	配置错误	配置文件或参数错误
3	浏览器错误	无法启动或连接浏览器
4	认证失败	npm login 失败
5	网络错误	网络连接问题
130	用户中断	用户按 Ctrl+C 中断

示例：

telescopex
echo $?  # 显示退出代码

---

使用示例

基本使用

# 在项目目录中运行
cd my-project
telescopex

调试问题

# 启用调试输出
telescopex --debug

# 增加超时时间
telescopex --timeout 60000

自定义配置

# 使用自定义浏览器
telescopex --browser-path "/usr/bin/chromium"

# 使用自定义端口
telescopex --port 9223

# 使用自定义配置文件
telescopex --config ./team-config.json

NPM Scripts 集成

在 package.json 中：

{
  "scripts": {
    "auth": "telescopex",
    "auth:debug": "telescopex --debug",
    "auth:reset": "telescopex --reset"
  }
}

然后运行：

npm run auth
npm run auth:debug
npm run auth:reset

---

配置文件

knowledge.json

知识库配置文件，自动生成。

位置： 项目根目录 knowledge.json

结构：

{
  "projects": [
    {
      "name": "project-name",
      "registry": "https://npm.company.com/...",
      "timestamp": "2025-12-01T10:30:00.000Z"
    }
  ]
}

字段说明：

• name - 项目名称
• registry - npm registry URL
• timestamp - 最后更新时间

---

故障排除

命令未找到

telescopex: command not found

解决方案：

1. 确保已全局安装：npm install -g telescopex
2. 检查 npm bin 路径是否在 PATH 中：npm bin -g
3. 重新加载 shell 配置：source ~/.zshrc 或 source ~/.bashrc

浏览器无法启动

Error: Failed to launch browser

解决方案：

1. 确保已安装 Chrome 浏览器
2. 使用 --browser-path 指定浏览器路径
3. 检查是否有权限启动浏览器

端口已被占用

Error: Port 9222 is already in use

解决方案：

1. 使用其他端口：telescopex --port 9223
2. 关闭占用 9222 端口的进程
3. TeleScopeX 会自动连接现有的调试实例

---

下一步

• 📖 查看 功能介绍 了解更多功能
• 📝 阅读 快速开始 快速上手
• 💬 提交反馈 报告问题