Subjective Technologies

Subjective Operator Guide

A polished operator guide for the PyQt desktop client, plus direct subcli equivalents for the same workflows so teams can move between GUI operations and repeatable command-line automation without context switching.

PyQt workflowssubcli equivalentscopy-ready commands

GUI + CLI

Operate the Same Platform from the Terminal

The PyQt client is the visual control surface. subcli exposes the same operational areas as command-line workflows: services, connections, plugins, pipelines, VirtualGlass, logs, snapshots, chat, configuration, and themes.

Best for the GUI

Visual pipeline composition, image-heavy browsing, live screenshots, and at-a-glance multi-pane monitoring.

Best for subcli

Repeatable operations, remote sessions, scripted setup, quick inspection, and support workflows where copy-paste commands are faster than clicking through the UI.

subcli

subcli quick-start

These are the fastest commands to orient yourself if you want CLI parity with the desktop client.

Start the local stack

subcli service start --all

Check service health

subcli service status

Inspect saved connections

subcli connection list

Browse available plugins

subcli plugin list

Inspect saved pipelines

subcli pipeline list

Open the latest logs in terminal form

subcli log show --page 1

The sections below mirror the GUI manual and add the closest supported subcli workflow for each feature.
When a GUI feature has no exact CLI equivalent, the documentation says so directly and shows the nearest supported command path.

Application Overview

Subjective Technologies is a desktop application built with PyQt5 that serves as a universal data source management platform. It enables you to connect, monitor, and orchestrate data from dozens of sources — cloud services, local folders, databases, APIs, and more — through a unified interface.

Connection Management

Configure and manage connections to 30+ data source types with per-connection settings, credentials, and start-at-startup capabilities.

Visual Pipeline Editor

Drag-and-drop pipeline builder for creating multi-step data processing workflows with node connections and visual orchestration.

Plugin Store

App Store-style marketplace for discovering, installing, and managing data source plugins fetched directly from GitHub.

VirtualGlass

Companion C++ overlay application for cross-device connectivity with QR-code based device linking and KVM support.

Snapshot Browser

Browse timestamped data snapshots with a JSON viewer, source code display, and database management tools.

Log Viewer

Color-coded, filterable log viewer with tabular display for real-time monitoring and debugging of all data sources.

subcli

subcli equivalent

At the top level, subcli mirrors the same feature families as the desktop client.

See every command group

subcli --help

Connection workflows

subcli connection --help

Plugin workflows

subcli plugin --help

Pipeline workflows

subcli pipeline --help

VirtualGlass workflows

subcli vg --help

Operational tooling

subcli log --help

The GUI is stronger for visual composition and rich browsing.
subcli is stronger for repeatable operator workflows, support sessions, and automation.

Getting Started

When you launch Subjective, the application performs the following startup sequence:

Configuration Loading

Reads `subjective.conf` from the project root, resolving all paths for tools, logs, and user data.

Redis Initialization

Starts an embedded Redis server (or connects to an external one) for inter-process messaging between the UI and data source services.

Privacy Dialog

A one-time privacy consent dialog appears. You must accept to continue.

Data Source Manager

The local DataSourceManager service starts, registering all installed plugins and making them available for connections.

VirtualGlass Launch

The VirtualGlass overlay application launches automatically in the background.

System Tray

The Subjective icon appears in your system tray. Right-click it to access all features. The main Connections window is hidden by default.

Auto-Start Connections

After a 3-second delay, any connections marked with “Start at Startup” are automatically started.

subcli

subcli equivalent

The CLI equivalent of application startup is to inspect config, bring up services, and trigger autostart explicitly.

Inspect resolved configuration

subcli config show

Start embedded Redis

subcli service start --redis

Start the DataSourceManager

subcli service start --manager

Verify service state

subcli service status

Launch VirtualGlass

subcli vg start

Run all startup-marked connections

subcli connection autostart

The privacy dialog is GUI-only; subcli assumes you already have a valid local setup.
Use service start/status when you want to reproduce the startup path without launching the desktop UI.

System Tray Menu

The system tray icon is your primary entry point to all Subjective features. Right-click it to see the full context menu:

subcli

subcli equivalent

The tray is a launcher for visual tools. In subcli, you run the action directly instead of opening a window first.

Inspect connections instead of opening the main window

subcli connection list

Inspect pipelines instead of opening the pipeline editor

subcli pipeline list

Browse plugins instead of opening the Plugin Store

subcli plugin list

Open logs from the terminal

subcli log show --page 1

Browse recent snapshots

subcli snapshot list --limit 10

Start or stop VirtualGlass

subcli vg start
subcli vg stop

Generate a VirtualGlass link code

subcli vg link generate --device-name "Office Laptop"

Stop the local service stack

subcli service stop --all

There is no CLI equivalent for opening the hidden tray window itself; subcli skips the launcher step and performs the workflow directly.

Managing Connections

The Connections window is the central hub for configuring all your data source connections. It is divided into two main panes:

Left Pane: Data Source Repositories

The left pane contains the Connection Edit Form where you configure individual data source connections. Fields include:

Server

Select the target server (IP address) where data will be processed.

Data Source

Choose from installed data source plugins (populated dynamically from the server).

Connection Name

A user-friendly label for this connection.

Start at Startup

Check to auto-start this connection when the application launches.

Dynamic Fields

Each data source plugin provides its own configuration fields (API keys, paths, tokens, intervals, etc.).

Right Pane: Connections List

The right pane displays all configured connections. Each connection row shows:

Data source icon and name

Each row identifies the connection at a glance with its iconography.

Play/Stop button

Start or stop the data source process.

Progress bar

Shows processing progress for running data sources.

Metadata indicators

Timestamp of last run, plugin class name.

Bottom: Pipelines Section

Below the edit form, the Pipelines section lets you browse and select saved pipeline files (.pipe) to add them as executable pipeline connections in the list. Selecting a pipeline creates a SubjectivePipelineDataSource connection entry.

subcli

subcli equivalent

Everything you do in the Connections window has a direct or near-direct subcli path.

List every saved connection

subcli connection list

Search by name or keyword

subcli connection search github

List available managers/servers

subcli connection servers

List available datasource types

subcli connection types

Create a new connection

subcli connection create my_connection --datasource MyDataSourceType --server 127.0.0.1 --param key1=value1 key2=value2 --startup

Update connection parameters

subcli connection edit my_connection --param interval=60 enabled=true

Start or stop a connection

subcli connection start my_connection
subcli connection stop my_connection

Delete a connection

subcli connection delete my_connection

Run all startup-marked connections

subcli connection autostart

Datasource field names vary by plugin, so the exact --param keys come from the datasource type you are using.
The GUI shows progress bars inline; from subcli you typically pair connection commands with log and service commands.

Creating New Data Sources

Subjective allows you to create your own custom data source plugins. Use the “New DataSource” toolbar button to scaffold a new plugin project with all required files.

Create New Data Source — Figure 3: New Data Source dialog — Enter a name to scaffold a complete plugin template

Click “New DataSource” from the toolbar (grid icon with a plus sign).

Enter a name for your new data source in the popup dialog (e.g., “my_custom_api”).

Click OK — The system generates a complete Python plugin template under the plugins directory, including the data source class, setup.py, icon template, and documentation skeleton.

Edit the generated code to implement your custom data collection logic.

subcli

subcli equivalent

The desktop scaffold button maps directly to datasource generation and execution commands.

Scaffold a standard datasource

subcli datasource new my_custom_api

Scaffold a realtime datasource

subcli datasource new my_realtime_feed --realtime

Execute a datasource manually

subcli datasource execute my_custom_api --collect-metadata

The GUI wizard creates the template visually; subcli performs the same scaffold operation directly from the terminal.
Implementation work still happens in the generated Python files after scaffolding.

Plugin Store

The Plugin Store provides an App Store-like experience for discovering and installing data source plugins. Plugins are fetched from the Subjective Technologies GitHub organization and displayed in a searchable grid.

Features

Search

Filter plugins by name, class, or description using the search bar.

Star Ratings

Each plugin displays a community rating.

Install Status

Green “Installed” badge or blue “Install” button for each plugin.

Clear Cache

Purge the local GitHub API cache for fresh results.

Refresh

Force re-fetch all plugin data from GitHub.

Available plugins include connectors for: GitHub, GitLab, Gmail, YouTube, Evernote, SFTP, Google Drive, Dropbox, OneDrive, S3, Azure, Slack, Notion, MongoDB, Redis, Elasticsearch, PostgreSQL, MySQL, Kafka, RabbitMQ, and many more.

subcli

subcli equivalent

The Plugin Store search and catalog workflows map cleanly to plugin inspection commands.

List every available plugin

subcli plugin list

Search the catalog by keyword

subcli plugin search sftp

Search another integration family

subcli plugin search github

The GUI adds ratings and card browsing; subcli focuses on fast filtering and operator-friendly inspection.

Plugin Details & Installation

Clicking on any plugin card opens a detailed view with full information about the plugin:

Figure 5: Plugin Detail View for “Subjective Sftp” — showing class name, rating, description, and action buttons

Detail View Contents

Plugin Icon

Custom SVG icon for the data source.

Class Name

The Python class name (e.g., `subjective_sftp_datasource`).

Rating

Star rating with the total number of ratings.

Description

Full plugin description and capabilities.

Documentation

Rendered README content from the plugin's GitHub repository.

Download button

Install the plugin to your local plugins directory.

View on GitHub button

Open the plugin's source repository in your browser.

subcli

subcli equivalent

Use subcli to inspect plugin metadata, install it locally, and reload the manager catalog.

Show plugin details

subcli plugin info subjective_sftp

Install a plugin

subcli plugin install subjective_sftp

Remove a plugin

subcli plugin uninstall subjective_sftp

Refresh the plugin registry

subcli plugin reload

Opening the GitHub repository is still a browser action; subcli handles the operational install and reload path.

Pipeline Editor

The Pipeline Editor is a visual composition surface for designing production workflows. Teams build reusable automation by dragging connections from the left pane, wiring nodes on the workbench, and tuning execution settings in the right-side properties panel.

Updated screenshots below document the current interface and expected operator flow from discovery, to graph wiring, to final orchestration review.

Figure 6a — Connections Explorer + Canvas

Pipeline Editor - Updated View 1 — Figure 6a: Updated Pipeline Editor view — visual workspace with multiple connected data source nodes.

Figure 6b — Node Configuration Workflow

Pipeline Editor - Updated View 2 — Figure 6b: Updated Pipeline Editor view — node configuration panel and execution flow wiring.

Figure 6c — Multi-Stage Graph Composition

Pipeline Editor - Updated View 3 — Figure 6c: Updated Pipeline Editor view — expanded pipeline graph with multiple processing stages.

Figure 6d — Orchestration Layout Detail

Pipeline Editor - Updated View 4 — Figure 6d: Updated Pipeline Editor view — detailed node connections and orchestration layout.

Figure 6e — End-to-End Pipeline Wiring

Pipeline Editor - Updated View 5 — Figure 6e: Updated Pipeline Editor view — complete workflow composition with linked data paths.

Editor Layout (Three Panes)

Left Pane: Available Connections

A tree view of all configured connections grouped by server IP. Each server node shows an “Install Plugin” button to open the Plugin Store, and a “Create New Connection” option. Drag any connection item onto the workbench to add it as a pipeline node.

Center Pane: Pipeline Workbench

The visual canvas where you compose your pipeline. Nodes appear as icons representing their data source type. Connect nodes by dragging arrows between connection points (top/bottom/left/right). The workbench supports:

Zoom

Scroll wheel or Ctrl + + / -.

Pan

Middle-click drag.

Fit to View

Ctrl + F or the “Fit” button.

Reset Zoom

Ctrl + 0.

Delete Node

Select and press Delete.

Right Pane: Node Properties

When a node is selected on the workbench, this panel shows its editable properties including the connection name, data source parameters, filter expressions, and transform configurations.

Pipeline File Format

Pipelines are saved in a hybrid JSON format (.pipe) that combines:

Execution model

Node definitions, dependencies, parameters, filters, and transforms.

Visual layout

Node positions, connection points, and display names for the workbench.

Menu Bar Operations

Action	Shortcut	Description
New Pipeline	Ctrl + N	Clear the workbench and start a new pipeline
Open Pipeline	Ctrl + O	Load a .pipe or .spipeline file
Save Pipeline	Ctrl + S	Save to the current file (prompts for name)
Save As	Ctrl + Shift + S	Save with a new file name
Export as JSON	—	Export for use with SubjectivePipelineDataSource

subcli

subcli equivalent

The visual canvas has no one-to-one CLI replacement, but subcli covers the persistence and inspection workflows around pipelines.

List saved pipelines

subcli pipeline list

Inspect one pipeline by name or ID

subcli pipeline show worktwins_v1

Review available connection building blocks

subcli connection list

Drag-and-drop editing, node positioning, and arrow wiring remain GUI-only features.
subcli is the right companion when you want to script around pipelines or inspect them without opening the editor.

Loading & Saving Pipelines

Use Ctrl + O or File → Open Pipeline to load an existing pipeline from disk. The file dialog filters for .pipe and .spipeline files by default.

Load Pipeline Dialog — Figure 7: File dialog for loading pipeline files from the pipelines directory

Pipelines are stored by default under `com_subjective_userdata/com_subjective_pipelines/`. The editor supports three file formats:

Hybrid format (.pipe)

Contains both execution nodes and visual workbench layout.

Legacy format

Older .pipe files with workbench-only data (auto-upgraded on load).

JSON export (.json)

Flat execution-only format for SubjectivePipelineDataSource.

Recently opened files are tracked under File → Recent Files for quick access.

subcli

subcli equivalent

Use subcli when you want to create, inspect, or export saved pipeline definitions from scripts or remote shells.

Create a pipeline record from a JSON template

subcli pipeline create worktwins_v1 --from-file .\pipelines\worktwins_v1.json

Export a pipeline to JSON

subcli pipeline export worktwins_v1 --output .\exports\worktwins_v1.json

Inspect the stored pipeline payload

subcli pipeline show worktwins_v1

Opening a local file picker and maintaining a recent-files menu are GUI-only conveniences.

VirtualGlass & Device Linking

VirtualGlass is a companion C++ application that provides an overlay interface and cross-device connectivity. It launches automatically on startup and can be toggled by left-clicking the system tray icon.

Link VirtualGlass Dialog — Figure 8: VirtualGlass device linking dialog with QR code and linking code

Linking a Device

To pair a remote device with this computer, use Link VirtualGlass from the tray menu. This opens a dialog with a QR code and a text-based linking code:

Open the Link dialog from the tray menu: Link VirtualGlass.

Scan the QR code with your mobile device or enter the linking code manually on the remote device.

Click “Link Device” to complete the pairing process.

Link to Main Device

Use “Link to Main Device...” from the tray menu to connect this computer as a player to another computer acting as the main device. This enables KVM (keyboard-video-mouse) input sharing between machines using the `input_unified` tool. The connection is persisted and auto-restored on startup.

subcli

subcli equivalent

subcli covers the operational VirtualGlass lifecycle and both sides of the linking workflow.

Start or stop VirtualGlass

subcli vg start
subcli vg stop

Generate a link code on the main device

subcli vg link generate --device-name "Studio Tablet"

Connect a secondary device with a code

subcli vg link connect "<link_code>"

The GUI renders the QR code and tray affordances; subcli gives you the raw linking flow for terminal-based setup.

Log Viewer

The Log Viewer provides real-time monitoring of all data source processes. Logs are displayed in a color-coded table format with filtering capabilities.

Log Table Columns

Column	Description
Timestamp	When the log entry was recorded
Log_Type	Severity level (INFO, WARNING, ERROR, DEBUG)
Process	The data source or system component that generated the log
Code_Location	Source file and line number for debugging
Message	The log message content
Processing_Time	Execution duration for the logged operation

3D Performance Profiler

The Log Viewer includes a powerful 3D Performance Profiler accessible via the Charts tab. This tool parses log files to extract execution timing data and renders an interactive 3D surface chart that makes it easy to spot data source bottlenecks and performance regressions at a glance.

Chart Axes

Axis	Description
X — Operation Category	Groups of operations performed by the data source (e.g., network I/O, parsing, database writes). The top N categories are shown (configurable via the Top Categories field).
Y — Execution Time (ms)	The measured duration for each operation. Peaks in the surface indicate slow operations that are potential bottlenecks.
Z — Time Progression	Chronological progression showing how performance changes over time, revealing trends, spikes, or degradation.

Color Gradient

Green

Fast execution (healthy performance).

Yellow

Moderate execution time (potential concern).

Red

Slow execution (bottleneck detected).

How to Use the Profiler

Open the Log Viewer from the tray menu or toolbar, and select a log file for the data source you want to analyze.

Switch to the Charts tab at the top of the viewer.

Set the Top Categories count (default: 15) to control how many operation categories are displayed on the X-axis.

Click “Generate Performance Chart” to parse the log and render the 3D surface. The generated chart is saved as an HTML file under `com_subjective_userdata/log_charts/`.

Interact with the chart — rotate, zoom, and pan the 3D view to inspect specific areas. Click “Open in Browser” for a full-screen interactive view.

Tip: Use the profiler after running a data source to identify which operations consume the most time. Red peaks on the surface are your primary optimization targets. Compare charts from different runs to verify that performance improvements are effective.

Logs are stored in the directory configured by `LOG_PATH` (default: `com_subjective_userdata/com_subjective_logs/`). Select a log file from the dropdown at the top to view its contents. Use the filter controls to narrow down by severity, process name, or keyword.

subcli

subcli equivalent

The log viewer translates well to CLI filtering, but the charted profiler remains a GUI-first capability.

Show the default log page

subcli log show

Filter by severity

subcli log show --level ERROR --page 1

Inspect one day of logs

subcli log show --date 20260306

There is no direct CLI equivalent for the 3D performance profiler or HTML chart explorer.
For terminal triage, pair log filters with connection and service commands.

Snapshot Browser

The Snapshot Browser allows you to explore timestamped data snapshots captured by your data sources. Each snapshot contains structured data collected at a specific point in time.

Interface Layout

Left Panel

Chronological list of snapshot timestamps. Click any entry to view its contents.

Right Panel

A JSON viewer that renders the snapshot data with syntax highlighting. Supports switching between formatted and raw views.

Top Bar

Toggle Overlay Mode, Clear Viewer, and switch between Dark/Light mode.

Bottom Bar

Database statistics including total size, log size, and storage usage gauge (shown as a percentage circle).

Database Management

The bottom of the Snapshot Browser shows storage information and provides Backup and Trash buttons for both the database and logs. The circular gauge indicates the percentage of allowed storage used.

subcli

subcli equivalent

subcli can browse snapshot inventory and open a specific snapshot payload from the terminal.

List recent snapshots

subcli snapshot list --limit 20

Inspect one snapshot file

subcli snapshot show 2026_03_06_12_00_00-example-context.json

The visual JSON browser, overlay mode, and storage gauge remain richer in the GUI.

OnDemand Data Source Testing

The Chat with OnDemand Data Sources tool provides a live testing interface for interacting with running LLM-based data sources. It lets you send messages directly to any active chatbot connection and inspect responses in real time — useful for verifying that your AI data source connections are working correctly before integrating them into pipelines.

OnDemand Data Source Chat — Figure 11: Chat with OnDemand Data Sources — testing interface showing running LLM connections (Grok, Gemini, ChatGPT, Claude, Llama, Qwen) with a live chat panel

Supported LLM Data Sources

The tool auto-discovers all running OnDemand data sources. These are AI/LLM chatbot connectors that respond to messages on demand. Currently supported providers include:

GrokGeminiChatGPTClaudeLlamaQwen

Interface Layout

Left Panel: Running Data Sources

Lists all currently running OnDemand data source processes. Each entry shows:

Connection name

The user-defined label (e.g., `chat_gemini`).

Type

The plugin class handling the connection.

PID

Process ID and launcher PID for debugging.

Click any entry to select it as the active chat target. Use Refresh List to re-scan for newly started or stopped data sources.

Right Panel: Chat Interface

The main chat area shows the conversation with the selected data source. The header displays the active connection name and PID. Features include:

Message log

Timestamped connection events and message exchanges.

Attach Files

Send file attachments along with your message (for multimodal models that support it).

Clear Attachments

Remove queued file attachments before sending.

Message input

Type your test prompt and click Send.

Clear Chat

Reset the conversation history.

How to Use

Start your LLM connections from the Connections window by clicking the Play button on each chatbot data source you want to test.

Open the tool from the toolbar (OnDemand DataSource icon) or via the tray menu.

Select a running data source from the left panel — the tool connects automatically and shows a confirmation in the chat log.

Type a test message in the input field and click Send to verify the connection responds correctly.

Switch between data sources by clicking different entries in the left panel to test multiple LLMs in the same session.

subcli

subcli equivalent

The OnDemand chat tool maps directly to process discovery and message-send commands.

List running chat-capable datasources

subcli chat list-datasources

Send a text prompt to one datasource PID

subcli chat send 12345 "Summarize the current context"

Send a prompt with file attachments

subcli chat send 12345 "Review this file" --attach .\notes.txt .\image.png

The GUI keeps an interactive multi-message conversation panel; subcli is better for direct test prompts and scripted checks.

Configuration Reference

Subjective is configured via `subjective.conf` (or `subjective_linux.conf` on Linux). Key configuration options:

Key	Default	Description
USERDATA_PATH	com_subjective_userdata	Base path for all user data, plugins, snapshots, and logs
LOG_PATH	com_subjective_userdata/com_subjective_logs	Directory for log files
DATASOURCES_TEMP_STORAGE	com_subjective_userdata/com_subjective_data_sources_temp	Base path passed to the DataSourceManager so each service can create per-connection temporary storage
PIPELINES_PATH	com_subjective_userdata/com_subjective_pipelines	Directory for saved pipeline files
SNAPSHOTS_DIR	com_subjective_userdata/com_subjective_snapshots	Directory for data snapshots
REDIS_SERVER_IP	localhost	Redis server hostname
REDIS_SERVER_PORT	6379	Redis server port
REDIS_EMBEDDED	true	Use embedded Redis (recommended for single-machine setups)
CURRENT_THEME_SELECTED	theme_default.json	Active UI theme file
LOG_ENABLE_FILES	false	Write logs to individual files per source
LOG_ENABLE_TERMINAL_OUTPUT	true	Mirror log output to the terminal console
SUBJECTIVE_CLIENT_PATH	(auto-detected)	Override path to the VirtualGlass executable
KVM_KEYBOARD_PATH	(auto-detected)	Path to the KVM input_unified tool
GITHUB_TOKEN	(none)	GitHub personal access token for Plugin Store API calls
FFMPEG_PATH	(auto-detected)	Path to FFmpeg for multimedia processing plugins
RCLONE_PATH	(auto-detected)	Path to rclone for cloud storage plugins

Tip: Paths can be absolute or relative to the project root. Environment variables (`$HOME`, `%USERPROFILE%`) and `~` are expanded automatically. The application also performs recursive path resolution for tool binaries.

subcli

subcli equivalent

subcli can inspect and update the same runtime configuration values that the GUI depends on.

Show the full resolved config

subcli config show

Inspect one key

subcli config show DATASOURCES_TEMP_STORAGE

Change a config value

subcli config set LOG_ENABLE_FILES true

Inspect or change themes

subcli theme list
subcli theme set theme_default.json

Only the desktop client and subcli read subjective.conf directly; services receive configuration through runtime arguments.

Troubleshooting

Common Issues

VirtualGlass won't launch

Check the VirtualGlass log file in your logs directory (timestamped as *-virtual_glass-launcher.log). Verify that the executable path in SUBJECTIVE_CLIENT_PATH is correct, or let auto-detection find it under com_subjective_tools/subjective_client_desktop/build/.

Redis connection errors

If you see Redis connection errors, ensure REDIS_EMBEDDED=true in your config. The embedded Redis is recommended for local development. For external Redis, verify the host and port settings.

Plugin Store shows no plugins

This is usually caused by GitHub API rate limiting (60 requests/hour for unauthenticated access). Set a GITHUB_TOKEN in your configuration or environment to increase the limit to 5,000 requests/hour.

Data source doesn't appear in the dropdown

Ensure the plugin is properly installed (check the Plugin Store), then restart the DataSourceManager or use the Plugin Store's Refresh button. The dropdown is populated by querying the running DataSourceManager service via Redis.

Pipeline editor can't save

Check that the PIPELINES_PATH directory exists and is writable. The editor uses a fallback save mechanism if the pipeline persistence system module is unavailable.

subcli

subcli equivalent

When the GUI is failing, subcli is often the fastest way to isolate service, plugin, and configuration problems.

Check local service health

subcli service status

Read recent errors

subcli log show --level ERROR --page 1

Inspect an important config path

subcli config show SUBJECTIVE_CLIENT_PATH

Reload installed plugins after a fix

subcli plugin reload

If a datasource still does not appear after reload, verify the install state with subcli plugin info or subcli plugin list.