#081Tutorial3 min

Use the Hackaiz CLI

Understand the prepared source client, stable requests and verification exit codes before automating it.

Hackaiz team · updated 21/11/2026

Illustration: a developer uses an editor and a terminal.
Illustration: a developer uses an editor and a terminal. Illustrative photo, not a screenshot.

01Check the distribution status before installation

The repository contains a command-line client in tools/hackaiz-cli with an executable at bin/hackaiz.mjs. Its package requires Node.js 22 or later. Although the package README shows a global npm installation example, the integration page explicitly says the client is prepared in the repository and is not published on npm. Use the source in an approved setup rather than presenting the example as proof that a public package is available.

The connected analysis workflow also needs deployed, synchronized autonomous processing. The integration page does not confirm a real customer-account run. Treat these as operational prerequisites, not details solved by having the client files locally. In a source checkout where the prerequisites are satisfied, “node tools/hackaiz-cli/bin/hackaiz.mjs help” shows the implemented commands. Help itself does not submit an analysis or prove that the remote worker is ready.

02Prepare the key and the platform identifier

The client reads HACKAIZ_API_KEY from the environment and sends it as a Bearer authorization header. Use a personal key with read access and launch permission for the intended platform. Keep it out of repository content and logs; configure it through your shell environment or automation secret store. The first positional identifier for connected commands is the saved platform UUID, not a repository URL, domain name or local source directory.

Before any website or API analysis, complete domain proof using the _hackaiz DNS TXT record, the HTTPS file /.well-known/hackaiz-verification.txt, or the instruction for your project AI to create that file. The target must be authorized and have current consent. The key does not waive those requirements. Analyses use account credits, and account purchases stay in Hackaiz rather than the terminal. Never put a key in a command you intend to copy into a public support ticket.

03Launch once and recover using the same request

The connected syntax is “hackaiz analyze PLATFORM_UUID STABLE_REQUEST_KEY”. When using the source directly, replace the initial hackaiz command with the Node invocation of bin/hackaiz.mjs. Supply a stable request key that identifies the intended run, then retain the returned requestId. The client polls the existing request with GET calls. Closing the client does not request cancellation of autonomous work and does not make an already started analysis safe to replay.

Use “hackaiz status PLATFORM_UUID REQUEST_UUID” to read that same request after an interruption. “hackaiz report PLATFORM_UUID” reads the platform’s latest report, while “hackaiz findings PLATFORM_UUID” reads findings. Those convenience reads are not a substitute for linking a release decision to a particular run. The analyze command can return success for a partial analysis, so its exit code alone is not a complete release gate. Check the stored run and its findings explicitly.

04Distinguish verification from component checking

“hackaiz verify PLATFORM_UUID REQUEST_UUID” reads only the analysis linked to that request and traverses its findings. Exit 0 means no unresolved High or Critical finding was found in a complete linked analysis; exit 1 means such findings exist; exit 2 is inconclusive because the analysis or data is incomplete or unavailable. High and Critical belong to the customer-facing Danger group. This verifies a saved-platform result, not a particular pull request commit or deployment.

The separate command “hackaiz check <path> --sarif” checks component text such as a Skill, MCP configuration, package or workflow and emits a structured SARIF report. Its codes are different: Danger returns 2 and an incomplete verdict returns 3. Do not reuse verify’s code mapping for check. The CLI never publishes fixes or merges changes; Hackaiz corrections remain draft GitHub pull requests for human review. A passing command is neither certification nor evidence that all application behavior was tested.

Frequently asked questions

Was this article helpful?

Related articles