xbar

User-provided variable values are persisted in a sidecar JSON file located alongside your plugin. The filename follows the pattern {plugin_name}.vars.json. The keys in the JSON object match the variable names used in the metadata (which are also the environment variable names).

// Example: tail.5s.sh.vars.json
{
	"VAR_FILE": "./001-tail.5s.sh",
	"VAR_LINES": 15
}

Plugins are stored in a specific folder on your Mac. If you are migrating from BitBar, move your existing plugins into this directory to install them in xbar.

Plugin Directory Path: ~/Library/Application Support/xbar/plugins

The sitegen tool generates the xbar website by combining plugin data from the matryer/xbar-plugins GitHub repository with local templates.

Prerequisites

Before running the site generator, you should update the CSS in the xbarapp.com directory:

cd ../xbarapp.com
npm run build

Execution Steps

To build and run the site generator, you must provide a GitHub access token to avoid rate limiting. Use the following command sequence:

go build -o sitegen && XBAR_GITHUB_ACCESS_TOKEN=xxx ./sitegen -small && cd ../../xbarapp.com && npm run build

CLI Options

• -small: Processes only a subset of plugins. Remove this flag to process all available plugins.

Important Notes

• GitHub Rate Limiting: Frequent use of this tool may trigger GitHub rate limits. Ensure you use a valid XBAR_GITHUB_ACCESS_TOKEN.

Compile and build the front-end styles using the defined npm build script.

npm run build

Deploy the application to Google Cloud using the gcloud CLI. This command targets the xbarapp project and sets the version to 6.

gcloud app deploy --project xbarapp --version 6

The name you define in the <xbar.var> tag becomes an environment variable available to your plugin script. Note that all environment variable values are treated as strings by the shell/system, even if defined as number or boolean in the metadata.

Example usage in a shell script:

# If metadata defines <xbar.var>string(VAR_NAME="World"): Your name.</xbar.var>
echo "Hello, ${VAR_NAME}"

#  <xbar.var>string(VAR_NAME="World"): Your name.</xbar.var>
echo "Hello, ${VAR_NAME}"

If you are running the project for the first time, you must generate the .version file and install the frontend dependencies before starting the development servers.

1. Generate version file: Run git describe --tags > .version inside the app directory.
2. Install dependencies: Run npm install inside the app/frontend directory.
3. Start Frontend: Run npm run dev inside the app/frontend directory.
4. Start Backend/App: Run wails dev inside the app directory.

cd app && git describe --tags > .version
cd app/frontend && npm install
cd app/frontend && npm run dev
cd app && wails dev

To package a new release, first tag your current branch with a version number (e.g., v0.1.0) and push the tag to your origin. Then, run the ./package.sh script.

Note: xbar uses github.com/matryer/gon (a fork of mitchellh/gon) for code signing.

git tag -a v0.1.0 -m "release tag."
git push origin v0.1.0
./package.sh

Most BitBar plugins will run in xbar without any changes. To fully leverage xbar features and ensure compatibility, you should update your plugin metadata and parameters.

Recommended updates:

• Replace <bitbar.*> tags in your metadata with <xbar.*> tags.
• Replace the bash parameter with the shell parameter.
• If you were using numbered parameters (e.g., param1, param2), note that xbar now supports an unlimited number of paramN parameters.

To start the development server for the xbarapp.com website, use the go run command on the main entry point.

go run main.go