cli

HeadlessX CLI

HeadlessX CLI 是一个命令行工具，用于让智能体通过已发布的 headlessx 命令来操作 HeadlessX，而不是直接调用文件或 API。规范命令为 headlessx。

主要能力与用途

• 提供 headlessx 作为规范命令，覆盖操作符（operator）级命令与路由。
• 支持本地工作区的引导与管理，工作区位于 ~/.headlessx 下。
• 支持认证流程，使用 HeadlessX API 凭据。
• 支持网站抓取、映射（map）和爬取（crawl）。
• 支持 Google AI Search 标志。
• 提供 Tavily、Exa、YouTube、jobs 及 operators 等示例命令模式。
• 支持将输出写入文件，格式包括 markdown 与 JSON。

安装与验证

全局安装：

npm install -g @headlessx-cli/core

安装后验证：

headlessx --help

快速开始

引导本地工作区：

headlessx init

更新现有工作区：

headlessx init update headlessx restart headlessx logs --tail 200 --no-follow

认证工作流

仅使用 HeadlessX API 凭据。推荐使用：

headlessx login

当可进行交互式输入时，headlessx init 和 headlessx login 会使用引导式的现代提示。

如果用户已经拥有两个值，可使用标志：

headlessx login --api-key your_headlessx_api_key --api-url http://localhost:38473

如果希望会话保持非交互式，可使用环境变量。参见 references/auth-and-output.md。

输出规则

• 面向大模型使用时，优先使用默认的 markdown/文本输出。
• 仅在明确需要结构化、机器可读输出时使用 --json。

命令模式

在组合多步 CLI 运行前，请先阅读 references/command-matrix.md。其中包含：

• 生命周期引导命令
• 网站抓取、映射和爬取示例
• Google AI Search 标志
• Tavily、Exa、YouTube、jobs 和 operators 示例
• markdown 与 JSON 的文件输出模式

参考文档

• references/command-matrix.md：按操作符逐项列出的命令。
• references/auth-and-output.md：认证优先级和输出规则。
• references/operator-routes.md：当前以操作符优先的 API 映射。

确定性验证

运行以下脚本以验证安装、认证界面和核心帮助输出：

scripts/smoke_cli.py

发布与安装

当前包：

@headlessx-cli/core

全局安装：

npm install -g @headlessx-cli/core

从本仓库发布的流程：

cd /home/saifyxpro/CODE/Crawl/HeadlessX/packages/cli npm login pnpm type-check pnpm build npm publish --access public

适用场景与限制

适用场景：智能体需要以命令行方式驱动 HeadlessX，进行工作区引导、认证、抓取、映射、爬取及各类检索操作；需要文本或 JSON 输出；需要可脚本化、可重复的验证流程。

注意事项：

• CLI 可以在 ~/.headlessx 下引导和管理本地 HeadlessX 工作区，而操作符命令仍然与 HeadlessX API 通信。
• 如果后端使用 apps/api/data 下的持久浏览器配置文件，CLI 请求会共享该后端状态，因为它们通过同一个 API 实例。
• 当用户要求“测试 CLI”时，优先运行：

headlessx --help headlessx init --help headlessx login --help headlessx status headlessx doctor headlessx logs --no-follow

以及操作符特定的帮助或 smoke 命令。

• 需要快速、确定性的基线时，使用 scripts/smoke_cli.py。

关于收费、价格、平台或效果等更多事实，资料暂未提供。