Introduction

channelBar is a macOS application that lives in the menu bar and allows you to receive, display, and organize messages from various sources. The app serves as a central hub for notifications and status messages from your tools, automations, and smart home systems.

What makes channelBar special:

• Multiple channels: Organize messages into thematic categories
• Flexible inputs: Receive messages via URLs, webhooks, MQTT, files, and more
• Customizable outputs: Menu bar, system notifications, audio, or command-line application
• Powerful templates: Format messages exactly the way you want

---

Basic Concepts

Channels

A channel is a container for related messages. Think of channels as thematic folders:

• work – Messages from build systems, CI/CD pipelines
• home – Smart home notifications
• weather – Weather alerts and updates
• server – Monitoring alerts

Each channel has:

• A unique identifier (name)
• A position in the menu bar (order)
• Its own providers (inputs)
• Its own outputs (menu bar, notifications, audio)
• Its own templates for message formatting
• Retention rules (how many/how long messages are stored)

Messages

A message is the actual content that arrives in a channel via a provider. Each message contains:

Providers (Inputs)

Providers are the ways messages reach channelBar. There are eight different provider types:

Each channel can have multiple providers active at the same time.

Outputs

Outputs define how and where messages are displayed. Each channel has four independently configurable outputs:

Templates

Templates determine how messages are formatted and displayed. With variables like {message}, {date}, or {source}, you can customize the appearance individually.

---

The User Interface

Menu Bar

channelBar displays an element in the macOS menu bar for each active channel. Clicking opens the channel menu with:

• The current message (formatted according to template)
• The message history as a submenu
• Optional actions like "New Message..." or "Clear History..."

Menu Bar Icon: When enabled, a permanent channelBar icon also appears, giving you quick access to settings.

Settings Window

You can access the settings window via:

• Click on the channelBar icon → "Settings..."
• Right-click on any channel element → "Settings..."

The window has four tabs:

1. General – Global app settings
2. Channels – Channel and provider management
3. Connections – Server connections (MQTT, Home Assistant, Cloud)
4. Servers – Local servers (gRPC, Webhook)

---

General Settings

In the General tab you'll find:

Language

Choose the app's display language. Available options:

• System (automatic based on macOS setting)
• Deutsch
• English
• Español
• Français

The language change takes effect immediately, without restart.

Launch at Login

Enable this option so channelBar starts automatically when you log into macOS.

Always Show Menu Bar Icon

When enabled, channelBar always shows an icon in the menu bar – even when no channels are active. Useful for quick access to settings.

App Version

Shows the current version and build number of channelBar.

Command-Line Application

Shows the status of the connected command-line application, including version information and compatibility.

Configuration

Here you'll find the functions for exporting and importing your channelBar configuration. More on this in the chapter Exporting and Importing Configuration.

---

Managing Channels

Creating a Channel

1. Open Settings → Channels tab
2. Click on + (Plus) below the channel list
3. Enter an identifier (e.g., "work", "home")
4. Configure the desired settings
5. Click Save

A new channel is enabled by default and displayed in the menu bar.

Editing a Channel

Select a channel in the list to edit its settings. The settings are divided into several areas:

Basic Settings

Changing Position

Change the order of channels in the menu bar via drag & drop in the channel list.

Deleting a Channel

1. Select the channel in the list
2. Click on − (Minus) below the channel list
3. Confirm the deletion

Configuring Retention

Retention settings determine how long and how many messages are stored:

Cleanup happens automatically in the background. Both retention rules (count and days) are applied independently.

---

Providers in Detail

Providers are the inputs through which messages reach channelBar. Each channel can use multiple providers simultaneously.

URL Scheme

The URL scheme enables sending messages via URLs. This is ideal for:

• Automations with Automator or AppleScript
• Links in documents
• Other apps that can open URLs

Sending a Message

Format:

channelbar://set?channel=CHANNEL&text=MESSAGE

Parameters:

Examples:

Simple message:

channelbar://set?channel=work&text=Build%20successful

With source and link:

channelbar://set?channel=work&text=PR%20merged&source=GitHub&link=https://github.com/...

With open action:

channelbar://set?channel=logs&text=Error%20occurred&open=/Applications/Console.app&args=--search%20error

Setting Channel Context

Sets the context of a channel (without sending a message):

channelbar://context-set?channel=CHANNEL&context=VALUE

Removing Channel Context

Removes the context of a channel:

channelbar://context-remove?channel=CHANNEL

AppleScript Example

open location "channelbar://set?channel=test&text=Hello%20World"

Activation: The URL scheme provider is active by default and requires no additional configuration.

Webhook

The webhook provider provides an HTTP endpoint through which external systems can send messages.

Endpoint:

http://localhost:8080/message/{channel}

The channel name is specified as part of the path (URL-encoded if necessary).

HTTP Method: POST

Request Body (JSON):

{
  "text": "Deployment completed",
  "source": "CI/CD",
  "link": "https://ci.example.com/build/123",
  "open": "/Applications/Terminal.app",
  "message_context": "build_id=123",
  "channel_context": "env=production"
}

Only text is required. The channel is determined via the URL path.

Authentication

You can configure an API key per channel. When set, the request must include an X-API-Key header:

X-API-Key: YOUR_API_KEY

Configuration

1. Go to Settings → Channels → select channel
2. Switch to the Providers section
3. Enable Webhook
4. Optional: Set an API key

Server Settings (under Settings → Servers):

• Port: Default 8080 (changeable)
• Enable CORS: For browser-based clients
• Rate Limit: Requests per minute (default: 100)

cURL Examples

Simple message:

curl -X POST http://localhost:8080/message/work \
  -H "Content-Type: application/json" \
  -d '{"text":"Build successful"}'

With API key and all options:

curl -X POST http://localhost:8080/message/work \
  -H "Content-Type: application/json" \
  -H "X-API-Key: my-api-key" \
  -d '{"text":"PR #42 merged","source":"GitHub","link":"https://github.com/..."}'

MQTT

MQTT is a lightweight pub/sub protocol, ideal for IoT devices and home automation.

Configuration per channel:

Topic Patterns with Wildcards

channelBar supports MQTT wildcards:

• + – Any single segment: home/+/temperature
• # – All following segments: sensors/#

Examples:

• home/livingroom/temperature – Exact topic
• home/+/temperature – All rooms: home/kitchen/temperature, home/bathroom/temperature
• alerts/# – All alert topics

Setting up connection:

MQTT connections are managed centrally under Settings → Connections. See MQTT Connections.

Message format:

The message text is taken directly from the MQTT payload. For JSON payloads, you can use templates to extract specific fields.

File Watcher

The file watcher provider monitors local files and creates messages when changes occur.

Configuration:

Adding Paths

1. Click + next to "Watched Paths"
2. Select a file in the Finder dialog
3. channelBar automatically receives the necessary access permissions (sandbox bookmark)

How It Works

• The file is read line by line
• Each non-empty line becomes a separate message
• Only new content is processed (since last change)
• With "Delete After Reading" enabled, the file is cleared after reading
• File doesn't need to exist – channelBar waits for its creation

Message Format

Since the provider is assigned to a channel, each line is used directly as a message:

Backup completed at 14:30
Server status: OK
New email received

Each of these lines becomes a separate message in the configured channel.

Example Workflow

# Script writes lines to watched file
echo "Backup completed: $(date)" >> ~/channelbar-inbox.txt
echo "Next backup: tomorrow 03:00" >> ~/channelbar-inbox.txt

Apple Shortcuts

The Shortcuts integration enables sending messages via Apple Shortcuts (Shortcuts.app).

Available Action: "Send to channelBar"

Parameters:

Creating a Shortcut

1. Open Shortcuts (Shortcuts.app)
2. Create a new shortcut
3. Search for "channelBar" in actions
4. Add "Send to channelBar"
5. Configure the parameters

Activation

1. Go to Settings → Channels → select channel
2. Switch to the Providers section
3. Enable Apple Shortcuts

Home Assistant

The Home Assistant integration enables displaying entity states from your smart home.

Configuration per channel:

Finding Entity ID

1. Open Home Assistant
2. Go to Settings → Devices & Services → Entities
3. Find the desired entity
4. The Entity ID is shown in the detail view

Example Entity IDs:

• sensor.livingroom_temperature
• binary_sensor.front_door
• weather.home
• switch.desk_lamp

Setting up connection:

Home Assistant connections are managed under Settings → Connections. See Home Assistant Connections.

Command-Line Application

The provider receives messages from the local channelBar command-line application.

Activation

1. Go to Settings → Channels → select channel
2. Switch to the Providers section
3. Enable Command-Line Application

Communication:

The command-line application communicates via gRPC with the app (default: localhost:51515). Server settings are found under Settings → Servers → gRPC Server.

Cloud

The Cloud provider receives messages from the channelBar Cloud Service.

Concept:

The Cloud Service provides buffers – remote queues that can be filled by external tools. Each buffer can be assigned to a channel.

Configuration

1. Make sure the Cloud connection is active (see Cloud Connection)
2. Go to Settings → Channels → select channel
3. Switch to the Providers section
4. Enable Cloud
5. Select the buffers from which the channel should receive

Buffer Properties:

• Each buffer has a name and an API key
• External tools send messages to buffers via Cloud API
• The app receives messages in real-time

---

Outputs in Detail

Each channel has four independently configurable outputs.

Menu Bar Output

The primary output displays messages in the macOS menu bar.

Configuration:

Menu Structure

▶ Current Message
├── 📜 Message History
│   ├── Message 1
│   ├── Message 2
│   └── ...
├── ➕ New Message... (optional)
└── 🗑 Clear History... (optional)

You can configure the history menu display in detail under Customizing Submenu Display.

Notifications

Shows macOS system notifications for new messages.

Configuration:

Selecting Icon

1. Enable "Use Custom Icon"
2. Click "Select..."
3. Choose an image file (PNG, JPG recommended)

Template examples:

• {message} – Message text only
• {channel}: {message} – With channel name
• {source}: {message} – With source

Audio

Plays a sound for new messages.

Configuration:

System Sounds:

macOS offers numerous system sounds like:

• Basso, Blow, Bottle, Frog
• Funk, Glass, Hero, Morse
• Ping, Pop, Purr, Sosumi
• Submarine, Tink

Custom Audio File

1. Select "Custom File" as sound source
2. Click "Select..."
3. Choose an audio file (MP3, WAV, AIFF, etc.)

Preview: Use the Play button to test the selected sound.

Command-Line Application

For querying channel messages via the terminal.

Configuration:

How It Works:

When enabled, the command-line application can query messages in the channel.

Templates for Command-Line Application:

The command-line application output uses its own templates:

• channelbar get – Formatting for current message
• channelbar list – Formatting for history

See Template Contexts for details.

---

Configuring Templates

Templates determine how messages are formatted. Each channel has its own templates for different contexts.

Template Variables

The following variables are available in templates:

Formatting Date and Time

Date and time can be displayed with custom formats:

{date#FORMAT}
{time#FORMAT}

Format Characters:

Examples:

Template Contexts

Each channel has four different templates, divided into two groups:

App Templates:

Command-Line Templates:

Editing Templates

1. Go to Settings → Channels → select channel
2. Switch to the Templates section
3. Edit the desired templates under "App Templates" or "CLI Templates"
4. Changes are saved automatically

Example Templates:

# With source and time
[{source}] {message} ({relativeTime})

# Compact with date
{date#MM/dd} {time#HH:mm} - {message}

# With icon based on provider
{provider}: {message}

# Detailed for logs
[{date#yyyy-MM-dd}T{time#HH:mm:ss}] [{source}] {message}

---

Customizing Submenu Display

The history menu (submenu) can be configured in detail. These settings determine what information is displayed for each message in the history.

Display Options

Menu Functions

Submenu Element Templates

Each submenu element has its own template:

Customizing

1. Go to Settings → Channels → select channel
2. Switch to the Menu Bar section
3. Enable/disable the desired options
4. Customize templates as needed

---

Managing Connections

Under Settings → Connections you manage reusable server connections. These can be shared by multiple channels.

MQTT Connections

MQTT connections define the connection parameters to an MQTT broker.

Creating a New Connection

1. Click + next to MQTT Connections
2. Enter a name (e.g., "Local Mosquitto")
3. Configure the connection parameters

Parameters:

Example URLs:

• localhost:1883 – Local broker
• mqtt.example.com:8883 – Remote with TLS
• 192.168.1.100:1883 – IP address

Test Connection:

Click "Test Connection" to check broker reachability.

Security:

The MQTT password is securely stored in Apple Keychain – encrypted and only accessible to channelBar.

Home Assistant Connections

Home Assistant connections enable integration with your smart home hub.

Prerequisites:

• Home Assistant instance reachable on the network
• Long-Lived Access Token

Creating Access Token in Home Assistant

The access token allows channelBar secure access to your Home Assistant instance.

1. Open Home Assistant in browser (e.g., http://homeassistant.local:8123)
2. Click on your username at bottom left (your profile)
3. Scroll to the Long-Lived Access Tokens section at the bottom
4. Click Create Token
5. Enter a name, e.g., "channelBar"
6. Click OK
7. Important: Copy the displayed token immediately – it's only shown once!

The token looks something like:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI...

Creating New Connection in channelBar

1. Go to Settings → Connections
2. Click + next to Home Assistant Connections
3. Enter a name (e.g., "Home Assistant")
4. Configure the connection parameters

Parameters:

Cloud Connection

The Cloud connection enables use of the channelBar Cloud Service.

Status:

• Connected – Active connection to Cloud Service
• Disconnected – No connection
• Connecting... – Connection in progress

Activating Connection

1. Go to Settings → Connections
2. Enable "Cloud Connection"
3. Authentication happens automatically

Managing Buffers:

Once connected, your Cloud buffers are displayed:

• Buffer name
• API key (for sending from external tools)

New buffers can be created via the Cloud web interface.

---

Configuring Servers

Under Settings → Servers you configure channelBar's local server services.

CLI Server (Command-Line Application)

The CLI server enables communication with the channelBar command-line application.

Settings:

Valid Port Range: 1024 – 65535

Status Display:

• Running – Server is active and ready
• Stopped – Server is disabled
• Error – Startup error (e.g., port in use)

Version:

Shows the version of the connected command-line application and checks compatibility.

Webhook Server

The Webhook server receives HTTP requests from external systems.

Settings:

CORS (Cross-Origin Resource Sharing):

Enable CORS if you want to send webhooks from browser-based applications. When CORS is enabled, the appropriate HTTP headers are set.

Rate Limiting:

Protects against excessive load. Requests over the limit are answered with HTTP 429 (Too Many Requests).

Endpoints:

---

Exporting and Importing Configuration

channelBar allows exporting and importing your entire configuration. Ideal for:

• Backing up your settings
• Migrating to a new Mac
• Sharing configurations

Exporting

1. Go to Settings → General
2. Click Export
3. Choose a save location
4. The configuration is saved as a .channelbar file

Exported Data:

• All channels with settings
• All provider configurations
• All output configurations
• All templates
• All connections (MQTT, Home Assistant)
• General settings (language, launch at login, etc.)

Not Exported:

• Message history
• Cloud connection status
• Passwords, API keys, and other credentials – these must be re-entered after import

Importing

1. Go to Settings → General
2. Click Import
3. Select a .channelbar file
4. Confirm the import

---

Tips and Best Practices

Channel Organization

• Thematic Separation: One channel per topic area (work, home, monitoring)
• Clear Names: Choose descriptive identifiers
• Sensible Order: Important channels to the left

Provider Selection

Template Tips

• Short and concise: The menu bar has limited space
• Relative time: {relativeTime} is often more useful than absolute timestamps
• Label source: With multiple providers, {source} helps
• Use emojis: Visual distinction (⚠ warning, ✅ success, etc.)

Performance

• Limit retention: Don't store more than necessary
• Adjust display limit: 25-50 messages usually suffice
• Disable unused providers: Saves resources

Security

• Set API keys: Secure webhook endpoints
• Use TLS: For MQTT and Home Assistant when possible