kotschak/qelectrotech-source-mirror

Fork 0

mirror of https://github.com/qelectrotech/qelectrotech-source-mirror.git synced 2026-09-20 07:14:13 +02:00

Table of Contents

Command Line Interface (CLI) Reference

Quick Start

Launch QElectroTech

Overview
Installation & Access

Windows
macOS
Linux

Basic Usage

Open a Single File
Open Multiple Files
Open File from Different Directory
Get Version Information
Get Help

Command Line Options

File Operations
Project File

Export & Batch Operations
Common Workflows

Workflow 1: Open Project for Editing
Workflow 2: Batch Open Multiple Projects
Workflow 3: Integration with Scripts
Workflow 4: Project with Parameters

Scripting & Automation

Launching QET from Scripts
Batch Processing Multiple Files
Advanced Automation

Environment Variables

Setting QET Location in Scripts
Custom Configuration

Exit Codes
Troubleshooting

"Command not found: qelectrotech"
"Permission denied"
"File not found" on project
"Library not found" or "Missing dependencies"

Advanced Usage

Running QET in Background
Capturing Output
Running Multiple Instances
Cron/Scheduled Tasks

Limitations & Workarounds
Best Practices

Script Development
Error Handling

Integration Examples

With Git
With File Managers
With IDEs/Editors

Comparison: GUI vs CLI
Getting Help

Check Version & Help
Community Support
Bug Reports

Next Steps
Quick 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:

Find installation directory (usually C:\Program Files\QElectroTech\)
Add to Windows PATH via Environment Variables
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

Depending on how the binary was compiled, these directory overrides may also be available: --common-elements-dir=DIR, --common-tbt-dir=DIR, --config-dir=DIR, --data-dir=DIR. Run --help to see which your build has.

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 folios
`--export-png` / `--export-svg`	a directory, one image per folio
`--export-bom`	CSV bill of materials
`--export-wiring`	CSV from-to wiring list
`--export-cables`	CSV wiring list, built from the document XML
`--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 output.

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:

Use the export flags above — they cover PDF, images, BOM, wiring lists, nets, cross-references and title-block stamping
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.
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"

Custom Configuration

QET's organisation and application name are both literally "QElectroTech" (checked in main.cpp), which is what Qt's QSettings uses to build the path — so on Linux/macOS that's ~/.config/QElectroTech/QElectroTech.conf, capitalised, not a lowercase qelectrotech/ folder.

There is no QET_CONFIG_DIR environment variable — checked directly, main.cpp/qetapp.cpp never read any QET-specific environment variable for this. The real override is the --config-dir=DIR CLI flag from the table above.

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:

Add to PATH:
- Windows: System Properties → Environment Variables
- Linux/macOS: Add to ~/.bashrc or ~/.zshrc:
```
export PATH="/usr/local/bin:$PATH"
```

Use full path:

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

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
No DXF export from the CLI	Use GUI export (File → Export)

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