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.

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.