Component Manager (linxira-component-manager)
The UI calls itself Quick System Runtime Setup.
Why it exists
Below applications sits another layer: capability bundles, runtimes, toolchains and
domain workspaces. They have dependencies, exclusions and required members, so
installing them one pacman command at a time hides both the relationships and the
reason each package is there. linxira-component-manager turns that layer into an
expandable, Windows Features-style tri-state tree: ticking requests an install,
expanding shows the nesting, and the whole plan is visible before anything runs.
The GUI, TUI and CLI share one transaction core, and all four entry points (GUI, TUI,
CLI, agent) follow the same plan → confirm → apply chain.
Responsibility boundaries
It owns: the selection UI for Catalog v3 bundle trees (GUI, TUI, CLI), node metadata and selection previews, and the plan display before confirmation.
It does not own:
- Package name expansion. It never turns component IDs into package names and never invokes a package manager.
- Planning, confirmation or privileged apply. Those belong to Components.
- Removal. Phase 1 installs ready package targets only.
- Metadata. Bundles, roles and selection policies come from the catalog.
The delegated transaction is the same chain for all three entry points and
belongs to Components: write the selection document and run plan,
show the immutable request-plan.json, run
confirm --catalog ... --plan ... --output-dir ... after confirmation, and, when
directPackageTargets is non-empty, run pkexec apply --confirmation .... Receipts
are written by the backend under /var/lib/linxira/components/receipts.
No entry point escalates by itself: the GUI, the TUI and the CLI never call
sudo, never run pacman, never write receipts and never expand component IDs into
package names. Elevation can only come from pkexec, and only for apply.
How to use
Graphical interface
linxira-component-manager # default catalog
linxira-component-manager --catalog ./catalog-v3.json
linxira-component-manager --select component-fish # preselect a leaf, repeatable
It looks for /usr/share/linxira/catalog/catalog-v3.json, then
/usr/share/linxira/catalog/catalog.json. With neither, it opens empty; Ctrl+O
chooses a file and Ctrl+S saves the selection JSON. --select ID only preselects:
the transaction still happens in the window. Welcome's Terminal page uses this to hand
over a chosen shell.
Only top-level bundles whose surface is components are shown (an omitted surface
means components). The tabs show node details, a live selection JSON and the backend
plan. Plan with linxira-components performs a fixed flow:
- Write the complete
org.linxira.component-selection.v1document into a private temporary directory. - Run
linxira-components plan --catalog ... --selection ... --output-dir .... - Show the immutable
request-plan.json, including separate ready package targets and pending/unsupported summaries. - After your confirmation, run
linxira-components confirmagainst that exact plan. - If
directPackageTargetsis non-empty, runpkexec linxira-components apply --confirmation ....
A plan with no direct package targets (only pending or unsupported leaves) is confirmed
without requesting pkexec. Pending and unsupported leaves are never applied.
TUI
linxira-component-manager --tui
linxira-component-manager --tui --catalog ./catalog-v3.json
Keys: arrows (or k/j) move, space toggles, a selects or clears all, Enter creates
the plan and asks for confirmation, q or Esc quits. Authorization defaults to auto:
running as root applies directly, otherwise it uses pkexec.
Command line
linxira-component-manager list
linxira-component-manager list --json
linxira-component-manager status component-fish
linxira-component-manager status component-fish --json
linxira-component-manager install component-fish --dry-run
linxira-component-manager install component-fish --yes
linxira-component-manager --catalog ./catalog-v3.json install component-fish
listshows availablecomponentandapplicationleaves and reads installed states fromlinxira-components inventory; when the backend is unavailable the state isunknown.statustakes one or more leaf IDs.installuses the sameplan → confirm → applychain.--dry-runprints only the planned package targets,--yesskips the interactive prompt (for agents), and--jsonemits machine-readable output. Pending items that cannot be installed are reported and skipped.- Exit codes:
0success,2selection or plan rejected (this includes an unusable catalog),3authorization or apply failure,64no subcommand given (help is printed).
When root is needed
The default authorization mode is auto: as root, apply runs directly; as a normal
user, pkexec asks Polkit for authorization. Planning and confirmation never
elevate. Do not wrap the commands in sudo and do not start the GUI as root — that
bypasses the Polkit prompt; the only elevation path this project defines is
linxira-components through Polkit.
Known limitations
- Phase 1 installs only. Ready package targets install; removal is not supported.
- Pending and unsupported leaves are listed before confirmation and are never applied.
- There is no
--component, profile/application, package-manager, remove or shell fallback — these are deliberately absent, not merely undocumented. - It consumes Catalog v3 directly and does not translate v2 profiles or package arrays. Direct or indirect cycles in the bundle graph are rejected.
- Required leaves are locked and explained;
exclusiveclears sibling alternatives;boundedrejects a change beyondmaxSelectedinstead of silently truncating. - Without a usable catalog the CLI fails and asks for
--catalog PATHor an installedlinxira-catalog.
Further reading
A complete nested example is in examples/catalog-v3.example.json in the repository.
The transaction shape is described under Components; implementation
lives in
linxira-component-manager.