cli_reference

Command Line Interface (CLI) Reference

Use QElectroTech from the command line for scripting, automation, and batch operations.

---

Quick Start

Launch QElectroTech

Basic launch:

qelectrotech

Open a project:

qelectrotech /path/to/project.qet

Open multiple projects:

qelectrotech project1.qet project2.qet project3.qet

---

Overview

QElectroTech is primarily a GUI application, but can be launched and controlled from the command line for:

• Opening projects in batch
• Exporting diagrams to various formats
• Integrating with scripts and automation
• Headless processing (limited support)

Note: Full headless/non-interactive CLI is limited. For complex automation, see API Reference for scripting options.

---

Installation & Access

Windows

After installation, launch from:

# Standard command
qelectrotech

# Or full path
"C:\Program Files\QElectroTech\qelectrotech.exe"

Add to PATH for easier access:

1. Find installation directory (usually C:\Program Files\QElectroTech\)
2. Add to Windows PATH via Environment Variables
3. Then use qelectrotech from any command prompt

macOS

After installation, launch from:

# Via Homebrew
qelectrotech

# Or direct path
/Applications/QElectroTech.app/Contents/MacOS/QElectroTech

Create alias for easier access:

alias qet="/Applications/QElectroTech.app/Contents/MacOS/QElectroTech"
qet

Linux

After installation:

# Package manager installations
qelectrotech

# AppImage
./QElectroTech-*.AppImage

# Flatpak
flatpak run org.qelectrotech.QElectroTech

---

Basic Usage

Open a Single File

qelectrotech myproject.qet

Result: Opens QET with the project loaded in the GUI

Open Multiple Files

qelectrotech project1.qet project2.qet project3.qet

Result: Opens all projects in separate windows/tabs

Open File from Different Directory

qelectrotech /home/user/projects/myschematic.qet
qelectrotech ~/Documents/diagram.qet
qelectrotech ./relative/path/project.qet

Get Version Information

qelectrotech --version
qelectrotech -v

Output: Shows QElectroTech version number

Get Help

qelectrotech --help
qelectrotech -h

Output: Lists available options and usage

---

Command Line Options

File Operations

Option	Usage	Description
--help	qelectrotech --help	Show help message
--version, -v	qelectrotech -v	Show version number
--license	qelectrotech --license	Show the licence
--lang-dir=DIR	qelectrotech --lang-dir=/opt/qet/lang	Directory holding the translation files

Four more options point QElectroTech at other folders:

Option	Folder
--common-elements-dir=DIR	the shipped symbol collection
--common-tbt-dir=DIR	the shipped title block templates
--config-dir=DIR	your configuration files
--data-dir=DIR	your own symbols, title blocks and logs

They are in every standard build (a packager can switch each one off at compile time; run --help to see what yours has). The Windows portable archive's launcher uses all four — see Installing on Windows without admin rights.

• A folder given on the command line wins over the collection folder saved in the preferences, for that run.

• They also apply to the headless runs: the exports below, --info, --resave and --run, and they can go anywhere among the other arguments:

  qelectrotech --export-pdf --common-elements-dir=/srv/qet/elements project.qet out.pdf
  qelectrotech --run add_motor.js project.qet --common-elements-dir=/srv/qet/elements

  In builds before PR #1262 (merged 2 October 2026) the headless runs ignored them, and an export took the option for the project file (Project not found).

Note the two different syntaxes. These options take their value with an = sign. The export flags in the next section take theirs positionally. A project file is given as a plain positional argument — there is no -o or --open option.

Project File

# Open specific project
qelectrotech myproject.qet

# Multiple projects open in separate windows
qelectrotech project1.qet project2.qet

---

Export & Batch Operations

QET has a headless export mode: pass one of the flags below and it opens the project, does the work and exits without showing a window.

qelectrotech --export-pdf myproject.qet out.pdf

Arguments are positional, not --flag=value. The shape is always qelectrotech <flag> <project.qet> <output>.

Flag	Output
--export-pdf	one PDF, all sheets
--export-png / --export-svg	a directory, one image per sheet
--export-dxf	a directory, one DXF per sheet; add --dxf-blocks to write symbols as DXF blocks, --dxf-attributes to also make their texts block attributes — see DXF import & export
--export-bom	CSV bill of materials (parts list); add --no-slaves to leave contact blocks and other slave symbols out, --no-junctions to leave junctions out — see Building a nomenclature query
--export-wiring	CSV from-to wiring list, from the project database (columns below)
--export-cables	CSV wiring list, built from the document XML; the same file as Projet → Exporter le plan de câblage (Project → Export the wiring diagram), with the wire's Cable as its last column — see Conductors
--export-wires	CSV conductor numbers
--export-nets	CSV electrical nets
--export-links	CSV cross-references
--info	JSON structural dump (stdout if no output path)
--resave	rewritten .qet
--set-titleblock	.qet with title-block fields stamped
--check-elements	validates .elmt files or a directory of them
--run	run a JavaScript macro against a project — see JavaScript Scripting

Plus --show-terminals, which paints terminal markers into PDF/PNG/SVG/DXF output.

--export-wiring columns, one row per wire, sorted by sheet then wire number:

Column
wire_number	the wire's number
from_element_label, from_terminal	the symbol and terminal name at one end
to_element_label, to_terminal	the same at the other end
diagram_position	the sheet's place in the project
conductor_uuid	the wire's id in the project file
from_terminal_index, to_terminal_index	the terminal's number within its symbol, counted from 0, top to bottom then left to right — the number a script's addConductor() takes. Empty when two terminals of one symbol sit at the same point
from_terminal_uuid, to_terminal_uuid	the terminal's id in the symbol

Most shipped symbols leave their terminals unnamed, so from_terminal and to_terminal are often empty; the index and uuid columns still say which terminal each end is on. They were added as the last four columns (PR #1248, 2 October 2026), so a reader of the older columns is not disturbed.

A repeatable PDF: with the SOURCE_DATE_EPOCH environment variable set, --export-pdf gives the same file, byte for byte, for the same project — see Environment Variables below.

Exit codes: 0 success, 1 the work failed, 2 called wrongly — so these are safe to chain in a script with set -e.

QT_QPA_PLATFORM=offscreen is enough; no Xvfb is needed. Always set a timeout in automated runs.

Full detail, including the --set-titleblock assignment syntax: Automating QElectroTech.

---

Common Workflows

Workflow 1: Open Project for Editing

# Open project
qelectrotech myschematic.qet

# User edits in GUI, saves manually

Workflow 2: Batch Open Multiple Projects

# Open all QET files in current directory
qelectrotech *.qet

# Open all in a specific folder
qelectrotech /projects/2024/*.qet

Workflow 3: Integration with Scripts

#!/bin/bash
# Script to open latest project

latest=$(ls -t *.qet | head -1)
qelectrotech "$latest"

Workflow 4: Project with Parameters

# Open and pass parameters (if supported)
qelectrotech --project myproject.qet

---

Scripting & Automation

Launching QET from Scripts

Bash:

#!/bin/bash
qelectrotech /path/to/project.qet &

Python:

import subprocess

subprocess.Popen(['qelectrotech', '/path/to/project.qet'])

PowerShell (Windows):

& "C:\Program Files\QElectroTech\qelectrotech.exe" "project.qet"

Batch Processing Multiple Files

Bash script to open all projects:

#!/bin/bash
for file in *.qet; do
    echo "Opening $file..."
    qelectrotech "$file" &
done
wait

Advanced Automation

For complex automation:

1. Use the export flags above — they cover PDF, images, BOM, wiring lists, nets, cross-references and title-block stamping
2. For loops, conditionals, or reading the model to decide what to export, use JavaScript scripting: --run script.js project.qet, or "Run Script..." in the GUI. See JavaScript Scripting.
3. For anything neither covers, write a program of your own that reads and writes the .qet / .elmt XML directly — see Automating QElectroTech

QET still has no plugin system: nothing runs automatically, and no project file can carry or trigger a script. Every script run is explicit.

---

Environment Variables

Setting QET Location in Scripts

Linux/macOS:

export QET_PATH="/usr/bin/qelectrotech"
$QET_PATH myproject.qet

Windows (PowerShell):

$env:QET_PATH = "C:\Program Files\QElectroTech\qelectrotech.exe"
& $env:QET_PATH "project.qet"

SOURCE_DATE_EPOCH: the same PDF every time

--export-pdf reads one environment variable. With SOURCE_DATE_EPOCH set to a number of seconds since 1 January 1970 UTC (the reproducible-builds.org convention), the PDF's dates are that time and its document id comes from the pages, so two exports of the same project are identical:

SOURCE_DATE_EPOCH=$(git log -1 --format=%ct) qelectrotech --export-pdf project.qet project.pdf

Without it, the PDF carries the time of the export. A value that is not a whole number of seconds is reported on stderr and ignored. The print window's PDF does not read it. More in Printing and exporting.

Custom Configuration

QET's organisation and application name are both literally "QElectroTech" (checked in main.cpp), which is what Qt's QSettings uses to place the settings:

System	Settings are kept in
Windows	the registry, HKEY_CURRENT_USER\Software\QElectroTech\QElectroTech
Linux	~/.config/QElectroTech/QElectroTech.conf — capitalised, not a lowercase qelectrotech/ folder
macOS	the system preferences, a .plist file under ~/Library/Preferences

QET_SETTINGS_DIR moves them. Set to a folder, QElectroTech keeps its settings in an ini file in that folder instead, <folder>/QElectroTech/QElectroTech.ini, on every system. A script or tool that runs QElectroTech headlessly can give each run its own settings this way, without touching the user's:

QET_SETTINGS_DIR=/tmp/qet-run1 qelectrotech --export-pdf project.qet out.pdf

There is no QET_CONFIG_DIR variable. --config-dir=DIR (table above) is a different thing: the folder for QElectroTech's own configuration files, such as saved text patterns and summary queries, not the settings.

To copy your settings to another computer, or keep several sets of them, use Configuration → Enregistrer la configuration sous... (Settings → Save settings as...) and Charger une configuration... (Load settings...) — see Saving and loading settings.

---

Exit Codes

QElectroTech typically returns:

Code	Meaning
0	Success - program ran without errors
1	Error - general error occurred
2	Error - invalid command line arguments

Example - Check for errors:

qelectrotech myproject.qet
if [ $? -ne 0 ]; then
    echo "QET failed to launch"
fi

---

Troubleshooting

"Command not found: qelectrotech"

Problem: QET not in PATH

Solutions:

1. Add to PATH:

   • Windows: System Properties → Environment Variables
   • Linux/macOS: Add to ~/.bashrc or ~/.zshrc:

     export PATH="/usr/local/bin:$PATH"

2. Use full path:

   /usr/bin/qelectrotech project.qet
   # or
   "C:\Program Files\QElectroTech\qelectrotech.exe" project.qet

3. Check installation:

   which qelectrotech  # Linux/macOS
   where qelectrotech  # Windows

"Permission denied"

Problem: Executable doesn't have permission

Solution:

# Linux/macOS
chmod +x /path/to/qelectrotech
ls -l /path/to/qelectrotech  # Should show x permission

"File not found" on project

Problem: Path to .qet file is incorrect

Solutions:

# Use absolute path
qelectrotech /home/user/projects/myproject.qet

# Use relative path from current directory
cd /home/user/projects
qelectrotech myproject.qet

# Check file exists first
ls -la myproject.qet
qelectrotech myproject.qet

"Library not found" or "Missing dependencies"

Problem: Qt libraries not installed

Solutions (Qt 6 — current QET builds against Qt 6, not Qt 5):

• Ubuntu/Debian: sudo apt install libqt6gui6 libqt6svg6
• Fedora: sudo dnf install qt6-qtbase qt6-qtsvg
• macOS: brew install qt6

---

Advanced Usage

Running QET in Background

Linux/macOS:

qelectrotech myproject.qet &

Windows (PowerShell):

Start-Process qelectrotech -ArgumentList "project.qet"

Capturing Output

# Redirect to log file
qelectrotech myproject.qet > qet.log 2>&1

# Run silently
qelectrotech myproject.qet >/dev/null 2>&1

Running Multiple Instances

# Open different projects simultaneously
qelectrotech project1.qet &
qelectrotech project2.qet &
qelectrotech project3.qet &
wait  # Wait for all to finish

Cron/Scheduled Tasks

Linux/macOS - Schedule daily backup:

# In crontab -e
0 2 * * * /usr/bin/qelectrotech ~/projects/*.qet > ~/logs/qet_backup.log 2>&1

---

Limitations & Workarounds

Limitation	Workaround
No CLI option to create or edit a diagram from a flag	Use JavaScript scripting (--run) for edits with real undo, or the .qet XML directly for anything scripting doesn't cover — see JavaScript Scripting and Automating QElectroTech
One project per invocation	Loop in the shell; each run is independent

Corrected September 2026. This section previously claimed QET had no headless export and no CLI PDF export, and pointed readers at Python scripting and plugins that do not exist. Headless export has shipped for some time — see the export flags above.

---

Best Practices

Script Development

✅ Do:

• Use absolute paths for reliability
• Check file existence before opening
• Capture exit codes
• Log output for debugging
• Test with sample projects first

⚠️ Don't:

• Assume qelectrotech is in PATH
• Use relative paths without cd first
• Ignore error messages
• Try to automate complex tasks via CLI (use scripting instead)

Error Handling

#!/bin/bash
# Good error handling

QET="qelectrotech"
PROJECT="myproject.qet"

# Check if file exists
if [ ! -f "$PROJECT" ]; then
    echo "Error: File not found: $PROJECT"
    exit 1
fi

# Run with error checking
if ! $QET "$PROJECT"; then
    echo "Error: QET failed to launch"
    exit 1
fi

echo "QET launched successfully"

---

Integration Examples

With Git

#!/bin/bash
# Open project modified in last commit

latest=$(git diff --name-only HEAD~1 HEAD | grep '\.qet$' | head -1)
if [ -n "$latest" ]; then
    qelectrotech "$latest"
fi

With File Managers

Create desktop launcher (Linux):

[Desktop Entry]
Name=QElectroTech
Type=Application
Exec=qelectrotech %F
Categories=Graphics;Engineering;

With IDEs/Editors

Some editors can open files with external apps:

• VS Code: Configure via launch.json
• Vim: Use :!qelectrotech file.qet
• Emacs: Use (shell-command "qelectrotech file.qet")

---

Comparison: GUI vs CLI

Task	GUI	CLI	Scripting
Open project	✅ Easy	✅ Easy	✅ Possible
Manual editing	✅ Best	❌ N/A	❌ N/A
Export single file	✅ Easy	⚠️ Limited	✅ Possible
Batch export	⚠️ Manual	⚠️ Limited	✅ Good
Automation	❌ No	⚠️ Limited	✅ Best
Data extraction	❌ No	⚠️ Manual	✅ Best

---

Getting Help

Check Version & Help

# See QET version
qelectrotech --version

# See available options
qelectrotech --help

# Check if installed correctly
which qelectrotech
qelectrotech --version

Community Support

• Forum — Ask about CLI usage
• Code Forum — Technical questions
• API Reference — For scripting solutions

Bug Reports

If CLI doesn't work as expected:

• GitHub Issues — Report bugs
• Include: QET version, OS, exact command, error output

---

Next Steps

• API Reference — For advanced automation with Python/XML
• User Manual — Understand QET features
• Scripts Forum — Community scripts and examples
• Development Roadmap — Planned CLI improvements

---

Quick Reference

# Basics
qelectrotech                           # Launch QET
qelectrotech myproject.qet             # Open project
qelectrotech --version                 # Show version
qelectrotech --help                    # Show help

# Multiple projects
qelectrotech *.qet                     # Open all QET files
qelectrotech project1.qet project2.qet # Open specific files

# Background operation
qelectrotech myproject.qet &           # Launch in background

# With logging
qelectrotech myproject.qet > output.log 2>&1

---

Ready to automate? See API Reference for scripting, or ask on Forum for CLI help!