CLI commands

Every nelix command as the tool itself lists it, grouped by what it is for.

EngineerStudentDeveloper 2 min read · Updated 2026-10-05

        On this page
        ProjectsThe three stagesResultsJobsNelix Agent: a failed simulationNelix Agent: a buildStructured outputRun ids
      

All commands run in the Workspace terminal. Be inside the project folder, except for nelix new and nelix learn. Running nelix with no arguments prints this list.

Projects#

Command	What it does
`nelix new [NAME] [--template ID]`	Create a project in `~/project`. With no template it asks you to choose a starter
`nelix new NAME --default`	Create a project from MAC-8 without the menu
`nelix learn`	List the guided projects and the command that creates each

Starter ids: uart-tx, fifo, blank. Guided ids: g1-counter, g2-debug, g3-pwm, g4-fsm, g5-uart.

The three stages#

Command	What it does
`nelix test`	Run the simulation: cocotb with Icarus Verilog
`nelix synth`	Synthesize the RTL with Yosys
`nelix build`	Run the OpenLane flow from RTL to a layout

These do not depend on Nelix Agent being available and do not use an AI request.

Results#

Command	What it does
`nelix waveform`	Open the waveform of the latest test
`nelix schematic [--module NAME] [--list-modules]`	Open the synthesized schematic
`nelix report [PROJECT]`	Show the latest build report
`nelix layout [PROJECT]`	Open the layout of the latest build
`nelix timing`	Show the timing summary of the latest build
`nelix artifacts [BLD-ID]`	List the files kept for a build

Jobs#

Command	What it does
`nelix status [JOB]`	Show a job. With no id, your latest
`nelix jobs`	List your recent jobs
`nelix logs JOB`	Print the raw tool output of a job
`nelix cancel JOB`	Cancel a queued or running job

Nelix Agent: a failed simulation#

Command	What it does
`nelix debug [TST-ID]`	Analyse a failed simulation
`nelix repair propose`	Propose a fix to the RTL that can be applied automatically
`nelix repair show ID`	Review a saved repair
`nelix repair approve ID --approve`	Approve it for verification
`nelix repair verify ID`	Verify it in a separate copy of the project
`nelix repair revise ID`	Ask for a revised repair
`nelix repair accept ID --approve`	Accept a verified repair
`nelix repair merge ID --approve`	Merge an accepted, verified repair into your working RTL
`nelix repair rollback ID --approve`	Restore the working RTL from before a merge
`nelix repair discard ID`	Throw a repair away
`nelix patch show ID`	Review a proposed AI patch

Nelix Agent: a build#

Command	What it does
`nelix ai status`	Show whether Nelix Agent is available
`nelix ai analyze [BLD-ID] [--learn] [--explain]`	What Nelix Agent found in a build, from its measured results
`nelix ai timing` and `power`, `area`, `cts`, `routing`, `antenna`, `drc`, `lvs`	One specialist: diagnosis, evidence, proposals and measured candidates
`nelix ai history`	Every candidate built for this project, and what became of it
`nelix explain-timing`	Explain timing from the build's own timing evidence
`nelix optimize propose`	Propose a measured timing optimisation of the RTL
`nelix optimize show`, `approve`, `verify`, `accept`, `discard`	Review and act on a proposed optimisation

Commands that change your design need --approve, so nothing is applied by accident.

Structured output#

Add --json to jobs, status, waveform, schematic, report, layout, design, debug, ai, artifacts, repair or patch for a machine-readable response. nelix design prints the project's design-view state in that form.

Run ids#

Prefix	Stage
`TST-`	Simulate
`SYN-`	Synthesize
`BLD-`	Build the chip

The rest is the date and a counter, for example BLD-20261005-0007.

Job statesEvery state a run can be in, what it means, and what you can do in it.
Build specialists and optimisationThe specialists that read a finished build, and how a proposed timing fix is measured before you accept it.

Something unclear or missing? Send feedbackSign in and use Feedback to tell us.