plugins

Plugins

Pre-alpha. Viewer plugins - the first kind - are in the current build, and rCommander ships twelve - viewers for JSON, XML, YAML, CSV, configuration files, shell scripts, batch files, PowerShell, diffs, logs, web code and SVG. Packers, file systems, connection types, columns and the other kinds come later, one stage at a time.

A plugin adds a file format to rCommander. It is a signed package (.rcplug) that runs in a sandbox: it has no file system, no network and no access to your passwords or keys - it sees only the file it is asked to show, and rCommander draws whatever it returns. Writing one is Plugin development.

The Plugins page

Configuration > Plugins... in the menu bar opens it, as does Settings, page Plugins. It has two tabs: Installed and Global settings (Ctrl+Tab switches them).

The tab Installed lists every installed plugin with its version, kind and state (On, Off, Suspended; bundled for one that came with rCommander, unsigned for one installed in development mode). Select a plugin to see who signed it, the files it shows, its versions, its own settings and its latest calls.

Install a plugin

1. Install... - pick the .rcplug file (the field beside it takes a path too).
2. The preview shows, before anything is written: name, version and author, the kind, the files the plugin claims and the views it offers, what it asks for, and how it is signed.
3. Install puts it in place; Cancel leaves everything as it was.

A first install runs at once. A newer version of an installed plugin runs from the next start; if it asks for more than the version before, the preview says what.

Trust a signing key

Every package is signed. A package signed by rCommander's own key, or by a key you trusted before, says Signed by a key you trust. A package signed by a key you have not seen shows the key's fingerprint: compare it with the one the plugin's author publishes, and only then install - installing from that preview trusts the key for the author's plugins from then on. A package that names a key id you trusted for another key, a revoked key or a withdrawn version cannot be installed, and neither can a package for a plugin you have installed that is signed by another key than the installed one: remove the installed plugin first if you trust the new signer. A plugin runs at most as many calls at once as its package declares. An unsigned package installs only in development mode (below).

Enable, disable, versions

• Disable switches a plugin off - the built-in viewer shows its files again - and Enable back on. Run plugins on the tab Global settings switches every plugin off at once.
• Versions lists what is installed. Roll back runs the previous version; Remove version removes one that is not running and not open in a viewer (in use).
• A plugin that crashes, hangs or runs out of memory three times within five minutes is Suspended: Resume lets it run again. Failures before a plugin is suspended sets the number (1-10).
• The plugin's settings are the plugin's own choices, saved with Save plugin settings.
• Latest calls shows what the plugin was asked and how each call ended.

Global settings

The tab Global settings holds what applies to every plugin:

Setting	What it does
Run plugins	Off: no plugin runs, and the built-in viewer shows every file.
Failures before a plugin is suspended	3 by default, 1-10.
Largest text a viewer plugin may write (MiB)	256 by default; the viewer shows what came up to it.
Show a viewer plugin's text in colour	Off shows a plugin's coloured text plain.
Extensions given to a plugin	Pairs such as csv=<plugin id>: that plugin shows the extension, ahead of what the plugins claim.
Development mode: accept unsigned plugins	For plugin authors only; unsigned plugins stay marked as such.

These settings decide which code runs, so an AI assistant over MCP can read the list of plugins (plugins_list) but never install, switch or change one.

Viewer plugins in the Lister and Quick View

F3 (Lister) and Ctrl+Q (Quick View) open a file with the plugin that claims it - by its extension, its first bytes and its size - unless rCommander shows the format itself (images, Markdown). Up to four plugins are asked in turn: the one Extensions given to a plugin names for the extension, then those that claim the extension, then those that claim how the file starts, each group by name. A plugin that turns the file down passes it to the next; if all turn it down, the built-in viewer shows it. The plugin runs in the background; Quick View moving on to the next file stops it. If a plugin fails or is suspended, the built-in viewer shows the file with a notice. Private keys, credential files and rCommander's own files are never handed to a plugin.

A plugin's document can offer several views - coloured text, a tree, a picture: 7 switches between them, as does the list in the Lister's title row; the first is shown first, the others are made the first time you switch to them. Text a plugin writes is the Lister's own text - wrap, search, selection, copy, hex and the text size all work on it.

Secret sources: passwords from a password manager

A secret source plugin lets a connection take its password, private key or passphrase from a password manager instead of rCommander's vault - see A secret from a password manager. It reaches its manager only on the one port of this computer its package names; the install preview shows it as net_http localhost:<port>, and installing is your confirmation. rCommander never asks for the password manager's master password: you unlock it in the manager itself.

Bitwarden

The Bitwarden plugin (a separate, paid plugin; not part of the zip) speaks to the Bitwarden CLI's local API. Set it up once:

1. Install the Bitwarden CLI (npm install -g @bitwarden/cli), point it at your server if you use Vaultwarden or a self-hosted Bitwarden (bw config server https://...) and sign in (bw login).
2. Unlock and start the local API in a console you leave open: $env:BW_SESSION = bw unlock --raw (PowerShell), then bw serve --hostname 127.0.0.1 --port 8087.
3. Install the plugin on the Plugins page and confirm its signing key.
4. Paste your licence key (one line starting with RCL1.) into the plugin's setting Licence key on the Plugins page and save. It is typed hidden and never shown to an AI assistant. Without a valid key the source shows no licence, in the Plugins list and under the connection, and hands out nothing. The key is checked by the plugin itself, offline - no server is asked.

Under a connection, Bitwarden (ready) then appears as a source. locked means Bitwarden is locked or signed out (bw unlock, bw serve again); not answering means bw serve is not running. Items are found by name, user name and address; passwords, SSH key items' private keys and one-time codes are read from them. Bitwarden keeps no key passphrase of its own.

While bw serve runs it answers every program on this computer, as Bitwarden's own documentation says: stop it (or bw lock) when you do not need it.

The bundled viewers

rCommander ships twelve viewer plugins. Each is installed at the first start and switched on; disable one on the Plugins page to get the built-in viewer back for its files. JSON, XML, YAML, CSV, configuration files and diffs offer two views, coloured text first and a tree on 7; the others colour the text only. All of them read a file once and keep only a small index, so files of hundreds of megabytes open without being held in memory. A file that is not valid UTF-8 shows � where its bytes are broken, and the colours stay on the right characters. A change to a viewer's own settings applies to the next file opened.

The JSON viewer

The JSON viewer is for .json and .geojson files. It is installed at the first start and switched on; disable it on the Plugins page to get the built-in viewer back. It offers two views:

• Coloured text (shown first) - the file coloured like an editor: keys, strings, numbers, true/false/null, punctuation and anything invalid each in its theme colour.
• Tree (press 7) - the structure to unfold: a key or [index] per node with its value, {n} or [n] for an object or list of n entries. Click a node, or Right and Left, to open and close it. A list of more than 1000 entries opens in ranges ([0..999], ...). Invalid JSON shows a first node naming the line and column of the first error.

It reads a file once and keeps only a small index, so a JSON file of hundreds of megabytes opens without being held in memory; colouring and unfolding read only what is on screen.

Its setting Format (Plugins page, the JSON viewer's settings): as is shows the file as it is written; pretty indents it, two spaces a level - a minified file of one long line becomes readable. A change applies to the next file opened.

The XML viewer

The XML viewer is for .xml, .xsd, .xsl, .xslt, .rss, .atom, .csproj, .vbproj, .vcxproj, .props, .targets, .nuspec, .resx, .xaml, .config, .manifest and .plist files (not .svg or .html).

• Coloured text - element names, attribute names and values, comments, <?...?> and <!DOCTYPE ...>, entities such as &, CDATA and anything invalid each in its theme colour; the text between tags stays plain.
• Tree (press 7) - one node per element, labelled with its start tag; an element that holds only text shows it as its value. Malformed XML shows a first node with the line and column of the error ("expected , found ").
• Format: as is, or pretty - one element per line, two spaces a level.
• A UTF-16 file opens in the built-in viewer.

The YAML viewer

The YAML viewer is for .yaml and .yml files - Docker Compose, GitHub workflows, Kubernetes and the like.

• Coloured text - keys, strings (quoted and block scalars | and >), numbers, true/false/null/~ and yes/no/on/off, comments, --- and directives, anchors &a, aliases *a and tags !!str each in their theme colour.
• Tree (press 7) - the mappings and sequences by their indentation; a [...] or {...} written on one line is one node with its text. A file with several documents shows document 1, document 2, ... Anchors and aliases are shown as written, never followed. Bad indentation or a tab in the indentation shows a first node with its line and column.
• No Format setting: YAML is shown as it is written.

The CSV viewer

The CSV viewer is for .csv, .tsv, .tab and .psv files.

• Coloured text - every column in its own colour, eight colours in turn, so a column is easy to follow down the file; a quoted field over several lines keeps its column's colour; a broken field (a quote never closed, text after the closing quote) shows red.
• Tree (press 7) - one row N per record, unfolding into its fields, each named by the header line (column N without one). More than 1000 rows open in ranges.
• Separator: auto, comma, semicolon, tab or pipe. Auto takes a tab for .tsv and .tab, a pipe for .psv, and otherwise the separator that appears equally often on every one of the first lines - so a German Excel file with decimal commas is split on its semicolons.
• First line is a header: auto (a header when none of its fields is a number), yes or no.
• Encoding: auto, UTF-8 or Windows-1252. Auto reads Windows-1252 when the file is not valid UTF-8, which is how Excel writes CSV on Windows - umlauts and € show correctly.

The shell script viewer

The shell script viewer colours sh, bash, zsh and ksh scripts: keywords, builtins and function names, variables, strings with the variables and $(...) inside them, heredocs, comments, numbers and operators; an unclosed quote shows red.

• It is offered for .sh, .bash, .zsh and .ksh, for .bashrc, .bash_profile, .profile and .zshrc, and for a file without an extension that starts with a shell's #! line (#!/bin/sh, #!/bin/bash, #!/usr/bin/env bash and the like - the full list is in the plugin's README). Any other file can be given to it under Extensions given to a plugin.
• Bytes that are not UTF-8 show as �. No settings.

The batch file viewer

The batch file viewer colours .bat and .cmd files the way cmd.exe reads them, upper or lower case alike: commands, if words and switches such as /a or /i, labels (also after goto and call), variables (%x%, %~dp0, %%i, !x!), strings, numbers, rem and :: comments, operators, redirections and comparisons. The text after echo stays plain except its variables; ^ continuations and ( ... ) blocks carry over lines.

• Encoding: auto, UTF-8, cp850, cp437 or Windows-1252. Auto reads UTF-8 when the file is UTF-8 and cp850 otherwise - batch files from a German Windows are written that way, so their umlauts show correctly.

The config viewer

The config viewer colours the small key-and-value formats: INI (.ini, .inf, .cfg, .conf), registry exports (.reg, UTF-16 read automatically), .env, .properties, .editorconfig, .gitconfig, .gitignore, .gitattributes, and TOML (.toml, Cargo.lock).

• Coloured text - sections, TOML tables and registry keys, keys, values, numbers, true/false/on/off/yes/no and TOML dates, registry types such as dword:, comments.
• Tree (press 7) - keys before the first section, then the sections with their keys; TOML tables nest by their dots, arrays of tables as [0], [1]; .env and properties are flat.
• Encoding: auto, UTF-8, UTF-16 LE or Windows-1252. Auto follows a byte-order mark, else reads UTF-8 when the file is, else Windows-1252.
• .env values are shown as they are, not hidden - the built-in viewer shows them too.
• .env.local and the like are not offered (their extension is local); give the extension to the config viewer under Extensions given to a plugin if you want them coloured.

The PowerShell viewer

The PowerShell viewer colours .ps1, .psm1 and .psd1: keywords, cmdlets and functions, variables, $true/$false/$null, types and attributes such as [CmdletBinding()], parameters and operators (-eq, -match ...), strings with their variables and $( ... ), here-strings, numbers with kb/mb, line and block comments; a string left open shows red.

• Encoding: auto (byte-order mark, else UTF-8 when the file is, else Windows-1252 - how Windows PowerShell 5.1 saves), UTF-8, UTF-16 LE, Windows-1252. A UTF-16 file without a byte-order mark needs UTF-16 LE.

The diff viewer

The diff viewer is for .diff, .patch and .rej, and for files that start with diff or a git format-patch header.

• Coloured text - added lines green, removed lines red, @@ hunk headers marked with the function name after them, file headers (diff --git, index, ---, +++, renames) stand out, a format-patch mail header is greyed like a comment. Unified, combined (merge) and context diffs.
• Tree (press 7) - one node per file with its path and +added −removed (new, deleted, renamed, copied or binary said beside it), the hunks under it with their line counts.
• A diff -u saved without an extension is recognised by its --- and +++ lines; a YAML file that starts with --- still opens in the YAML viewer, because its extension comes first. No settings.

The log viewer

The log viewer is for .log, .out and .err files up to 1 GiB.

• Error levels red (ERROR, FATAL, CRITICAL, ERR ...), warnings yellow (ochre in the light theme), INFO teal, DEBUG/TRACE muted; timestamps (ISO, syslog, Apache), IP addresses, URLs, paths, key=value and JSON keys, quoted strings, and Java, .NET, JavaScript and Python stack traces coloured.
• Level colour: word colours the level word, line the whole line of an error or warning and its stack trace.
• Encoding: auto, UTF-8, UTF-16 LE, Windows-1252.
• The text stops at Largest text a viewer plugin may write (256 MiB by default). Rotated logs such as app.log.1 are not offered (their extension is 1).

The web code viewer

The web code viewer colours HTML, XHTML, Vue, CSS, SCSS, LESS, JavaScript, TypeScript, JSX, TSX and PHP - also languages inside each other: scripts and styles in HTML, CSS and JavaScript in style and on... attributes, PHP anywhere in its page, code in template strings and JSX.

• Keywords, names of properties and attributes, strings and regular expressions, numbers, CSS units and colours, literals, comments, types and element names, function names, PHP variables and operators each in their theme colour.
• Minified files work; a line is coloured up to 64 KiB. No settings.
• Not .json (the JSON viewer) or .svg and .xml (the XML viewer).

The SVG viewer

The SVG viewer is for .svg and .svgz files.

• Picture (shown first) - the drawing rendered: paths, gradients, transformations, embedded pictures, and text in a bundled font (Lato), since the plugin sees no installed fonts. Zoom and fit work as for any picture; a drawing larger than Largest picture shown at full detail (Settings, Appearance, tab Viewer) is scaled down.
• Source (press 7, and 7 again for the picture) - the SVG coloured like the XML viewer's. It is written only when you first switch to it, so Quick View stays quick.
• Size: the longest side 512, 1024 (default) or 2048 pixels. Background: transparent, white or black.
• It never loads anything from outside the file: links to other files or web addresses are ignored, only pictures embedded in the SVG itself are drawn. A file nested more than 256 levels deep, one whose <use> references would expand beyond a million elements, or a .svgz that unpacks to more than 64 MiB is refused with a notice.