Skip to content

Headless Execution

NEX is designed to be a deeply interactive assistant, but many workflows, such as CI/CD pipelines, nightly regression runs, or automated linting, require it to operate without human intervention.

For these scenarios, NEX provides a headless execution mode that lets you invoke the agent directly without the user interface.

Note

This page describes the headless mode of NEX's main multi-agent system. Some task-specific agents also provide their own headless execution modes, which may expose different command-line interfaces or behaviors depending on the task they perform. Refer to the documentation for each task agent for details.

Use Cases

Common use cases for headless execution include:

  • CI/CD Pipelines: Validate RTL changes, review pull requests, or verify synthesis and timing constraints as part of your automated build pipeline.
  • Batch Processing: Run formatting, design sweeps, or waveform generation across multiple designs or entire IP libraries.
  • Scheduled Jobs: Execute nightly builds or regression suites and have NEX automatically summarize failures and highlight actionable issues.

Enabling Headless Mode

You can run NEX in headless mode by passing your instructions directly via the --prompt parameter:

Shell
nex --prompt="Run the linting flow on the ALU module and summarize any warnings."

When a prompt is provided through the CLI, NEX skips the interactive chat interface, initializes the required agents, executes your request, prints the final response to stdout, and exits.

Machine-Readable Output

For automation workflows, combine --prompt with --json-output to emit the response as structured JSON instead of plain text. This makes it easy for shell scripts, CI/CD pipelines, and other tools to parse NEX's output programmatically.

Example:

Shell
nex --prompt="Run the linting flow on the ALU module." --json-output

The JSON response includes the generated answer together with useful metadata such as the session ID, approval policy, execution statistics, token usage, and timing information.

Exit Codes and Errors

A completed headless turn exits with code 0. If the turn ends with an execution error, NEX exits with code 1. In JSON mode, it writes the response before exiting: successful turns have status: 200; failed turns have status: 500 and an error field explaining the failure. These status values are JSON fields, separate from the process exit code.

If a requested session cannot be loaded, NEX exits with code 1 and returns status: 404, an error message, and the requested session_id in JSON mode. Startup errors can occur before a JSON response is available, so CI scripts should check the process exit code even when using --json-output.

For example, preserve the failure status while saving the response for inspection:

Shell
if nex --prompt="Run the linting flow on the ALU module." \
    --approval-policy=auto --json-output > nex-result.json; then
    echo "NEX completed; review nex-result.json for the workflow result."
else
    nex_status=$?
    echo "NEX failed with exit code $nex_status; inspect nex-result.json and stderr." >&2
    exit "$nex_status"
fi

A completed turn can still report failing tests or an unmet design target. Review the response and verification evidence as well as the exit code.

Continuing a Session

Headless execution also supports multi-turn conversations. Pass an existing session ID with --session-id to continue a previous session while preserving its conversation history.

Example:

Shell
nex --session-id=my-session --prompt="Summarize the timing violations from the previous run."

This allows scripts and automated workflows to build on earlier interactions instead of starting a new session for every invocation.

Managing Interactivity

By default, NEX continues to enforce its approval workflow, even when invoked with --prompt. If a task requires executing a high-impact shell command or modifying protected files, NEX will pause and request confirmation.

In fully automated environments such as GitHub Actions, no one is available to provide that confirmation, causing execution to block. For unattended workflows, configure an appropriate Approval Policy so NEX can proceed without interactive prompts.