Use when an agent needs to operate HeadlessX through the published `headlessx` CLI instead of calling files or APIs directly. Covers installing the CLI package, bootstrapping local HeadlessX with `headlessx init`, updating an existing workspace with `headlessx init update`, using the guided modern setup/login prompts, logging in with API URL and API key, reading runtime logs with `headlessx logs`, using markdown-first terminal output, and running commands for website scraping, map, crawl, Google AI Search, Tavily, Exa, YouTube, jobs, and operators. Trigger for requests like "use the CLI", "test the CLI", "show the command", "log in with the CLI", "run HeadlessX from terminal", "bootstrap HeadlessX", "update HeadlessX", "show logs", or "smoke test the CLI".
Use headlessx as the canonical command.
For full command families and route coverage, read:
references/command-matrix.md for operator-by-operator commandsreferences/auth-and-output.md for auth precedence and output rulesreferences/operator-routes.md for the current operator-first API mappingFor deterministic validation, run:
scripts/smoke_cli.py to verify install, auth surface, and core help outputInstall 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
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.
Prefer the default markdown/text output for LLM-facing use.
Use --json only when structured machine-readable output is specifically needed.
Read references/command-matrix.md before composing multi-step CLI runs. It contains:
Current package:
@headlessx-cli/coreGlobal 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
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:
headlessx --helpheadlessx init --helpheadlessx login --helpheadlessx statusheadlessx doctorheadlessx logs --no-followUse scripts/smoke_cli.py when you need a fast deterministic baseline.