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 nine 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.

Group by Source

When enabled, messages in the history menu are grouped by their source label. Each source appears as a separate submenu section.

Text Truncation

---

Providers

Providers are the inputs through which messages reach channelBar. Each channel can use multiple providers simultaneously. Each provider has its own dedicated documentation page.

See the Providers section for detailed documentation of each provider.

---

Message Filters

Each channel can define filter rules to control which messages are accepted. Messages that do not match the filter criteria are discarded.

Filter Configuration

Multiple filters can be configured per channel. A message must match at least one filter to be accepted. If no filters are configured, all messages are accepted.

Examples

• Only errors: Match Type contains, Target message, Pattern error – accepts only messages containing "error"
• Specific source: Match Type contains, Target messageContext, Pattern production – accepts messages with "production" in context

---

Processor Pipelines

Processor Pipelines are reusable data transformation chains that process message values before display. They are particularly useful with MQTT topics and Home Assistant entities.

A pipeline consists of one or more steps that are applied in sequence. Each step transforms or filters the value before passing it to the next step.

Available Steps

Round

Rounds numeric values to a specified number of decimal places.

Threshold

Filters values based on a numeric comparison. Only values matching the condition are passed through.

Filter

Matches values against a text pattern. Only matching (or non-matching) values pass through.

Map

Transforms values using a lookup table. Maps input values to configured output values.

Replace

Performs search-and-replace on the value.

Trim

Removes unwanted characters from the value.

Usage

Processor Pipelines are linked to individual MQTT topics or Home Assistant entities via the Processor setting. A single pipeline can be reused across multiple topics and entities.

---

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

Additional App Templates

In addition to the main templates, each channel has the following app templates:

Conditional Rendering

Templates support conditional rendering using the syntax:

{variable[condition,prefix,postfix]}

The prefix and postfix are only shown if the condition is met.

Operators:

Escape Sequences

Templates support the following escape sequences:

• \n – Newline
• \t – Tab
• \\ – Literal backslash

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

---

Advanced Settings

The Advanced tab in Settings provides storage management and global podcast configuration. It is divided into two main areas, accessible via a sidebar: Storage and Podcasts.

Storage

Messages

Displays message storage statistics and provides tools to manage stored messages.

• Overview showing total message count and number of channels
• Expandable list of channels with message count and per-source breakdown
• Delete messages per channel or per source

Deletion options:

• Delete all messages
• Delete messages older than a specified number of days, months, or years
• Delete messages before a specific date

Cache

Displays and manages cached images used by channelBar.

Podcasts

Global Settings

Default podcast settings that apply to all feeds unless overridden per feed.

Expert Settings

Fine-tuning options for streaming and download behavior.

Downloads

Manage downloaded podcast episodes. Each entry shows the episode title, feed name, file size, and download status (Pending, Downloading, Completed, or Failed).

Available actions:

• Cancel active downloads
• Retry failed downloads
• Delete individual episodes
• Delete all downloads
• Retry all failed downloads

---

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