Cli

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.