AbraFlexi TUI v1.2.0

A terminal user interface for abraflexi-cli, built with the Turbo Vision (tvision) library.

Latest Release: v1.2.0 - Enhanced UX, Makefile, and Documentation

Features

Status screen: configured connection info and server/company reachability (abraflexi-cli status)
Company list: all companies on the configured server (abraflexi-cli list-companies)
Evidence browser: all AbraFlexi evidence catalogues (abraflexi-cli list-evidences); Enter/double-click opens its record list
Generic record browser: one evidence-parameterized list/detail screen that works for any AbraFlexi evidence, with editable filter, columns, limit and order fields
Record detail: embedded field-by-field panel that follows the highlighted row, fetching the full record on Enter
Record creation: a JSON payload editor pre-annotated with the evidence's mandatory fields, with Dry-Run, Submit and a Force checkbox
Record edit and delete: the list can open the current record as JSON (record update) and remove it after confirmation (record delete)
Evidence structure: columns, relations and labels for the open evidence (record properties), from the record list or F2 in the evidence browser
Find: search one evidence, or evidence names when the evidence field is empty
Query: raw REST call (method, path, optional body) through abraflexi-cli query
Changes API: status, enable/disable, and webhook register/unregister
Server profiles: several AbraFlexi servers saved in ~/.config/abraflexi-tui/servers.json (mode 0600), switched from the Servers screen, with either a password or a session token
Request URL: the status line shows the AbraFlexi URL implied by the current abraflexi-cli call. Click that address, or use Alt+B / AbraFlexi → Browser QR, to show a QR code of the same address opened in the web interface (without .json or a query string)

PDF preview, company backup/restore/clone, the custom-button designer and a webhook HTTP listener stay in Flexplorer. They need a browser or an HTTP endpoint.

Keyboard Reference

Global

Key	Action
`Alt+A`	Open the AbraFlexi menu
`Alt+S`	Status
`Alt+C`	Companies. Type to narrow by database name, name or status. Enter chooses the company; it then appears on the status line
`Alt+E`	Evidences
`Alt+V`	Servers
`Alt+Q`	Query
`Alt+F`	Find. The evidence field narrows the catalogue as you type; Tab copies the highlighted path, Enter opens it
`Alt+G`	Changes API
`Alt+B`	QR code of the web address currently shown on the status line
`Alt+H`	Help menu
`Alt+W`	Window menu
`F1`	About, with links to the libraries and utilities
`Alt+X`	Quit
`F6` / `Shift+F6`	Next / previous window
`Ctrl+F5`	Move or resize the active window
`Alt+F3`	Close the active window
`F10`	Menu

Window menu

Lists, record windows and the evidence browser take part in tiling. Dialogs do not.

Command	Action
Tile	Split the open windows across the desktop
Cascade	Stack them with a stepped offset
Minimize all	Shrink every open window to a title bar along the bottom
Restore	Put minimized windows back
Close all	Close tiled windows and minimized title bars
Zoom	The frame's zoom control fills the desktop

Evidence Browser

Key	Action
`↑/↓`, mouse wheel	Move selection
Type	Narrow the list by path, name or description. Backspace deletes the last character
`Enter`, double-click	Open the record list for the selected evidence
`F2`	Columns, relations and labels of the selected evidence. Type to narrow that structure list

Record List

Key	Action
Type, Find	Narrow the rows already loaded, by the visible columns. Diacritics are ignored. Backspace deletes the last character
`↑/↓`	Move selection (updates the detail panel from already-fetched row data). Works while Find is focused
`Enter`, double-click	Fetch and show the full record in the lower pane (`record <evidence> show <id>`)
`F4`, Preview	Open a read-only window. A document shows its header and line items, with Filter and Sort; anything else shows the field list. A second Preview of the same id brings that window forward
`F5`	Re-run the list query with the current filter/columns/limit/order
`F2`	Evidence structure (columns, relations, labels)
Filter / Columns / Limit / Order fields	Map 1:1 to `record <evidence> list -f -c -l -o`. Columns and Order suggest matching field names in the detail pane as you type
Refresh / New / Edit / Delete / Info / Preview	Reload, create, edit the selected row, delete it after confirmation, open the structure window, or open a read-only preview

Document preview

F4 on an invoice opens its line items. On an address-book row it opens that company's contacts (jmeno, prijmeni, email, tel). Filter and Sort apply to that listing. Typing while the list is focused narrows the loaded rows; the text is shown on the status line and Esc clears it. A company with no contacts shows no Contacts.

Control	Action
Filter	Dialog for an item filter, for example `nazev BEGINS 'A'`
Sort	Dialog for item order, for example `nazev@A` or `sumCelkem@D`
Refresh, `F5`	Reload the line items of this document

New Record

Key	Action
Edit the JSON text area	The record payload for `--data`
`Dry-~R~un`	`record <evidence> create --dry-run --data=...`
`~S~ubmit`	`record <evidence> create --data=...`
Force checkbox	Adds `--force` (skip mandatory-field validation)
`Format`	Pretty-print the JSON
`Cancel` / `Esc`	Close without creating

Edit Record

Key	Action
Edit the JSON text area	Payload sent as `record <evidence> update <id> --data=...`
`Dry-Run` / `Save`	Same dry-run and submit flow as New Record
`Format`	Pretty-print the JSON

Find (`Alt+F`)

Key	Action
Evidence empty	Filter evidence names from `list-evidences`
Evidence filled	`record <evidence> search --query=...`
Open	Empty id opens that evidence's record list; otherwise shows the record

Query (`Alt+Q`)

Key	Action
Method / Path / Body	`abraflexi-cli query <path> --method=... --body=...`
JSON / XML	Preferred body highlighting. The choice is saved and shown on the status line
Format	Pretty-print the body as JSON or XML
Send	A relative path is sent under `/c/<company>/`
Zoom	The frame's maximize control fills the desktop; the editor grows with it

Changes (`Alt+G`)

Key	Action
Enable / Disable	`abraflexi-cli changes enable` or `disable`
Register / Unregister	Add a webhook URL, or remove the selected hook

Servers

Key	Action
`Add` / `Edit` / `Delete`	Change saved server profiles
`Set Active`, Enter, double-click	Use that profile and open the status dialog
`Get Token...`	Exchange the typed login and password for an `authSessionId` (not written to disk until OK)
Password / Token	Password sends `ABRAFLEXI_LOGIN`/`ABRAFLEXI_PASSWORD`; token sends `ABRAFLEXI_AUTHSESSID` only

Prerequisites

abraflexi-cli installed and available on PATH (or pointed to via --cli=/ABRAFLEXI_TUI_CLI)
A C++17 compiler, CMake ≥ 3.16, libncurses-dev (or libncursesw5-dev on older distributions), nlohmann-json3-dev

Installation

From Source

git clone --recurse-submodules https://github.com/VitexSoftware/abraflexi-tui.git
cd abraflexi-tui
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
sudo cmake --install build

Debian Package

git submodule update --init --recursive
dpkg-buildpackage -us -uc
sudo dpkg -i ../abraflexi-tui_*.deb

Usage

abraflexi-tui

The application opens with the AbraFlexi menu. Use Alt+S/Alt+C/Alt+E/Alt+V or the mouse to navigate.

On the first start, if ~/.config/abraflexi-tui/servers.json does not exist yet, a default profile is imported from --envfile= when that file contains ABRAFLEXI_URL, otherwise from ABRAFLEXI_* variables already in the environment. When neither source defines a server, the public demo is saved and activated: https://demo.flexibee.eu:5434, login winstrom, company demo. If a profile is already active, the Status dialog opens at startup. If no profile is active, the Servers dialog opens so a configuration can be chosen. Later runs use the saved profile. --envfile= is still forwarded to abraflexi-cli when no profile is active.

To run against a development checkout of abraflexi-cli instead of a system install:

ABRAFLEXI_TUI_CLI=/path/to/abraflexi-cli/bin/abraflexi-cli \
    abraflexi-tui --envfile=/path/to/abraflexi-cli/.env

Project Structure

abraflexi-tui/
├── CMakeLists.txt
├── include/abraflexitui/
│   ├── TV.h                 # Shared tvision Uses_ macro list + <tvision/tv.h>
│   ├── CliClient.h           # fork+execvp process runner + JSON wrapper
│   ├── DisplayUrl.h          # Status-line URL built from CLI arguments
│   ├── ProfileStore.h        # ~/.config/abraflexi-tui/servers.json
│   ├── SimpleListViewer.h    # Read-only TListViewer over a vector<string> of rows
│   ├── JsonFormat.h          # Small JSON -> display-string helpers
│   ├── Commands.h            # App-wide command ids
│   ├── AppShell.h            # TApplication subclass, menu bar, status line
│   ├── AppStatusLine.h       # Status line with the current request URL
│   ├── ServerConfigView.h    # Saved server profiles
│   ├── StatusView.h
│   ├── CompanyListView.h
│   ├── EvidenceListView.h
│   ├── RecordDetailView.h
│   ├── RecordListView.h      # The generic, evidence-parameterized browser
│   └── RecordCreateForm.h
├── source/                   # One .cpp per header above
├── tools/cliclient_check.cpp # Standalone CliClient smoke test (no terminal needed)
├── vendor/tvision/           # tvision, as a git submodule
├── man/abraflexi-tui.1
└── debian/                   # Debian packaging

Architecture

abraflexi-tui never talks to the AbraFlexi REST API directly. CliClient (include/abraflexitui/CliClient.h) runs abraflexi-cli via fork()+execvp() with an argv vector (never a shell string), always appending --format=json, and parses the result with nlohmann/json. Schema and validation stay in abraflexi-cli. Connection settings live in the TUI as named profiles (~/.config/abraflexi-tui/servers.json, mode 0600, plaintext, same level as a .env file) and are injected into the child as ABRAFLEXI_* variables. Password profiles set login and password and blank ABRAFLEXI_AUTHSESSID. Token profiles set ABRAFLEXI_AUTHSESSID and blank the password variables. The status line shows an approximate REST URL for the call in progress (buildDisplayUrl).

A session token expires if it is not kept alive. This version does not ping keep-alive in the background (FlexiBee expects that about once a minute). When a token stops working, open the profile and use Get Token... again.

Unlike a per-entity command-line tool (compare multiflexi-cli, which has one Symfony-console subcommand per entity), abraflexi-cli exposes a single generic record <evidence> list|show|create command parameterized by evidence name at runtime. abraflexi-tui mirrors that: there is one evidence-parameterized RecordListView/RecordDetailView/RecordCreateForm set, not a source file per AbraFlexi evidence type (there are close to 250). Adding support for a new evidence requires no code changes at all — it just shows up in the Evidence browser.

Update/Delete are intentionally not implemented, because abraflexi-cli record does not implement them either.

Development

cmake -B build && cmake --build build -j"$(nproc)"   # Build
./build/abraflexi-tui-cliclient-check <cli-path> [envfile] -- status  # CliClient smoke test
./build/abraflexi-tui-profile-check                                  # Profiles, display URL, env injection

There is no automated UI test suite — tvision apps take over the terminal, so verification is manual (see the man page's EXAMPLES section). The abraflexi-tui-cliclient-check binary exercises the process-spawning and JSON-parsing logic in isolation, without starting the terminal event loop.

Using Makefile (Recommended)

The project includes a comprehensive Makefile that simplifies common tasks:

make              # Build the project
make run          # Build and run
make test         # Run tests
make install      # Install system-wide
make clean        # Clean build artifacts
make help         # Show all available targets

See the Makefile section below for complete documentation.

Recent UX Improvements

The latest version includes significant ergonomy and user experience enhancements:

Edit Dialog Improvements

Feature	Description
Tab Navigation	Use `Tab` and `Shift+Tab` to navigate between fields
Real-time Validation	Fields are validated as you type with visual error indicators
Field Type Hints	Labels now show type information (dates, numbers, relations, etc.)
Validation Summary	Clear error messages shown before form submission
Improved Field Ordering	Mandatory fields appear first, then alphabetically sorted

Supported Field Types with Validation

Type	Format	Validation
Date	`YYYY-MM-DD`	Validates format and logical dates (including leap years)
Datetime	`YYYY-MM-DD HH:MM:SS`	Validates format and time ranges
Integer	Numeric	Validates integer format
Float	Decimal	Validates floating-point format
String	Text	Validates maximum length constraints
Relation	Reference	Pick from related records with dialog
Logic	Boolean	Checkbox for yes/no values

Validation Error Indicators

Visual Feedback: Red exclamation mark (!) appears next to fields with errors
Error Messages: Clear, user-friendly messages referencing field titles (not just technical names)
Pre-submission Check: All validation errors are summarized before form submission

Package Information

Section: utils
Priority: optional
Maintainer: Vitex Software info@vitexsoftware.cz
Homepage: https://github.com/VitexSoftware/abraflexi-tui
Runtime dependency: abraflexi-cli

License

MIT License — see LICENSE.

Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Makefile Reference

The project includes a comprehensive Makefile that provides convenient targets for building, testing, and running:

Common Targets

Target	Description
`make`	Build all targets (default)
`make build`	Build the project
`make clean`	Remove build directory
`make install`	Install system-wide
`make uninstall`	Remove installed files
`make run`	Build and run the application
`make test`	Run all tests
`make help`	Show all available targets

Configuration Options

Variable	Default	Description
`BUILD_DIR`	`build`	Build directory
`BUILD_TYPE`	`Release`	Build type (`Release` or `Debug`)
`INSTALL_PREFIX`	`/usr/local`	Installation prefix
`NPROC`	auto-detect	Number of parallel build jobs

Examples

# Debug build
make BUILD_TYPE=Debug

# Install to home directory
make install INSTALL_PREFIX=$HOME/.local

# Run with 4 parallel jobs
make NPROC=4

Complete Target List

Run make help to see the complete list of available targets, including:

Test targets: test, test-cliclient, test-profile, test-integration
Development targets: pot-update, update-po, clean-translations
Package targets: package, package-source
Information targets: version, check-deps
Git helpers: git-pull, git-status

Next Steps and Future Enhancements

Short-term Roadmap (Priority: High)

Enhancement	Description	Status
Auto-save Drafts	Automatically save form state to prevent data loss	Planned
Field Auto-complete	Suggest values for relation fields and known enumerations	Planned
Field Descriptions	Add tooltips/help text for schema fields	Planned
Bulk Edit	Edit multiple records simultaneously	Planned

Medium-term Roadmap (Priority: Medium)

Enhancement	Description	Status
Date Picker	Calendar-based date selection dialog	Planned
Input Masks	Pattern-based input for structured data (phone, email, etc.)	Planned
Undo/Redo	Field-level change history with Ctrl+Z/Ctrl+Y	Planned
Field Grouping	Logical grouping of related fields with visual separators	Planned
Bulk Import	Import records from CSV/JSON files	Planned
Export Templates	Save and reuse export configurations	Planned

Long-term Roadmap (Priority: Low)

Enhancement	Description	Status
Custom Themes	User-configurable color schemes	Idea
Keyboard Macros	Record and replay keyboard sequences	Idea
Multi-language Spell Check	Spell checking for text fields	Idea
Offline Mode	Cache data for offline browsing	Idea
Plugin System	Extensible architecture for custom evidence types	Idea

Technical Improvements

Area	Description	Status
Test Automation	Automated UI test suite using terminal emulation	Research
Performance Profiling	Identify and optimize slow operations	Research
Memory Optimization	Reduce memory usage for large datasets	Research
CI/CD Pipeline	GitHub Actions for automated builds and releases	Planned

Contributing Guidelines

We welcome contributions! Please focus on:

User Experience: Improve keyboard navigation, field editing, and validation
Performance: Optimize data loading and rendering
Accessibility: Ensure the TUI works well with screen readers
Internationalization: Add translations for new languages
Documentation: Improve user and developer documentation

Getting Started

# Fork the repository
git clone https://github.com/VitexSoftware/abraflexi-tui.git
cd abraflexi-tui

# Build the project
make

# Run tests
make test

# Make your changes and submit a PR

Code Review Checklist

Code follows existing style and conventions
All new features have keyboard navigation
Error messages are user-friendly
Changes are backward compatible
Documentation is updated
Tests pass (if applicable)

Support

For issues and questions visit the GitHub repository or contact Vitex Software at info@vitexsoftware.cz.

Name		Name	Last commit message	Last commit date
.claude		.claude
.kdev4		.kdev4
debian		debian
include/abraflexitui		include/abraflexitui
man		man
po		po
source		source
tools		tools
vendor		vendor
.gitignore		.gitignore
.gitmodules		.gitmodules
CMakeLists.txt		CMakeLists.txt
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
abraflexi-tui.kdev4		abraflexi-tui.kdev4
abraflexi-tui.svg		abraflexi-tui.svg
screenshot.png		screenshot.png

Latest commit

History

Folders and files

Repository files navigation