Guth CLI

guth-cli is the headless companion to the Guth desktop file manager. It discovers UUIDv7-identified command plugins and dispatches them without a shell, making the same plugin tools available on desktop and headless Linux machines.

cargo install guth-cli
guth-cli plugins
guth-cli enable <plugin-uuid>
guth-cli sync -- help

Plugin manifests live in $XDG_DATA_HOME/guth/plugins, or ~/.local/share/guth/plugins when XDG_DATA_HOME is unset. The CLI does not persist plugin arguments, endpoints, sessions, or command output.

External plugins are trusted native commands, not sandboxed extensions. Guth CLI accepts only UUIDv7-named manifests and verified regular executables owned by the current user or root with safe permissions, then executes the already-verified file without a shell. Capabilities are descriptive declarations rather than permissions.

Installed plugins are disabled until enabled in Guth's plugin settings or with guth-cli enable <plugin-uuid>. Desktop and headless commands share the bounded $XDG_CONFIG_HOME/guth/enabled-plugins.conf state. Use guth-cli prune after removing plugins to discard stale enabled UUIDs.

Desktop GUI actions

Existing schema-1 command plugins remain unchanged. Schema 2 is an explicit, independently versioned contract for actions that Guth may place in a file context menu or the Ctrl+K Quick Actions palette:

{
  "schema": 2,
  "id": "019f6abc-1234-7abc-8def-0123456789ab",
  "name": "Example Tools",
  "version": "1.0.0",
  "executable": "/absolute/path/to/example-tools",
  "description": "Selection-aware example actions.",
  "capabilities": ["gui-actions"],
  "contributions": { "actions": { "protocol": 1 } }
}

Guth invokes the verified executable without a shell using exactly one of these argument lists:

--guth-action-protocol 1 probe
--guth-action-protocol 1 invoke

Rust plugins can use guth_cli::install_action_manifest(&manifest) to validate and atomically install the schema-2 manifest. On the executable side, parse_plugin_action_probe_request(std::io::stdin(), plugin_id) and parse_plugin_action_invoke_request(std::io::stdin(), plugin_id, &allowed_action_ids) perform the same bounded request validation Guth expects. Write exactly one response JSON object to standard output—send diagnostics and progress logging to standard error so the protocol response remains unambiguous.

Each call receives one versioned JSON object followed by a newline on standard input. A probe request includes protocol, plugin_id, operation: "probe", and context. The context contains current_directory plus a bounded selection; every path has presentation-only display text and authoritative lowercase unix_bytes_hex, and every selected target includes kind and an optional lowercase extension.

A successful probe writes one response object to standard output:

{
  "protocol": 1,
  "plugin_id": "019f6abc-1234-7abc-8def-0123456789ab",
  "actions": [{
    "id": "optimize-image",
    "label": "Optimize Image",
    "description": "Create a smaller optimized copy beside the source.",
    "category": "convert",
    "icon": "convert",
    "placements": ["context-menu", "command-palette"],
    "matcher": {
      "min_selection": 1,
      "max_selection": 16,
      "kinds": ["file"],
      "extensions": ["jpg", "jpeg", "png", "webp"]
    },
    "destructive": false,
    "confirmation": null
  }]
}

Allowed categories are tools, organize, convert, sync, and share; host-owned icons are plugin, tool, convert, sync, share, and archive. Matchers apply to every selected target. Destructive actions must set destructive: true and provide non-empty confirmation text; Guth presents that text in its own confirmation dialog.

An invocation request repeats the exact context and adds operation: "invoke" plus the validated action_id. Return a typed result:

{
  "protocol": 1,
  "plugin_id": "019f6abc-1234-7abc-8def-0123456789ab",
  "action_id": "optimize-image",
  "outcome": "completed",
  "message": "Optimized copy created",
  "refresh": true
}

Exit with status zero after writing any valid typed result, including "outcome": "failed" or "outcome": "cancelled". A non-zero exit status is reserved for process or protocol failure; Guth reports bounded standard-error diagnostics and does not parse standard output as a typed result in that case.

Outcomes are completed, cancelled, or failed; failed results require a message. refresh: true asks Guth to rescan both file panes. Identity, action IDs, paths, matchers, placements, strings, and response sizes are validated. Probes have a two-second deadline, invocations have a five-minute deadline, protocol I/O is capped at 48 KiB, selections at 256 entries, and each contributor at 32 actions. Plugin actions are still trusted native commands rather than sandboxed code, so users must explicitly enable the manifest before Guth probes it.