### Preview the documentation site
Source: https://github.com/navbytes/vee/blob/main/CONTRIBUTING.md
Commands to install dependencies and start the development server for the documentation site.
```sh
cd docs-site && npm install && npm run dev
```
--------------------------------
### Install the Vee Go SDK
Source: https://github.com/navbytes/vee/blob/main/plugins/go/README.md
Use the go get command to add the SDK as a module dependency.
```sh
go get github.com/navbytes/vee/plugins/go@v0.2.0 # or @latest
```
--------------------------------
### Install and import Go SDK
Source: https://github.com/navbytes/vee/blob/main/docs/_content/sdk.md
Go plugins use standard module dependencies as they compile to binaries.
```sh
go get github.com/navbytes/vee/plugins/go
```
```go
import vee "github.com/navbytes/vee/plugins/go"
```
--------------------------------
### Install Vee with custom options
Source: https://github.com/navbytes/vee/blob/main/docs/_content/getting-started.md
Installs Vee with specific configuration flags for application directory, binary path, or version pinning.
```sh
# Install per-user instead of system-wide
curl -fsSL https://vee.navbytes.io/install.sh | bash -s -- --app-dir ~/Applications
# Put the CLI somewhere else on your PATH
curl -fsSL https://vee.navbytes.io/install.sh | bash -s -- --bin-dir /opt/homebrew/bin
# Pin a specific release rather than the latest
curl -fsSL https://vee.navbytes.io/install.sh | bash -s -- --version v0.2.0
```
--------------------------------
### Example preference declarations
Source: https://github.com/navbytes/vee/blob/main/docs/_content/preferences.md
Common examples of preference declarations for different data types.
```python
# string(CITY=London): Which city's weather to show.
# number(REFRESH_COUNT=5): How many items to display.
# boolean(SHOW_ICON=true): Show an icon in the menu bar.
# select(UNITS=metric): Measurement units. [metric, imperial]
# string(API_TOKEN=): Your service API token.
```
--------------------------------
### Accessing guide page source
Source: https://github.com/navbytes/vee/blob/main/docs/_content/writing-plugins-with-an-llm.md
Individual guide pages can be retrieved in Markdown format by changing the file extension.
```text
https://vee.navbytes.io/guide/plugin-authoring.html ← the page you read
https://vee.navbytes.io/guide/plugin-authoring.md ← the source a model reads
```
--------------------------------
### Create Hello World Plugin
Source: https://github.com/navbytes/vee/blob/main/plugins/python/README.md
Example of a plugin script defining a menu with a title, dropdown items, and a submenu.
```python
#!/usr/bin/env python3
from vee import Menu # vee.py sits beside this file
menu = Menu()
menu.title("CPU 12%", color="green", sfimage="cpu")
d = menu.dropdown
d.item("Top processes", href="https://example.com/procs")
d.separator()
details = d.submenu("Details")
details.item("Load: 1.20")
details.item("Cores: 8")
d.item("Refresh", refresh=True)
menu.print()
```
--------------------------------
### Create a Hello World plugin
Source: https://github.com/navbytes/vee/blob/main/plugins/typescript/README.md
A basic example of a plugin script that defines a menu with a title, dropdown items, and a submenu.
```ts
#!/usr/bin/env node
import { Menu } from "./vee.ts";
const menu = new Menu();
menu.title("CPU 12%", { color: "green", sfimage: "cpu" });
const d = menu.dropdown;
d.item("Top processes", { href: "https://example.com/procs" });
d.separator();
const details = d.submenu("Details");
details.item("Load: 1.20");
details.item("Cores: 8");
d.item("Refresh", { refresh: true });
menu.print();
```
--------------------------------
### Install Vee via Homebrew
Source: https://github.com/navbytes/vee/blob/main/docs/_content/getting-started.md
Installs the Vee application and CLI using the Homebrew package manager.
```sh
brew install --cask navbytes/tap/vee
```
--------------------------------
### Install Vee SDK
Source: https://github.com/navbytes/vee/blob/main/plugins/python/README.md
Command to generate the vee.py SDK file in the specified plugins directory.
```sh
vee sdk py --out ~/path/to/your/plugins # writes vee.py there
```
--------------------------------
### Download and run the kitchen sink plugin
Source: https://github.com/navbytes/vee/blob/main/plugins/showcase/README.md
Downloads the kitchen-sink example plugin to the Vee plugins directory and makes it executable.
```sh
curl -o ~/Library/Application\ Support/Vee/plugins/kitchen-sink.1m.sh \
https://raw.githubusercontent.com/navbytes/vee/main/plugins/showcase/kitchen-sink.1m.sh
chmod +x ~/Library/Application\ Support/Vee/plugins/kitchen-sink.1m.sh
```
--------------------------------
### Install Vee SDK via CLI
Source: https://github.com/navbytes/vee/blob/main/plugins/typescript/README.md
Use the CLI to write the SDK file directly to your plugins directory.
```sh
vee sdk ts --out ~/path/to/your/plugins # writes vee.ts there
```
--------------------------------
### Install Vee SDK via npm
Source: https://github.com/navbytes/vee/blob/main/plugins/typescript/README.md
Install the SDK as a dependency in projects that already use npm.
```sh
npm install @navbytes/vee
```
--------------------------------
### Settings form layout example
Source: https://github.com/navbytes/vee/blob/main/docs/_content/preferences.md
Visual representation of how the declared preferences appear in the settings pane.
```text
City [ London ] Which city's weather to show.
Refresh count [ 5 ] How many items to display.
Show icon ( ●) on Show an icon in the menu bar.
Units [ metric ▾ ] Measurement units.
API token [ •••••••••••• ] Your service API token.
```
--------------------------------
### Install Vee via curl
Source: https://github.com/navbytes/vee/blob/main/docs/_content/getting-started.md
Installs Vee using the provided shell script.
```sh
curl -fsSL https://vee.navbytes.io/install.sh | bash
```
--------------------------------
### Install Vee CLI via mise
Source: https://github.com/navbytes/vee/blob/main/docs/_content/getting-started.md
Installs only the Vee CLI tool using the mise version manager.
```sh
mise use github:navbytes/vee
```
--------------------------------
### Preview a plugin with vee show
Source: https://github.com/navbytes/vee/blob/main/docs/_content/debugging.md
Use this command to render a plugin's output in the terminal, either by file path or by installed plugin name.
```sh
$ vee show ./cpu.10s.sh # or an installed plugin by name: vee show cpu
```
--------------------------------
### Install a plugin manually
Source: https://github.com/navbytes/vee/blob/main/plugins/showcase/README.md
Sets the executable bit on a plugin file and copies it to the Vee plugins directory.
```sh
chmod +x hello-world.10s.sh
cp hello-world.10s.sh ""
```
--------------------------------
### Install and import TypeScript SDK via npm
Source: https://github.com/navbytes/vee/blob/main/docs/_content/sdk.md
Use npm for plugins that are part of a larger project with node_modules.
```sh
npm install @navbytes/vee
```
```ts
import { Menu } from "@navbytes/vee";
```
--------------------------------
### Triggering an actionable notification
Source: https://github.com/navbytes/vee/blob/main/docs/_content/cli-and-urls.md
Example of an actionable notification using the open command and the $VEE_PLUGIN_ID variable.
```bash
open "vee://notify?plugin=$VEE_PLUGIN_ID&title=Build%20failed&body=exit%201"
```
--------------------------------
### Import SDK from npm package
Source: https://github.com/navbytes/vee/blob/main/plugins/typescript/README.md
Import the Menu class from the installed npm package.
```ts
import { Menu } from "@navbytes/vee";
```
--------------------------------
### Create a streamable plugin
Source: https://github.com/navbytes/vee/blob/main/docs/_content/plugin-authoring.md
Use the streamable type to push updates continuously. The ~~~ separator defines the start of a new menu render.
```bash
#!/bin/bash
# streamable
while true; do
echo "~~~"
echo "⏱ $(date +%T)"
sleep 1
done
```
--------------------------------
### Define menu items with options
Source: https://github.com/navbytes/vee/blob/main/docs/_content/sdk.md
Examples of adding menu items with various options like shell commands, badges, markdown, and SF symbols across different languages.
```typescript
d.item("Open build", { shell: "/usr/bin/open", params: ["-a", "Xcode"], terminal: false });
d.item("Inbox", { badge: "12" });
d.item("**Bold** text", { md: true });
d.item("Status :checkmark.circle:", { symbolize: true });
```
```python
d.item("Open build", shell="/usr/bin/open", params=["-a", "Xcode"], terminal=False)
d.item("Inbox", badge="12")
d.item("**Bold** text", md=True)
d.item("Status :checkmark.circle:", symbolize=True)
```
```go
d.Item("Open build", &vee.Options{Shell: vee.Str("/usr/bin/open"), Params: []string{"-a", "Xcode"}, Terminal: vee.Bool(false)})
d.Item("Inbox", &vee.Options{Badge: vee.Str("12")})
d.Item("**Bold** text", &vee.Options{MD: vee.Bool(true)})
d.Item("Status :checkmark.circle:", &vee.Options{Symbolize: vee.Bool(true)})
```
--------------------------------
### Define a Vee menu with rich controls in JSON
Source: https://github.com/navbytes/vee/blob/main/docs/_content/json-output.md
Example structure demonstrating various inline controls including sparklines, toggles, sliders, progress bars, and a donut chart.
```json
{
"vee": 1,
"title": [{ "text": "System" }],
"items": [
{ "text": "Load history", "sparkline": [1, 2, 3, 5, 8, 13], "sparklineWidth": 120, "sparklineHeight": 18, "sparklineColor": "teal" },
{ "text": "Notifications", "toggle": true },
{ "text": "Volume", "slider": { "min": 0, "max": 100, "value": 40 } },
{ "text": "Disk usage", "color": "green", "progress": 0.72, "progressTrackColor": "#333333", "progressWidth": 80, "progressHeight": 6 },
{ "text": "By category", "chart": { "kind": "donut", "values": [45, 30, 25], "labels": ["Documents", "Photos", "Apps"] } }
]
}
```
--------------------------------
### Initialize and build the project
Source: https://github.com/navbytes/vee/blob/main/CONTRIBUTING.md
Commands to clone the repository, build the libraries, run tests, and execute the menu-bar app.
```sh
git clone https://github.com/navbytes/vee.git
cd vee
swift build # build the libraries + the dev `vee` executable
swift test # run the XCTest suites (TDD — keep these green)
swift run vee # run the menu-bar app for local development
```
--------------------------------
### Create a Hello World Plugin
Source: https://github.com/navbytes/vee/blob/main/plugins/go/README.md
Construct a menu with a title, dropdown items, and a submenu using the Vee builder pattern.
```go
package main
import "vee"
func main() {
m := &vee.Menu{}
m.Title("CPU 12%", &vee.Options{Color: vee.Str("green"), SFImage: vee.Str("cpu")})
d := m.Dropdown()
d.Item("Top processes", &vee.Options{Href: vee.Str("https://example.com/procs")})
d.Separator()
details := d.Submenu("Details", nil)
details.Item("Load: 1.20", nil)
details.Item("Cores: 8", nil)
d.Item("Refresh", &vee.Options{Refresh: vee.Bool(true)})
m.Print()
}
```
--------------------------------
### Create a hello world plugin
Source: https://github.com/navbytes/vee/blob/main/docs/_content/getting-started.md
A basic shell script that displays a menu bar title and a dropdown menu item.
```bash
#!/bin/bash
echo "Hello 👋"
echo "---"
echo "It works!"
echo "Refresh | refresh=true"
```
--------------------------------
### Build and run Vee from source
Source: https://github.com/navbytes/vee/blob/main/docs/_content/cli-and-urls.md
Use these commands to build the project, run tests, and launch the menu-bar application during development.
```sh
swift build # build the libraries + dev executable
swift test # run the test suites
swift run vee # launch the menu-bar app for development
```
--------------------------------
### Configure Share Charts
Source: https://github.com/navbytes/vee/blob/main/docs/_content/sdk.md
Examples of using the chart builder for pie and donut visualizations.
```ts
d.item("By category", { chart: { kind: "pie", values: [45, 30, 25], labels: ["Documents", "Photos", "Apps"] } });
d.item("By volume", { chart: { kind: "donut", values: [512, 256, 128], colors: ["blue", "teal", "orange"] } });
```
```python
d.item("By category", chart={"kind": "pie", "values": [45, 30, 25], "labels": ["Documents", "Photos", "Apps"]})
d.item("By volume", chart={"kind": "donut", "values": [512, 256, 128], "colors": ["blue", "teal", "orange"]})
```
```go
d.Item("By category", &vee.Options{Chart: &vee.Chart{
Kind: "pie", Values: []float64{45, 30, 25}, Labels: []string{"Documents", "Photos", "Apps"},
}})
d.Item("By volume", &vee.Options{Chart: &vee.Chart{
Kind: "donut", Values: []float64{512, 256, 128}, Colors: []string{"blue", "teal", "orange"},
}})
```
--------------------------------
### Initialize GitHubCatalogClient with StoreConfig
Source: https://github.com/navbytes/vee/blob/main/docs/design/custom-plugin-store.md
Initializes the client with a configuration object, optional token provider, and URL session.
```swift
public init(config: StoreConfig, tokenProvider: StoreTokenProviding? = nil, session: URLSession = .shared)
```
--------------------------------
### Regenerate shared fixtures
Source: https://github.com/navbytes/vee/blob/main/plugins/README.md
Updates the golden output files using the TypeScript examples.
```sh
cd plugins/typescript && npm run build:fixtures
```
--------------------------------
### Plugin Management Actions
Source: https://github.com/navbytes/vee/blob/main/docs/_content/cli-and-urls.md
Actions to refresh, enable, disable, toggle, or install plugins.
```APIDOC
## [GET] vee://[action]
### Description
Perform management operations on plugins using the vee:// or swiftbar:// URL schemes.
### Endpoint
vee://[action]?name=[plugin_name]
### Parameters
#### Query Parameters
- **name** (string) - Required - The name or path of the plugin.
- **src** (string) - Required (for addplugin) - The URL source to download and install a plugin.
### Actions
- **refreshallplugins** / **refreshall**: Re-run every plugin.
- **refreshplugin**: Re-run one plugin by name.
- **enableplugin**: Enable a plugin.
- **disableplugin**: Disable a plugin.
- **toggleplugin**: Toggle a plugin's enabled state.
- **addplugin**: Download and install a plugin from a URL.
```
--------------------------------
### Build and Test Commands
Source: https://github.com/navbytes/vee/blob/main/ARCHITECTURE.md
Standard commands for building libraries, running tests, and executing the menu-bar application.
```sh
swift build # libraries + the dev `vee` executable
swift test # all XCTest suites (keep green; TDD)
swift run vee # run the menu-bar app for local development
```
--------------------------------
### Declare a preference using xbar.var
Source: https://github.com/navbytes/vee/blob/main/docs/_content/preferences.md
Use this syntax within a plugin source to define a configuration setting.
```text
TYPE(NAME=DEFAULT): Description [option1, option2, …]
```
--------------------------------
### Triggering a notification via URL
Source: https://github.com/navbytes/vee/blob/main/docs/_content/cli-and-urls.md
Example of a basic notification URL using the vee:// scheme.
```text
vee://notify?title=Backup&subtitle=Nightly&body=Completed%20successfully&href=https://example.com
```
--------------------------------
### Create a Go plugin
Source: https://github.com/navbytes/vee/blob/main/docs/_content/sdk.md
Implements a menu plugin in Go. Requires Go 1.21 or later and must be compiled into a binary.
```go
package main
import "vee"
func main() {
m := &vee.Menu{}
m.Title("CPU 12%", &vee.Options{Color: vee.Str("green"), SFImage: vee.Str("cpu")})
d := m.Dropdown()
d.Item("Top processes", &vee.Options{Href: vee.Str("https://example.com/procs")})
d.Separator()
details := d.Submenu("Details", nil)
details.Item("Load: 1.20", nil)
details.Item("Cores: 8", nil)
d.Item("Refresh", &vee.Options{Refresh: vee.Bool(true)})
m.Print()
}
```
```sh
go build -o cpu.5s ./...
```
--------------------------------
### Configure Inline Controls
Source: https://github.com/navbytes/vee/blob/main/docs/_content/sdk.md
Examples of using typed builders for inline visual controls across supported languages.
```ts
d.item("Load history", { sparkline: [1, 2, 3, 5, 8, 13], sparklineW: 120, sparklineH: 18, sparklineColor: "teal" });
d.item("Notifications", { toggle: true });
d.item("Volume", { slider: { min: 0, max: 100, value: 40 } });
d.item("Disk usage", { color: "green", progress: 0.72, progressTrackColor: "#333333", progressW: 80, progressH: 6 });
// progress also accepts a value/max pair, emitted as `progress=72,100`:
d.item("Budget", { progress: { value: 72, max: 100 } });
// and any width takes "full":
d.item("Requests", { sparkline: [12, 40, 31, 55], sparklineW: "full" });
```
```python
d.item("Load history", sparkline=[1, 2, 3, 5, 8, 13], sparkline_w=120, sparkline_h=18, sparkline_color="teal")
d.item("Notifications", toggle=True)
d.item("Volume", slider={"min": 0, "max": 100, "value": 40})
d.item("Disk usage", color="green", progress=0.72, progress_track_color="#333333", progress_w=80, progress_h=6)
d.item("Budget", progress={"value": 72, "max": 100})
d.item("Requests", sparkline=[12, 40, 31, 55], sparkline_w="full")
```
```go
d.Item("Load history", &vee.Options{Sparkline: []float64{1, 2, 3, 5, 8, 13}, SparklineW: vee.Float(120), SparklineH: vee.Float(18), SparklineColor: vee.Str("teal")})
d.Item("Notifications", &vee.Options{Toggle: vee.Bool(true)})
d.Item("Volume", &vee.Options{Slider: &vee.Slider{Min: 0, Max: 100, Value: 40}})
d.Item("Disk usage", &vee.Options{Color: vee.Str("green"), Progress: vee.Float(0.72), ProgressTrackColor: vee.Str("#333333"), ProgressW: vee.Float(80), ProgressH: vee.Float(6)})
d.Item("Budget", &vee.Options{ProgressValue: vee.Float(72), ProgressMax: vee.Float(100)})
d.Item("Requests", &vee.Options{Sparkline: []float64{12, 40, 31, 55}, SparklineFullWidth: true})
```
--------------------------------
### Build and run Vee from source
Source: https://github.com/navbytes/vee/blob/main/README.md
Commands to compile the libraries, run tests, and generate the Xcode project for the distributable app bundle.
```sh
swift build # build the libraries + dev executable
swift test # run the test suites
swift run vee # run the menu-bar app for development
# Build the distributable app bundle:
xcodegen generate
xcodebuild -project Vee.xcodeproj -scheme Vee build
```
--------------------------------
### Preview menu structure with --text
Source: https://github.com/navbytes/vee/blob/main/docs/_content/debugging.md
Treats a file as static output to preview menu formatting without executing code.
```sh
$ cat menu.txt
CPU 42% | color=red
---
Open dashboard | href=https://example.com
$ vee dev --text menu.txt
```
--------------------------------
### Build and verify generated documentation partials
Source: https://github.com/navbytes/vee/blob/main/CONTRIBUTING.md
Scripts to generate documentation partials from the parameter JSON or verify if existing partials are up to date.
```sh
python3 docs/scripts/build_reference.py # write the generated partials
python3 docs/scripts/build_reference.py --check # fails if a partial is stale
```
--------------------------------
### Accessing full plugin documentation
Source: https://github.com/navbytes/vee/blob/main/docs/_content/writing-plugins-with-an-llm.md
The complete plugin documentation is available as a single Markdown file for LLM context.
```text
https://vee.navbytes.io/llms-full.txt
```
--------------------------------
### JSON Output Schema Example
Source: https://github.com/navbytes/vee/blob/main/docs/_content/json-output.md
A sample JSON structure conforming to the Vee output schema. The $schema property is ignored by the engine.
```json
{
"$schema": "https://vee.navbytes.io/schemas/json-output.schema.json",
"vee": 1,
"title": [{ "text": "System" }],
"items": [{ "text": "Hello" }]
}
```
--------------------------------
### MDM Configuration Profile Payload
Source: https://github.com/navbytes/vee/blob/main/docs/_content/enterprise-store.md
An example XML payload for configuring managed stores and disabling the public catalog via MDM.
```xml
vee.managedStores
idacme-internal
displayNameAcme Internal Tools
kindgithubEnterprise
apiHosthttps://ghe.acme.corp/api/v3
rawHosthttps://ghe.acme.corp/raw
ownerplatform
repovee-plugins
requireSignature
pinnedSigningKeyMCowBQYDK2VwAyEA…
vee.disablePublicStore
```
--------------------------------
### Run tests and build fixtures
Source: https://github.com/navbytes/vee/blob/main/plugins/typescript/README.md
Commands to run the drift guard tests and regenerate fixtures.
```sh
cd plugins/typescript
npm test # fixture drift guard (node --test)
npm run build:fixtures # regenerate ../fixtures from the examples
```
--------------------------------
### Build menus using SDKs
Source: https://github.com/navbytes/vee/blob/main/docs/_content/json-output.md
Demonstrates how to use the typed builders in TypeScript, Python, and Go to generate the same JSON menu structure.
```ts
import { JSONMenu } from "./vee.ts";
const menu = new JSONMenu();
menu.title("JSON ✓", { color: "green", sfimage: "curlybraces" });
const d = menu.dropdown;
d.item("Structured item", { href: "https://example.com" });
d.separator();
d.submenu("Submenu").item("Child", { color: "blue" });
menu.print();
```
```python
from vee import JSONMenu
menu = JSONMenu()
menu.title("JSON ✓", color="green", sfimage="curlybraces")
d = menu.dropdown
d.item("Structured item", href="https://example.com")
d.separator()
d.submenu("Submenu").item("Child", color="blue")
menu.print()
```
```go
m := &vee.JSONMenu{}
m.Title("JSON ✓", &vee.JSONOptions{Color: vee.Str("green"), SFImage: vee.Str("curlybraces")})
d := m.Dropdown()
d.Item("Structured item", &vee.JSONOptions{Href: vee.Str("https://example.com")})
d.Separator()
d.Submenu("Submenu", nil).Item("Child", &vee.JSONOptions{Color: vee.Str("blue")})
m.Print()
```
--------------------------------
### Define Store Identification and Trust Policies
Source: https://github.com/navbytes/vee/blob/main/docs/design/custom-plugin-store.md
Core types for identifying stores, defining their kind, and setting trust policies for installation.
```swift
public struct StoreID: Hashable, Codable, Sendable {
public let rawValue: String // e.g. "com.vee.store.xbar", "acme-internal"
}
public enum StoreKind: String, Codable, Sendable {
case github, githubEnterprise, http, local
}
/// How loudly the install gate frames a store. Never changes enforcement —
/// provenance + trust scan always run; this only reframes and sets the default
/// button posture.
public enum StoreTrustPolicy: String, Codable, Sendable {
case publicUntrusted // current behavior: full warnings, no default action
case internalReviewed // "Reviewed internal source"; warnings still shown
}
```
--------------------------------
### Push ephemeral plugin to menu bar
Source: https://github.com/navbytes/vee/blob/main/docs/_content/debugging.md
Sends plugin output directly to the running Vee app for real-time previewing without installing the file.
```sh
$ vee dev --push ./cpu.10s.sh
```
--------------------------------
### Create the plugins directory
Source: https://github.com/navbytes/vee/blob/main/docs/_content/getting-started.md
Ensures the default plugins directory exists before adding new scripts.
```sh
mkdir -p ~/Library/Application\ Support/Vee/plugins
```
--------------------------------
### Import SDK from local file
Source: https://github.com/navbytes/vee/blob/main/plugins/typescript/README.md
Import the Menu class from the local SDK file.
```ts
import { Menu } from "./vee.ts";
```
--------------------------------
### Provide JSON Schemas for Plugin Generation
Source: https://github.com/navbytes/vee/blob/main/docs/_content/writing-plugins-with-an-llm.md
Use these schema URLs to guide the LLM in generating structured plugin output that adheres to Vee's requirements.
```text
https://vee.navbytes.io/schemas/widget-card.schema.json
https://vee.navbytes.io/schemas/json-output.schema.json
```
--------------------------------
### Import the Vee SDK
Source: https://github.com/navbytes/vee/blob/main/plugins/go/README.md
Import the package to access the Menu, Section, and Options builders.
```go
import vee "github.com/navbytes/vee/plugins/go"
```