Workspace files

Every workspace can be edited as plain text, much like VS Code's settings.json. Use it to change many shortcuts at once, keep your setup in a dotfiles repo, or share a workspace with someone else.

Open the file view

1. Open Settings → Workspaces and click a workspace.
2. In the dialog's top-right corner, switch from the list icon (Edit visually) to the { } icon (Edit as a file). Rovyl remembers your choice for next time.
3. Edit the text, then press Apply or Ctrl+S.

Next to Apply you'll find:

• ?: opens this page.
• Copy: copies the whole file to the clipboard.
• Revert: throws away your edits and reloads the saved workspace.

A dot next to workspace.jsonc means you have unapplied edits. Clicking Done, closing the dialog, pressing Escape or switching back to the visual view applies them first. If the file has an error, the dialog stays open and the error bar shows the line. Click the bar to jump there. After applying, Undo in the toast restores the workspace as it was.

Syntax

The file is JSON with two relaxations, the same ones VS Code allows (JSONC):

• Comments: // to the end of the line and /* blocks */.
• Trailing commas after the last item in a list or object.

Everything else is ordinary JSON: keys and text go in double quotes, and true/false have no quotes.

Rovyl doesn't store comments or formatting. After you apply, the text is rewritten in its standard form.

Workspace keys

The file is one object that describes a single workspace.

Some things aren't in the file on purpose. The number key comes from the workspace's position (the first workspace gets 1), so to change it, drag the card. Which workspace is current is set with the check button in the visual view.

Shortcut keys

Every entry in shortcuts is an object with a type. Each type accepts its own set of keys. A key that type doesn't accept is an error rather than being ignored, so a typo like "lanch" is caught instead of doing nothing.

"type": "app": an application

target is what Windows launches. It can be:

• A path to an .exe, .lnk, .bat or .cmd file, such as "C:\\Program Files\\App\\app.exe". If the path contains spaces, you can wrap it in escaped quotes and add arguments after it: "\"C:\\Program Files\\App\\app.exe\" --profile work".
• A Store or Start menu app ID: "shell:AppsFolder\\Microsoft.WindowsTerminal_8wekyb3d8bbwe!App". Apps you add from the installed-apps list are stored this way. To find an ID, run Get-StartApps in PowerShell.

Environment variables such as %LOCALAPPDATA% are expanded.

"type": "url": a website

target is an http:// or https:// address. If you leave out the scheme, https:// is added, so "github.com" becomes "https://github.com". Other schemes are rejected. The page opens in your default browser.

"type": "folder": a folder

target is a folder path, and it opens in File Explorer. Environment variables are expanded, so "%USERPROFILE%\\Downloads" works on any PC. This type has no other keys.

"type": "file": a document

target is the path to any file. It opens in whichever program Windows uses for that file type, so a .xlsx opens in Excel and a .pdf in your PDF reader. Environment variables are expanded. This type has no other keys, including no launch mode, because Windows picks the program.

"type": "command": a command line

target is a command line, passed to the shell exactly as written, including quotes, &&, ; and pipes. Use the chosen shell's own syntax for variables: $env:USERPROFILE in PowerShell, %USERPROFILE% in Command Prompt.

"type": "group": a submenu

A group has no target. It opens a second wheel containing its items, and the hub takes you back.

Icons

A workspace and each of its shortcuts can show a glyph from the built-in set or a picture of your own. You can set either one in Settings or in the file.

Choose an icon in Settings

For a workspace, click the icon square next to its name. For a shortcut, click its pencil, then click the Icon field. The dialog has two tabs:

• Glyph: search the built-in set by name, or by an English word such as work, time or home.
• Picture: use an image of your own, or any icon Windows has. Click Browse…, drop a file on the dashed area, or press Ctrl+V to paste a copied picture (a screenshot, for example) or a copied file path.

The Picture tab accepts these files:

Under Windows icons, the shell32.dll, imageres.dll and ddores.dll buttons open the icon libraries that come with Windows, so you don't have to browse to System32.

Rovyl trims empty transparent edges and scales every picture to match the icons it finds on its own, so custom icons line up with the rest of the wheel. It also keeps its own copy, so moving or deleting the original file later doesn't change the icon.

Default undoes your choice. An app, file or website gets back the icon Rovyl found for it, and a folder, command or group gets back its standard glyph.

Icons in the file

icon is the name of a Lucide icon in PascalCase: "Rocket", "FolderGit2", "TerminalSquare". Convert Lucide's names from kebab-case (folder-git-2 becomes FolderGit2). An unknown name falls back to a generic glyph.

iconFile is the full path to a picture, an icon file or a program, and accepts the same file types as the Picture tab. Environment variables such as %SystemRoot% are expanded. To use an icon other than the first one in a program or DLL, add a comma and its number, counting from 0. This is the format Windows uses for icon locations: "%SystemRoot%\\System32\\shell32.dll,4" is the fifth icon. In the Picture tab's grid, hold the pointer over an icon to see its number. A negative number is a resource ID instead (shell32.dll,-16769).

• If you leave out icon, the type's default glyph is used: app → AppWindow, url → Globe, folder → Folder, file → File, command → TerminalSquare, group → Folder.
• Apps, files and websites find a picture on their own: the program's icon, the file type's icon or the site's favicon. If you set icon to a glyph other than the default, that glyph is shown instead. Remove the line to get the found picture back.
• iconFile takes priority over both. When it's set, icon is used only if the picture can't be loaded.
• Removing iconFile removes the picture. The one exception is a picture you pasted in Settings: it has no path, so it isn't written to the file, and it stays until you change it in Settings.
• The file is read when you apply. If it's missing or can't be used, a message says so and the glyph is shown instead.

Share and migrate

The file holds only what you'd type. It leaves out internal IDs, the machine's icon cache and the number key, so the same text works on any PC. A custom picture is written as the path it came from (iconFile), never as Rovyl's own copy of it.

1. Export: open the workspace, switch to the file view and click Copy. Save or send the text.
2. Import into a new workspace: in Settings → Workspaces, click New workspace, open it, switch to the file view, replace the text with what you received, and apply.
3. Replace an existing workspace: paste over its file and apply. Undo in the toast brings the old one back.

When you apply a file, every shortcut whose type and target are unchanged keeps its identity and its extracted icon, even if you renamed or moved it. For groups, the name is used instead of the target. A picture named in iconFile is kept as long as the path stays the same. New apps, files and websites have their icons fetched right after you apply, and a new or changed iconFile is read at the same time.

Paths are specific to each PC. Prefer %USERPROFILE%, %LOCALAPPDATA% and shell:AppsFolder\\… IDs over hard-coded user folders so a shared file works for the person receiving it. The same goes for iconFile: %SystemRoot%\\System32\\imageres.dll exists on every PC, a picture in your Downloads folder doesn't.

To move everything at once (all workspaces plus every preference), use Settings → Advanced → Export settings and Import settings instead.

Full example

// Rovyl workspace. Reference: https://rovyl.arshitvaghasiya.com/docs
{
  "name": "Dev",
  "icon": "Code",
  "enabled": true,
  "shortcuts": [
    {
      "type": "app",
      "name": "VS Code",
      "target": "%LOCALAPPDATA%\\Programs\\Microsoft VS Code\\Code.exe",
      "launch": "reuse",
      "recents": true,
      "terminalForRecents": true,
      "terminalCommands": ["git pull", "npm run dev"]
    },
    {
      "type": "app",
      "name": "Terminal",
      "iconFile": "%USERPROFILE%\\Pictures\\Icons\\terminal.png",
      "target": "shell:AppsFolder\\Microsoft.WindowsTerminal_8wekyb3d8bbwe!App"
    },
    { "type": "url", "name": "GitHub", "target": "github.com", "launch": "reuse" },
    { "type": "folder", "name": "Projects", "icon": "FolderGit2", "target": "%USERPROFILE%\\src" },
    {
      "type": "folder",
      "name": "Downloads",
      "iconFile": "%SystemRoot%\\System32\\shell32.dll,4",
      "target": "%USERPROFILE%\\Downloads"
    },
    { "type": "file", "name": "Roadmap", "target": "D:\\Docs\\Roadmap.xlsx" },
    {
      "type": "group",
      "name": "Ops",
      "icon": "Server",
      "items": [
        {
          "type": "command",
          "name": "Flush DNS",
          "icon": "Wifi",
          "target": "ipconfig /flushdns",
          "shell": "cmd",
          "window": "hidden"
        },
        {
          "type": "command",
          "name": "Dev server",
          "target": "npm install; npm run dev",
          "workingDirectory": "D:\\src\\site"
        }, // trailing commas are fine
      ]
    }
  ]
}

Errors

Every error includes its line and column. These are the most common:

Found something here that doesn't match what the app does? Open an issue at github.com/arshit09/rovyl.