CLI

Install the published HeadlessX CLI, bootstrap a local workspace, and run the operator API from the terminal.

The published HeadlessX CLI package is:

package: @headlessx-cli/core
command: headlessx

It talks to the same backend API used by the dashboard, and it also manages the local HeadlessX workspace lifecycle through ~/.headlessx.

Install

With npm:

With pnpm:

Bootstrap a workspace

The current CLI is not just an API client. It also boots and manages the local runtime.

Fastest path:

Common mode examples:

The default branch is main. Use --branch develop only when you explicitly want the development branch.

Log in

Interactive login:

Direct login:

Environment variables also work:

Lifecycle commands

Core lifecycle commands:

Update an existing install:

headlessx init update reuses the saved mode and env files for the workspace, pulls the saved branch, and backfills missing env keys when the runtime layout changes.

Common commands

Website scrape:

Google AI Search:

Tavily and Exa:

YouTube:

Jobs and operators:

Output model

headlessx is markdown-first by default.

default output is compact markdown or text
--json opts into JSON
--pretty pretty-prints JSON
-o page.md or -o data.json writes to a file

Redis is only needed for crawl

Website scrape, map, Google AI Search, Tavily, Exa, and YouTube commands do not need Redis. Queue-backed crawl commands still require Redis plus the worker, because they call the same /api/operators/website/crawl backend workflow as the dashboard.

Google AI Search needs one shared-profile bootstrap

Before the first Google AI Search run, open the dashboard Google workspace and use Build Cookies once. That seeds the shared persistent browser profile with Google session state. The CLI then benefits from the same saved profile through the API runtime.