BitBar (by Mat Ryer - @matryer) lets you put the output from any script/program in your Mac OS X Menu Bar.

• Download latest BitBar release - requires Mac OS X Lion or newer (>= 10.7)
• Visit the app homepage at https://getbitbar.com to install plugins
• Get started and installing plugins

Digging deeper:

• Browse plugin repository
• Guide to writing your own plugins
• Distributing pre-configured BitBar
• Learn about integrating with bitbar via the bitbar:// URL scheme

And finally...

• Read the story about how BitBar unexpectedly got going
• Contributing and special thanks

Example showing the latest Buy and Sell figures for BitCoins:

Click to see the full output, and more options:

Example showing your internal and external IP addresses:

Get the latest version of BitBar. Copy it to your Applications folder and run it - it will ask you to (create and) select a plugins folder, do so.

Browse our plugins to find useful scripts, or write your own.

If you love this, any BitCoin donations are most welcome, to 1DGoNEYAnjE5DqK7y5zMPR4PLU5HLKpLNR or send something useful (Amazon Wishlist).

Just download the plugin of your choice into your BitBar plugins directory and choose Refresh from one of the BitBar menus.

The refresh time is in the filename of the plugin, following this format:

{name}.{time}.{ext}

• name - The name of the file
• time - The refresh rate (see below)
• ext - The file extension

For example:

• date.1m.sh would refresh every minute.

Most plugins will come with a default, but you can change it to anything you like:

• 10s - ten seconds
• 1m - one minute
• 2h - two hours
• 1d - a day

Ensure the plugin is executable by running chmod +x plugin.sh.

Because Git will ignore everything in Plugins/Enabled, you can use it to maintain your own plugins directory while still benefitting from tracking (upstream) changes.

cd Plugins/Enabled

# Enable spotify plugin
ln -s ../Music/spotify.10s.sh

# Enable uptime plugin and change update interval to 30 seconds
ln -s ../System/uptime.1m.sh uptime.30s.sh

Then select the Enabled folder in your BitBar preferences.

In case you made the mistake of choosing a directory with thousands of files as the plugin directory and BitBar getting stuck forever, do this from terminal to reset it:

defaults delete com.matryer.BitBar

• Help us solve bugs or build new features.
• If you want to contribute a plugin, please head over to the Plugin repository and submit a pull request. Be sure to read our guide to writing plugins below.

1. Clone the project git clone https://github.com/matryer/bitbar.git
2. Ensure you've pod installed on your system using sudo gem install pod
3. Install dependencies make init within the root of the project
4. Open in XCode open App/BitBar.xcworkspace

Make sure you've all dependencies installed on your system by running make setup.

• Run the test suit once: make test
• Run the suit every time a file changes: make watch
• Run a specific test: make test class=PropertyTest or make watch class=PropertyTest

• make lint will display all linting errors
• make fix will fix linting errors

• Release: make release

• Special thanks to @muhqu and @tylerb for all their help (see commit history for details)
• Thanks to Chris Ryer for the app logo - and to @mazondo for the original
• Thanks for all our plugin contributors who have come up with some pretty genius things

We're always looking for new plugins, so please send us pull requests if you write anything cool or useful.

Join the conversation with plugin authors and BitBar maintainers on Slack.

If you've got ideas, or want to report a bug, nip over to our issues page and let us know.

If you want to contribute, please send us a pull request and we'll add it to our repos.

• Ensure the plugin is executable
• Be sure to include appropriate Metadata to enhance the plugin's entry on getbitbar.com

• To write a plugin, just write some form of executable script that outputs to the standard output.

• Multiple lines will be cycled through over and over.

• If your output contains a line consisting only of ---, the lines below it will appear in the dropdown for that plugin, but won't appear in the menu bar itself.

• Lines beginning with -- will appear in submenus.

• Output ~~~ from long running scripts to render everything above it and since the last ~~~ (example).

• Your lines might contain | to separate the title from other parameters, such as...

  • href=.. to make the item clickable
  • color=.. to change their text color. eg. color=red or color=#ff0000
  • font=.. to change their text font. eg. font=UbuntuMono-Bold
  • size=.. to change their text size. eg. size=12
  • bash=.. to make the item run a given script terminal with your script e.g. bash=/Users/user/BitBar_Plugins/scripts/nginx.restart.sh if there are spaces in the file path you will need quotes e.g. bash="/Users/user/BitBar Plugins/scripts/nginx.restart.sh"
  • param1= to specify arguments to the script. additional params like this param2=foo param3=bar full example bash="/Users/user/BitBar_Plugins/scripts/nginx.restart.sh" param1=--verbose assuming that nginx.restart.sh is executable or bash=/usr/bin/ruby param1=/Users/user/rubyscript.rb param2=arg1 param3=arg2 if script is not executable
  • terminal=.. start bash script without opening Terminal. true or false
  • refresh=.. to make the item refresh the plugin it belongs to
  • dropdown=.. May be set to true or false. If false, the line will only appear and cycle in the status bar but not in the dropdown
  • length=.. to truncate the line to the specified number of characters. A … will be added to any truncated strings, as well as a tooltip displaying the full string. eg. length=10
  • trim=.. whether to trim leading/trailing whitespace from the title. true or false (defaults to true)
  • alternate=true to mark a line as an alternate to the previous one for when the Option key is pressed in the dropdown
  • templateImage=.. set an image for this item. The image data must be passed as base64 encoded string or URL and should consist of only black and clear pixels. The alpha channel in the image can be used to adjust the opacity of black content, however. This is the recommended way to set an image for the statusbar. Use a 144 DPI resolution to support Retina displays. The imageformat can be any of the formats supported by Mac OS X
  • image=.. set an image for this item. The image data must be passed as base64 encoded string or URL. Use a 144 DPI resolution to support Retina displays. The imageformat can be any of the formats supported by Mac OS X
  • emojize=false will disable parsing of github style :mushroom: into 🍄
  • ansi=false turns off parsing of ANSI codes.
  • checked=true for a checkmark

To enhance your entry on getbitbar.com, add the following metadata to your source code (usually in comments somewhere):

# <bitbar.title>Title goes here</bitbar.title>
# <bitbar.version>v1.0</bitbar.version>
# <bitbar.author>Your Name</bitbar.author>
# <bitbar.author.github>your-github-username</bitbar.author.github>
# <bitbar.desc>Short description of what your plugin does.</bitbar.desc>
# <bitbar.image>http://www.hosted-somewhere/pluginimage</bitbar.image>
# <bitbar.dependencies>python,ruby,node</bitbar.dependencies>
# <bitbar.abouturl>http://url-to-about.com/</bitbar.abouturl>
# <bitbar.droptypes>filenames,public.url</bitbar.droptypes>
# <bitbar.demo>--demo</bitbar.demo>

• The comment characters can be anything - use what is suitable for your language
• bitbar.title - The title of the plugin
• bitbar.version - The version of the plugin (start with v1.0)
• bitbar.author - Your name
• bitbar.author.github - Your github username (without @)
• bitbar.desc - A short description of what your plugin does
• bitbar.image - A hosted image showing a preview of your plugin (ideally open)
• bitbar.dependencies - Comma separated list of dependencies
• bitbar.abouturl - Absolute URL to about information
• bitbar.droptypes - Uniform type identifiers or filenames, comma separated. Plugin is executed with arguments -type and the dropped item(s) (example)
• bitbar.demo - Whitespace separated arguments to execute plugin with in demo mode (i.e. when saving a screenshot)

For a real example, see the Cycle text and detail plugin source code.

• If you're writing scripts, ensure it has a shebang at the top.
• You can add to PATH by including something like export PATH='/usr/local/bin:/usr/bin:$PATH' in your plugin script.
• You can use emoji in the output (find an example in the Music/vox Plugin).
• If your bash script generates text in another language, set the LANG variable with: export LANG="es_ES.UTF-8" (for Spanish) to show the text in correct format.
• If you want to call the plugin script for action, you can use bash=$0
• If your plugin should support Retina displays, export your icon at 36x36 with a resolution of 144 DPI (see this issue for a more thorough explanation).

#!/bin/bash
date

#!/bin/bash

# the current date and time
date

# the current username
echo $USER

# the current user id
id -u

#!/bin/bash
echo "One"
echo "Two"
echo "Three"
echo "---"
echo "Four"
echo "Five"
echo "Six"

• Only One, Two and Three will appear in the top bar
• Clicking the plugin menu item will show all lines

#!/bin/bash
curl -m 1 http://example.com -I >/dev/null 2>&1
[ $? -gt 0 ] && echo "FAIL | color=red" || echo "OK | color=green"
echo "---"
echo "Show Graphs | color=#123def href=http://example.com/graph?foo=bar"
echo "Show KPI Report | color=purple href=http://example.com/report"

#!/bin/zsh
FONT=( 'size=14' 'font=UbuntuMono' )
if ((0)); then echo "DO | $FONT color=orange"
else           echo "DO | $FONT color=cadetblue"
echo "---"
...

Anything that can write to standard out is supported, but here is a list that have been explicitly tested.

1. Ruby

2. Status: Working

3. Output: puts "your string here"

4. Python2

5. Status: Working

6. Output: print "your string here"

7. Python3

8. Status: Working

9. Output: print("your string here")

10. JavaScript (node)

11. Status: Working

12. Caveats: Shebang has to be in the format #!/usr/bin/env /path/to/the/node/executable

13. Output: console.log("your string here")

14. Notes:

1. `process.stdout.write` doesn't output desired text.
2. There may be a better way to run JavaScript files.

5. Tips:

1. Use the Node.js [`bitbar` module](https://github.com/sindresorhus/bitbar) to simplify plugin creation.

5. CoffeeScript (coffee)

6. Status: Working

7. Caveats:

1. Shebang has to be in the format `#!/usr/bin/env /path/to/the/coffee/executable`
2. `coffee` shebang also had to be modified.
3. `#!/usr/bin/env /path/to/the/node/executable`

3. Output: console.log "your string here"

4. Notes:

1. `process.stdout.write` doesn't output desired text.
2. There may be a better way to run CoffeeScript files.

6. Swift (Interpreted)

7. Status: Working

8. Output: print("your string here")

9. Swift (Compiled)

10. Status: Working

11. Caveats: You still need a file extension (file.1s.cswift)

12. Output: print("your string here")

13. Notes:

1. To compile a swift file, use: `xcrun -sdk macosx swiftc -o file.1s.cswift file.1s.swift`

8. Go (Interpreted)

9. Status: Working

10. Caveats:

1. Your script's shebang must be: `//usr/env/bin go run $0 $@; exit`
2. `go` must be in your `PATH`

3. Output: Println("your string here")

4. Go (Compiled)

5. Status: Working

6. Caveats: You still need a file extension (file.1s.cgo)

7. Output: Println("your string here")

8. Notes

1. To compile a Go file, use: `go build file.1s.go`

10. Lisp

11. Status: Working

12. Caveats: lisp/clisp must be in your PATH

13. Output: (format t "your string here")

14. Perl5

15. Status: Working

16. Output: print "your string here"

17. Notes

18. Add -l to shebang to automatic add newline to print function: #!/usr/bin/perl -l

19. PHP

20. Status: Working

21. Output: echo 'your string here'

22. Notes

23. Add shebang #!/usr/bin/php

24. Utilities:

25. BitBar PHP Formatter - https://github.com/SteveEdson/bitbar-php