Getting Support#

When a build fails in a way you can’t explain, or the runtime misbehaves, JITX support can help fastest with a diagnostics bundle — a zip of your project, the runtime’s configuration and logs, and the environment the CLI sees. The jitx support commands build that bundle and, separately, file a support ticket, all from the terminal. This guide targets JITX 4.4.0; the support commands were introduced in jitx 4.2.2.

By default a diagnostics bundle stays on your disk. Uploading the bundle requires --submit and confirmation (or --yes). jitx support request submits the ticket text after confirmation even without --submit.

Both commands require you to be signed in — the bundle records which account it came from. If you aren’t, they stop before doing anything:

Error: no license file on disk. Sign in first with `jitx auth login`.

Warning

A bundle contains your design files. If your project is subject to export-control or other data-handling restrictions (ITAR/EAR and similar), don’t pass --submit — build the bundle locally and deliver it through your organization’s approved channel. Uploading a diagnostics bundle requires --submit plus confirmation (or --yes); filing a ticket sends its text after confirmation. The account identity recorded in the bundle is decoded from your license; the license token itself is never included.

Build a diagnostics bundle#

From inside your project, build a bundle and attach a note describing the problem for support staff:

jitx support bundle --description "Build fails after adding the USB connector"
jitx support bundle --description-stdin < notes.txt    # multi-line notes from a file

The bundle is written locally and nothing is sent:

A support bundle was created but not uploaded:
  /Users/you/.jitx/support/support-bundle-20260909-142530.zip (1,482,113 bytes)
  Designs: 1
It may contain export-controlled or otherwise restricted (ITAR/EAR) design data — share it with JITX support only if it is cleared for release.

Bundles go under ~/.jitx/support/ with a timestamped filename. Pass --out to choose another destination. An existing file at the output path can be overwritten; choose distinct paths when retaining multiple bundles.

The project is found by walking up from the current directory; name it explicitly with --project if you’re running from elsewhere. If no project is found at all, the CLI warns and still collects the runtime state — useful when the runtime itself is the problem — and reports Designs: 0. An explicit --project that isn’t a JITX project is an error.

--description (or -d) is optional but worth including; without it the CLI reminds you with Tip: pass --description to attach context for support staff.

Inspect the bundle before sharing#

A bundle is an ordinary zip file, so you can check exactly what it contains before handing it to anyone:

unzip -l ~/.jitx/support/support-bundle-20260909-142530.zip

Path	Contents
`manifest.json`	JITX version, platform, installation type, server URL, your account identity (decoded from the license, never the token), your description, the list of designs, and any files skipped for size
`workspace/`	Your project tree, including the project’s `.jitx/` directory (runtime logs and `runtime.json`)
`runtime/`	The runtime’s introspection output and its configuration files
`env/`	The environment variables the runtime honors, a short allowlist of OS variables (`HOME`, `SHELL`, `LANG`, `PATH`, `USER`, …), and the OS and Python versions

Left out of workspace/: version-control directories (.git and friends), virtual environments and build or cache output (.venv, __pycache__, build, dist, node_modules), editor settings (.vscode, .idea), credential stores and secrets (.ssh, .aws, .gnupg, .env, *.key, *.pem, id_rsa*, *.p12), your JITX license files, earlier support bundles, and any single file over 50 MiB (these are listed as Skipped N file(s) over the size cap: when the bundle is built). File and directory names listed under [tool.jitx] exclude in pyproject.toml are also left out, so add anything else that must not leave your machine there.

Upload a bundle to JITX#

Once you’ve decided the bundle is cleared to share, --submit uploads it after building:

jitx support bundle --submit --description "Build fails after adding the USB connector"

You’re asked to confirm first, and the default is no:

Upload this diagnostics bundle — including your design files — to JITX servers? [y/N]: n
Error: Submission cancelled; nothing was sent to JITX.
The bundle is saved locally at /Users/you/.jitx/support/support-bundle-20260909-142530.zip.

Answer y and the CLI uploads the bundle and prints its bundle id along with the size, completion time, design count, and a Local copy: line — a local copy is always kept. Quote the bundle id when you contact support. For scripting, --yes (or -y) skips the confirmation.

If the upload fails, the error always names the local file so you can retry or deliver it another way. If your credentials are rejected, run jitx auth refresh (or jitx auth login) and try again.

File a support ticket#

jitx support request files a ticket with JITX support directly from the terminal. On its own it sends only the text you write; two flags decide whether a diagnostics bundle is built alongside it:

jitx support request                 # ticket text only
jitx support request --project .     # also writes a local bundle (not uploaded)
jitx support request --submit        # also uploads a bundle and attaches it to the ticket

You’re prompted for a title and a description unless you pass --title (-t) and --description (-d); use --description-stdin for multi-line text piped in from a file or another tool. Blank values are rejected. Filing always asks for confirmation (skip it with --yes), and the prompt tells you exactly what is about to happen:

Text only — File this support ticket with JITX? Nothing but your title and description is sent.
--project without --submit — File this support ticket with JITX and write a local diagnostics bundle under $HOME/.jitx/support/ (not uploaded)? The bundle stays on your disk for you to deliver through an approved channel; the ticket is filed with a note telling support where it is and that it may be export-restricted.
--submit — File this support ticket with JITX and upload a diagnostics bundle — including your design files? The bundle is built in a temporary directory, uploaded, and attached to the ticket. No local copy is kept, so run jitx support bundle separately if you want one.

A typical interactive session, up to the confirmation:

Title: Build fails after adding the USB connector
Description: jitx design build exits with status error after adding J1; the runtime log is in .jitx/logs.
File this support ticket with JITX? [y/N]: y

On success the CLI prints Ticket <id> filed. With --submit, that line is preceded by Bundle <id> attached (<size> bytes). and followed by the bundle id, so you can refer to both when following up.

Note

For scripts and coding agents, the global --format json flag (jitx --format json support bundle) prints a single JSON object on stdout instead of the text above. In JSON mode there is no place for a prompt, so anything that would ask for confirmation requires --yes, and jitx support request requires --title and --description (or --description-stdin); otherwise the command exits with a usage error before doing any work.

See the support command reference for every argument, option, and default.