Design commands

Install the project in editable mode before discovery or building. A live build requires an installed runtime, authentication, and a reachable project server. For translation without contacting the runtime, use --dry --no-dependency-check; --dry alone still runs the Python dependency check.

jitx design find
jitx runtime start --background
jitx design build myboard.main.Myboard
jitx design build --all

jitx design

Use find, build, session, exec, issues, or export. The group itself shows help.

jitx design find

List fully qualified Design class names. With positional paths, scan those paths and ignore --project with a warning. Without paths, scan the resolved project root. Discovery imports Python modules and can execute their module-level code.

jitx design find
jitx design find myboard

Argument / option	Default	Meaning
path	unset	Optional paths to scan; accepts multiple paths.
--project	unset	JITX project root (directory containing pyproject.toml with jitx as a dependency). Defaults to walking up from the current directory.

jitx design build

Build one or more fully qualified Design names or .py files. Without names, auto-select a single discovered design or offer an interactive choice. In noninteractive use, provide names or --all when more than one design exists.

--all cannot be combined with explicit names or --dump. --generate-config requires --all. --dump writes the translated payload; use it with one named design to keep the output unambiguous.

Connection selection is --uri, then --port with --host, then --socket, then the project connection. Explicit connection flags skip the project-runtime probe. Dry translation skips runtime communication but still checks Python dependencies unless --no-dependency-check is also supplied.

jitx design build myboard.main.Myboard --dry --no-dependency-check
jitx design build --all --generate-config

Argument / option	Default	Meaning
design	unset	Fully qualified Design class name (or names / Python files for build). Repeatable.
--all	false	Build every design discoverable in the resolved project.
--dump	unset	Write the translated design payload to this path before sending it to the runtime — useful for debugging.
--dry	false	Translate without contacting the runtime; add –no-dependency-check to skip the Python dependency check.
--host	localhost	Hostname the runtime is listening on. Only consulted when --port is supplied without --uri.
--port	unset	Port the runtime is listening on. Skips the project-local probe and connects to ws://<host>:<port>.
--uri	unset	Full URI of the runtime (e.g. ws://localhost:39365/abc123). Takes precedence over --port / --socket / project probe.
--socket	unset	Path to a socket file describing the runtime’s connection parameters. Used when targeting a runtime outside the resolved project’s directory.
--generate-config	false	After building, write/refresh the VS Code launch configuration for each discovered design. Only meaningful with --all.
--no-dependency-check	false	Skip the pyproject.toml dependency sync step.
--check-include-group	unset	Include this dependency group in the pre-build sync check. Repeatable.
--project	unset	JITX project root (directory containing pyproject.toml with jitx as a dependency). Defaults to walking up from the current directory.

jitx design session

Hold a design open in the project’s runtime and run scripts sent by jitx design exec. It requires an installed runtime, authentication, and a reachable project server. The session runs until --stop is sent for the same design, or until another session starts on it.

jitx design session myboard.main.Myboard
jitx design session myboard.main.Myboard --stop

Argument / option	Default	Meaning
design	required	Fully qualified Design class name.
--stop	false	Stop the session running for design instead of starting one. design only names the session; the design isn’t loaded.
--project	unset	JITX project root (directory containing pyproject.toml with jitx as a dependency). Defaults to walking up from the current directory.

jitx design exec

Run a script against a design held by jitx design session. Pass exactly one of a script file, - for stdin, or -c. The session calls the --function function with the design and prints its return value as JSON.

jitx design exec myboard.main.Myboard check.py
jitx design exec myboard.main.Myboard -c "def main(design): return design.name"

Argument / option	Default	Meaning
design	required	Design served by jitx design session. Only names the session; the design isn’t loaded.
file	unset	Script file to run, or - to read the script from stdin.
-c, --command	unset	Script source to run.
-f, --function	main	Function in the script to call with the design.
--project	unset	JITX project root (directory containing pyproject.toml with jitx as a dependency). Defaults to walking up from the current directory.

jitx design issues

Submit a design and report its physical-design issues. It requires an installed runtime, authentication, and a reachable project server. It exits 0 unless --error is given; then it exits with the code of the worst matching severity (error 1, warning 2, info 3), so it can be used as a CI gate.

jitx design issues myboard.main.Myboard
jitx design issues myboard.main.Myboard --error error

Argument / option	Default	Meaning
design	required	Fully qualified Design class name.
--category	all	Only report this category: signal_constraint, topology, geometry, realization, routing, length_tuning, or general. Repeatable.
--satisfied	false	Also report checks that passed.
--wait	5.0	Seconds to wait for background tasks to finish before taking the snapshot. 0 answers immediately.
--error	unset	Exit with a non-zero code when an issue of this severity or worse (error, warning, info) is reported.
--project	unset	JITX project root (directory containing pyproject.toml with jitx as a dependency). Defaults to walking up from the current directory.