Utilities

System-level functions for opening files, running terminal commands, querying applications, and controlling the launcher window.

open

Open a URL or file with the default application, or a specific one.

import { open } from "@vicinae/api";

await open("https://vicinae.org");
await open("/path/to/file.pdf");
await open("/path/to/file.txt", "code");

runInTerminal

Run a command in a new terminal window. The arguments are not interpreted by a shell.

import { runInTerminal } from "@vicinae/api";

await runInTerminal(["journalctl", "--user", "-u", "vicinae", "-f"]);

To run a shell command, wrap it explicitly:

await runInTerminal(["/bin/bash", "-c", "echo $HOME"], { hold: true });

Options

Option	Description
`hold`	Keep the terminal open after the command finishes
`workingDirectory`	Set the working directory
`appId`	Override the application ID for the terminal window
`title`	Override the window title

Options are hints to the terminal emulator and may not be honored by all terminals. Vicinae follows the xdg-terminal-exec specification.

showInFileBrowser

Reveal a file or folder in the system file browser.

import { showInFileBrowser } from "@vicinae/api";

await showInFileBrowser("/path/to/file.txt");
await showInFileBrowser("/path/to/file.txt", { select: true });

trash

Move files to the system trash.

import { trash } from "@vicinae/api";

await trash("/path/to/file.txt");
await trash(["/path/to/a.txt", "/path/to/b.txt"]);

On Linux, Vicinae currently does not try to simulate a proper trash nor use any of the available ones (sometimes exposed by file managers). The files are immediately and permanently removed from the filesystem.

Applications

Query installed applications on the system.

import { getApplications, getDefaultApplication, getFrontmostApplication } from "@vicinae/api";

const apps = await getApplications();
const defaultApp = await getDefaultApplication("/path/to/file.pdf");
const frontmost = await getFrontmostApplication();

Each Application has id, name, path, and an optional icon.

The icon returned for an application, if any, should not be considered stable and should not be stored as-is. It is meant to be passed as an icon at runtime to any Vicinae API that accepts them.

closeMainWindow

Close the launcher window. Useful after performing an action that doesn't need further user interaction.

import { closeMainWindow } from "@vicinae/api";

await closeMainWindow();

showHUD

Close the launcher window and show a brief heads-up message.

import { showHUD } from "@vicinae/api";

await showHUD("Copied to clipboard!");

popToRoot

Reset the navigation stack to the root view of the current command.

import { popToRoot } from "@vicinae/api";

await popToRoot();

getSelectedText

Get the currently selected text. Often combined with Clipboard.paste to replace the selected text with something else.

import { getSelectedText, Clipboard } from "@vicinae/api";

const selected = await getSelectedText();
await Clipboard.paste(selected.toUpperCase());