Vee documentation

CLI and URL actions

Vee can be driven from the command line during development and controlled at runtime through URL actions. Plugins use those same URL schemes to trigger refreshes and post notifications.

Running from source (swift run vee)

For development, run the menu-bar app straight from the SwiftPM package:

swift build          # build the libraries + dev executable
swift test           # run the test suites
swift run vee        # launch the menu-bar app for development

swift run vee starts the app so you can iterate on plugins and code without producing a full app bundle. See the project README for building the distributable, notarized Vee.app.

While developing you can point Vee at a specific plugins folder with an environment variable, which overrides the folder chosen in the UI:

VEE_PLUGINS_DIR=~/dev/my-plugins swift run vee

The vee command-line tool

Running vee with no subcommand launches the menu-bar app (that's also what happens when the bundled app is opened). Passing a subcommand instead gives you a zero-install authoring loop that reuses Vee's real parser — no app, no GUI:

The four authoring and debugging commands — vee render, vee show, vee dev, and vee lint — have their own page: Debugging and testing plugins. The remaining subcommands are documented below.

vee new

Scaffolds a ready-to-run plugin. Flags: --lang ts|py|sh, --interval (e.g. 5s, 10m), --name, --trust (comma-separated capabilities, e.g. network,secrets), and --out DIR. When run in a terminal with flags omitted, it prompts.

$ vee new --lang sh --interval 30s --name weather --trust network --out ~/plugins
# writes ~/plugins/weather.30s.sh with <xbar.*> + <vee.*> headers and a working body

For ts/py, the generated body imports the corresponding SDK so a scaffold doubles as a starting point for typed authoring.

vee search

Flattens a plugin's whole menu tree — including nested submenus — and prints the items fuzzy-filtered and ranked, so you can try the searchable filter panel's matching from the terminal before installing anything. With no query it lists every activatable item.

$ vee search ./dev-dashboard.5m.sh retry
2 of 45 item(s) match "retry":
  #412 Fix retry backoff jitter  ⟨Repositories › orders › Pull Requests⟩  [href]
  feature/retry-jitter  ⟨Repositories › orders › Branches⟩  [shell]

Query words are ANDed and matched fuzzily (gh finds GitHub); a match on a parent group's name still surfaces its children. Exits 1 when nothing matches and 2 on a missing path, so it slots into scripts and CI too.

URL actions

Vee registers two URL schemes: vee:// and swiftbar://. The swiftbar:// scheme is supported for compatibility, so plugins written for SwiftBar keep working. Both schemes accept the same actions.

The action is the URL host, and parameters come from the query string. The plugin name is passed as name (or path).

The same URLs work with the swiftbar:// scheme, e.g. swiftbar://refreshplugin?name=cpu.

The notify action

notify posts a macOS notification. Its parameters:

• title — the notification title.
• subtitle — an optional subtitle.
• body — the notification body text.
• href — an optional URL to open when the notification is clicked. Scheme-filtered like every other Vee URL (file:/javascript: are ignored; http(s) and app deep links such as vee:// are allowed).
• plugin — the originating plugin's id. When present, the alert becomes actionable — it gains Re-run, Silence (mute this plugin's alerts for the session), and Open Log buttons — and repeated alerts from the same plugin coalesce instead of stacking. Pass your own id with the injected $VEE_PLUGIN_ID variable.

vee://notify?title=Backup&subtitle=Nightly&body=Completed%20successfully&href=https://example.com

An actionable alert from a monitor plugin, tagged with its id so Re-run / Silence / Open Log resolve back to it:

open "vee://notify?plugin=$VEE_PLUGIN_ID&title=Build%20failed&body=exit%201"

Remember to URL-encode parameter values that contain spaces or special characters.

Triggering actions from a plugin

Because these are ordinary URLs, a plugin triggers them the same way it opens any link — either as an href on a menu item, or by opening the URL from the script.

As a clickable menu item (href=):

echo "Refresh now | href=vee://refreshplugin?name=cpu"
echo "Enable weather | href=vee://enableplugin?name=weather"

From the script itself (open the URL with open):

# Notify when a long task finishes
open "vee://notify?title=Build&body=Done"

# Force this plugin to re-render immediately
open "vee://refreshplugin?name=$VEE_PLUGIN_PATH"

Note that a menu item can also refresh the plugin without a URL at all, using the refresh=true line parameter:

echo "Refresh | refresh=true"

Use refresh=true for the common "re-run me" case; use the URL actions when a plugin needs to refresh, enable/disable, or toggle a different plugin, or to post a notification.

See also

• Plugin authoring reference — the href and refresh parameters.
• Plugin authoring reference — VEE_PLUGIN_PATH and other injected variables.