mcpField
C
cli

cli

github.com/saifyxproDevelopment2.3k55 installsUpdated 2w ago
Repository

About cli

A command-line skill for using HeadlessX through the `headlessx` command. It covers workspace setup and maintenance, authentication, and operator commands, with guidance for text and JSON output.

Key features

  1. 01Bootstraps and updates a local workspace
  2. 02Guides API-key authentication
  3. 03Runs lifecycle and operator commands
  4. 04Supports text and JSON output
  5. 05Includes CLI smoke-test guidance

Use cases

  1. 01Setting up or updating a HeadlessX workspace
  2. 02Authenticating to the HeadlessX API
  3. 03Running website scrape, map, or crawl commands
  4. 04Checking CLI health and logs

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/saifyxpro/headlessx --skill cli

After installing, type/cliin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
auth-and-output.md
command-matrix.md
operator-routes.md
scripts/
smoke_cli.py

Details

From the project README

HeadlessX CLI

Use headlessx as the canonical command.

For full command families and route coverage, read:

  • references/command-matrix.md for operator-by-operator commands
  • references/auth-and-output.md for auth precedence and output rules
  • references/operator-routes.md for the current operator-first API mapping

For deterministic validation, run:

  • scripts/smoke_cli.py to verify install, auth surface, and core help output

Quick Start

Install and verify:

npm install -g @headlessx-cli/core
headlessx --help

Bootstrap a local workspace:

headlessx init

Update an existing workspace:

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

Authentication Workflow

Use HeadlessX API credentials only. Prefer:

headlessx login

The CLI now uses guided modern prompts for headlessx init and headlessx login when interactive input is available.

Use flags when the user already has both values:

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

Use environment variables when the session should stay non-interactive. See references/auth-and-output.md.

Output Rules

Prefer the default markdown/text output for LLM-facing use.

Use --json only when structured machine-readable output is specifically needed.

Command Patterns

Read references/command-matrix.md before composing multi-step CLI runs. It contains:

  • lifecycle bootstrap commands
  • website scrape, map, and crawl examples
  • Google AI Search flags
  • Tavily, Exa, YouTube, jobs, and operators examples
  • file output patterns for markdown and JSON

Publishing And Install

Current package:

  • @headlessx-cli/core

Global install:

npm install -g @headlessx-cli/core

Publish flow from this repo:

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

Agent Notes

The CLI can bootstrap and manage a local HeadlessX workspace under ~/.headlessx, and the operator commands still talk to the HeadlessX API.

If the backend uses the persistent browser profile under apps/api/data, CLI requests share that backend state because they go through the same API instance.

When a user asks to "test the CLI", prefer:

  1. headlessx --help
  2. headlessx init --help
  3. headlessx login --help
  4. headlessx status
  5. headlessx doctor
  6. headlessx logs --no-follow
  7. operator-specific help or smoke commands

Use scripts/smoke_cli.py when you need a fast deterministic baseline.

Comments

Markdown supported