Introduction

channelbar is a command-line tool for interacting with the channelBar app. It enables sending and retrieving messages, managing channels, setting context metadata, and cloud integration for cross-platform usage.

Basic Syntax

channelbar <COMMAND> [ARGUMENTS] [OPTIONS]

Getting Help

channelbar --help              # General help
channelbar <COMMAND> --help     # Help for a specific command

---

Platform Versions

The command-line application exists in two variants with different feature sets:

macOS Version (Full Version)

The macOS version communicates via the CLI server with the local channelBar app and provides full functionality:

Prerequisite: The channelBar app must be installed and running on the Mac.

Linux Version (Cloud-only)

The Linux version supports only cloud functions:

Note: On Linux, local commands (get, list, create, delete, info, enable, disable, context-*) are not available and are not shown in the help.

Command Overview by Availability

---

Configuration

The configuration is stored in a TOML file:

• macOS: ~/.channelbar/config.toml
• Linux: ~/.channelbar/config.toml

Show Configuration File

channelbar config show

Example output:

[app]
port = 51515
timeout_ms = 5000

[cli]
language = "en"

Show Configuration Path

channelbar config path

Configure Language

The command-line application supports four languages: German (de), English (en), French (fr), and Spanish (es).

# Show current language
channelbar config language

# Set language to English
channelbar config language en

Language Detection (Priority):

1. Configuration file (cli.language)
2. Environment variable LANG
3. Environment variable LC_ALL
4. System language
5. Fallback: English

Configure Connection Timeout

The timeout determines how long to wait for a connection to the channelBar app (in milliseconds).

# Show current timeout
channelbar config timeout

# Set timeout to 3 seconds
channelbar config timeout 3000

Configure Port (macOS only)

By default, the CLI communicates with the channelBar app on port 51515.

# Show current port
channelbar config port

# Change port
channelbar config port 51516

Port Resolution (Priority):

1. --port flag on command invocation
2. Environment variable CHANNELBAR_APP_PORT
3. Configuration file (app.port)
4. Default: 51515

Configure Cloud Buffers

Cloud buffers enable sending messages to channelBar Cloud. Buffers are stored in a separate file: ~/.channelbar/buffers.toml

# Add buffer
channelbar config buffer-add <NAME> <IDENTIFIER> <API_KEY>

# Example
channelbar config buffer-add server-alerts cbID123DEF45 xxxxxxxxxxxxx

# List buffers
channelbar config buffer-list

# Remove buffer
channelbar config buffer-remove server-alerts

Global Options

These options are available for all commands:

---

Commands in Detail

set — Send Message

Sends a message to a channel (local) or buffer (cloud).

Syntax:

channelbar set <CHANNEL|BUFFER> [MESSAGE] [OPTIONS]

Arguments:

• <CHANNEL|BUFFER> — Name of the target channel or cloud buffer
• [MESSAGE] — The message to send (optional, can also be passed via stdin)

Options:

Examples:

# Simple message
channelbar set status "Build completed successfully"

# Message with source and link
channelbar set deploy "Version 1.2.3 deployed" -s "CI/CD" -l "https://github.com/repo/releases/v1.2.3"

# Message via stdin (e.g., from a pipeline)
echo "Disk usage: 85%" | channelbar set monitoring

# Multi-line message via stdin
cat error.log | channelbar set logs -s "error-monitor"

# Message to cloud buffer
channelbar set server-alerts "CPU load critical: 95%" --cloud

# With context metadata
channelbar set metrics "Active users: 1523" -m '{"type":"gauge","unit":"users"}'

# Quiet execution in scripts
channelbar set backup "Backup completed" -q

---

get — Get Latest Message

Retrieves the latest message from a channel.

Syntax:

channelbar get <CHANNEL> [OPTIONS]

Options:

Examples:

# Get latest message
channelbar get status

# With timestamp
channelbar get status -v

# As JSON for processing
channelbar get metrics --json | jq '.message'

# As XML
channelbar get logs --xml

Note: If the channel is empty, an appropriate message is displayed (or an empty object for JSON/XML).

---

list — List Channels or Messages

Lists all channels or shows messages from a specific channel.

Syntax:

channelbar list [CHANNEL] [OPTIONS]

Arguments:

• [CHANNEL] — Optional: Name of the channel whose messages should be displayed

Options:

Examples:

# List all channels
channelbar list

# All channels as JSON
channelbar list --json

# Show messages from a channel
channelbar list logs

# Last 10 messages
channelbar list logs -L 10

# Oldest messages first
channelbar list logs -L 5 --ascending

# Detailed channel list
channelbar list -v

---

create — Create Channel

Creates a new channel in the channelBar app.

Syntax:

channelbar create <CHANNEL> [OPTIONS]

Options:

Examples:

# Create simple channel
channelbar create monitoring

# Channel with context
channelbar create server-status -c '{"environment":"production","team":"ops"}'

# Channel with custom templates
channelbar create alerts \
  --template-app-latest "{message}" \
  --template-cli-latest "[{source}] {message}"

# Quiet creation in scripts
channelbar create backup-status -q

Template Placeholders:

• {message} — The message text
• {source} — The source label (empty if not set)
• {link} — The associated link (empty if not set)
• {relativeTime} — Relative time (e.g., "5 minutes ago", "yesterday")
• {date#FORMAT} — Date with format (e.g., {date#yyyy-MM-dd})
• {time#FORMAT} — Time with format (e.g., {time#HH:mm:ss})

Format Placeholders:

• yyyy — 4-digit year
• MM — 2-digit month
• dd — 2-digit day
• HH — Hour (24h)
• mm — Minute
• ss — Second

---

delete — Delete Channel

Deletes a channel and all messages it contains.

Syntax:

channelbar delete <CHANNEL> [OPTIONS]

Options:

Examples:

# Interactive deletion (with confirmation)
channelbar delete old-logs
# Output: Delete channel 'old-logs' and all messages? [y/N]:

# Direct deletion without prompt
channelbar delete temp-channel --yes

# Quiet deletion in scripts
channelbar delete cleanup -y -q

---

info — Show Channel Information

Shows detailed information about a channel.

Syntax:

channelbar info <CHANNEL> [OPTIONS]

Options:

Examples:

# Show channel information
channelbar info monitoring

# As JSON for scripts
channelbar info status --json

Displayed Information:

• Channel name
• Enabled status (enabled/disabled)
• Number of messages
• Message limit
• Retention period
• Configured templates
• Context metadata

---

enable / disable — Enable/Disable Channel

Enables or disables a channel. Disabled channels do not accept new messages.

Syntax:

channelbar enable <CHANNEL> [OPTIONS]
channelbar disable <CHANNEL> [OPTIONS]

Options:

Examples:

# Disable channel (e.g., during maintenance)
channelbar disable alerts

# Re-enable channel
channelbar enable alerts

# Quiet execution
channelbar disable maintenance-channel -q

---

context-get — Get Channel Context

Retrieves the JSON metadata of a channel.

Syntax:

channelbar context-get <CHANNEL> [OPTIONS]

Options:

Examples:

# Get channel context
channelbar context-get monitoring

# As formatted JSON
channelbar context-get status --json | jq .

---

context-set — Set Channel Context

Sets or updates the JSON metadata of a channel.

Syntax:

channelbar context-set <CHANNEL> <CONTEXT> [OPTIONS]

Arguments:

• <CHANNEL> — Name of the channel
• <CONTEXT> — JSON string with the metadata

Options:

Examples:

# Set context
channelbar context-set monitoring '{"environment":"production","owner":"ops-team"}'

# Update context
channelbar context-set alerts '{"priority":"high","oncall":"team-a"}'

---

context-remove — Remove Channel Context

Removes the metadata of a channel.

Syntax:

channelbar context-remove <CHANNEL> [OPTIONS]

Options:

Examples:

# Remove context
channelbar context-remove old-channel

# Quiet execution
channelbar context-remove temp -q

---

ping — Check Connection

Checks the connection to the channelBar app or cloud.

Syntax:

channelbar ping [OPTIONS]

Options:

Examples:

# Check local app (macOS only)
channelbar ping
# Output: channelBar App: OK (v2.1.0)

# Check cloud connection
channelbar ping --cloud
# Output: server-alerts: OK

# In scripts (check exit code only)
if channelbar ping -q; then
  echo "App reachable"
fi

Exit Codes:

• 0 — Connection successful
• 1 — Connection failed

---

completions — Shell Completion

Generates shell completion scripts for various shells.

Syntax:

channelbar completions [SHELL]

Supported Shells:

• bash
• zsh
• fish
• powershell
• elvish

Examples:

# Show installation instructions
channelbar completions

# Generate bash completion
channelbar completions bash > ~/.local/share/bash-completion/completions/channelbar

# Generate zsh completion
channelbar completions zsh > ~/.zfunc/_channelbar

# Generate fish completion
channelbar completions fish > ~/.config/fish/completions/channelbar.fish

---

version — Show Version

Shows the current version of the command-line application.

Syntax:

channelbar version

Example:

channelbar version
# Output: channelbar X.Y.Z

---

Output Formats

channelbar supports three output formats:

Text Format (Default)

The default format for human readability:

channelbar get status
# Build successful at 14:32

channelbar list
# monitoring
# alerts
# logs

JSON Format

Structured format for machine processing:

channelbar get status --json

{
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "channelId": "660e8400-e29b-41d4-a716-446655440001",
  "text": "Build successful at 14:32",
  "provider": "cli",
  "source": "CI/CD",
  "createdAt": 1705325520.0,
  "link": null,
  "open": null,
  "openArgs": null,
  "messageContext": null,
  "channelContext": null
}

channelbar list --json

[
  {
    "identifier": "monitoring",
    "enabled": true,
    "displayLimit": 25,
    "retentionCount": 500,
    "retentionDays": 30,
    "channelContext": null
  },
  {
    "identifier": "alerts",
    "enabled": true,
    "displayLimit": 25,
    "retentionCount": null,
    "retentionDays": null,
    "channelContext": "{\"priority\":\"high\"}"
  }
]

XML Format

Alternative structured format:

channelbar get status --xml

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <messageId>550e8400-e29b-41d4-a716-446655440000</messageId>
  <channelId>660e8400-e29b-41d4-a716-446655440001</channelId>
  <text>Build successful at 14:32</text>
  <provider>cli</provider>
  <source>CI/CD</source>
  <createdAt>1705325520.0</createdAt>
  <link/>
  <open/>
  <openArgs/>
  <messageContext/>
  <channelContext/>
</message>

Note: --json and --xml are mutually exclusive.

---

Error Handling

Exit Codes

Handling Errors in Scripts

#!/bin/bash

# Check if app is running
if ! channelbar ping -q; then
  echo "channelBar app not reachable" >&2
  exit 1
fi

# Send message with error handling
if channelbar set status "Deployment started" -q; then
  echo "Notification sent"
else
  echo "Error sending notification" >&2
fi

# Evaluate exit code
channelbar get metrics --json
case $? in
  0) echo "Success" ;;
  1) echo "Connection error" ;;
  2) echo "Validation error" ;;
  3) echo "Channel not found" ;;
esac

---

Practical Examples

Build Notifications

Integration into CI/CD pipelines for build status notifications:

#!/bin/bash
# build-notify.sh

PROJECT="my-project"
BRANCH=$(git branch --show-current)

# Start build
channelbar set builds "Build started: $PROJECT ($BRANCH)" -s "CI" -q

if make build; then
  channelbar set builds "Build successful: $PROJECT ($BRANCH)" \
    -s "CI" \
    -l "https://ci.example.com/builds/$BUILD_ID"
else
  channelbar set builds "Build failed: $PROJECT ($BRANCH)" \
    -s "CI" \
    -l "https://ci.example.com/builds/$BUILD_ID"
  exit 1
fi

Server Monitoring

Monitoring system resources with regular updates:

#!/bin/bash
# system-monitor.sh

HOSTNAME=$(hostname)

# CPU load
CPU=$(top -l 1 | grep "CPU usage" | awk '{print $3}')

# Memory
MEM=$(vm_stat | awk '/Pages active/ {print $3}' | sed 's/\.//')

# Disk
DISK=$(df -h / | awk 'NR==2 {print $5}')

# Send to cloud (for Linux servers)
channelbar set server-metrics \
  "[$HOSTNAME] CPU: $CPU, Memory: active, Disk: $DISK" \
  -s "$HOSTNAME" \
  -m "{\"cpu\":\"$CPU\",\"disk\":\"$DISK\"}" \
  --cloud

Log Aggregation

Forward important log entries to channelBar:

#!/bin/bash
# error-watcher.sh

tail -F /var/log/application.log | while read line; do
  if echo "$line" | grep -q "ERROR\|CRITICAL"; then
    channelbar set app-errors "$line" -s "error-watcher" -q
  fi
done

Deployment Tracking

Complete deployment tracking with context:

#!/bin/bash
# deploy.sh

VERSION=$1
ENVIRONMENT=$2

# Prepare deployment channel
channelbar context-set deployments "{
  \"current_version\": \"$VERSION\",
  \"environment\": \"$ENVIRONMENT\",
  \"deployed_at\": \"$(date -Iseconds)\",
  \"deployed_by\": \"$USER\"
}"

# Status updates
channelbar set deployments "Deployment $VERSION to $ENVIRONMENT started" \
  -s "deploy-script"

# ... deployment steps ...

channelbar set deployments "Deployment $VERSION to $ENVIRONMENT completed" \
  -s "deploy-script" \
  -l "https://app.example.com"

Backup Notifications

Automatic notifications for backup jobs:

#!/bin/bash
# backup-notify.sh

BACKUP_NAME=$1
BACKUP_SIZE=$(du -sh "$BACKUP_PATH" | cut -f1)

if [ $? -eq 0 ]; then
  channelbar set backups \
    "Backup '$BACKUP_NAME' successful ($BACKUP_SIZE)" \
    -s "backup-system" \
    -m "{\"size\":\"$BACKUP_SIZE\",\"path\":\"$BACKUP_PATH\"}"
else
  channelbar set backups \
    "Backup '$BACKUP_NAME' failed" \
    -s "backup-system"
fi

Cron Job Monitoring

Notification about cron job execution:

# In crontab:
# 0 * * * * /path/to/hourly-job.sh 2>&1 | channelbar set cron-jobs -s "hourly-cleanup"

# Or with more detailed tracking:
#!/bin/bash
# cron-wrapper.sh

JOB_NAME=$1
shift

START=$(date +%s)
OUTPUT=$("$@" 2>&1)
EXIT_CODE=$?
END=$(date +%s)
DURATION=$((END - START))

if [ $EXIT_CODE -eq 0 ]; then
  channelbar set cron-jobs \
    "$JOB_NAME completed (${DURATION}s)" \
    -s "cron" \
    -m "{\"duration\":$DURATION,\"exit_code\":$EXIT_CODE}" \
    -q
else
  echo "$OUTPUT" | channelbar set cron-jobs \
    -s "cron [$JOB_NAME]"
  channelbar set cron-jobs \
    "$JOB_NAME failed (Exit: $EXIT_CODE)" \
    -s "cron"
fi

Multi-Server Setup with Cloud

Centralized notifications from multiple Linux servers:

# On each server (Linux - cloud mode only):

# Configure buffer once
channelbar config buffer-add production abc123 sk-live-xxxxx

# Then in scripts:
channelbar set production \
  "[$(hostname)] Service restarted" \
  -s "systemd" \
  --cloud

Interactive Usage

Quick notes and reminders via the command line:

# Quick note
channelbar set notes "Meeting at 3:00 PM with team"

# Multi-line input (interactive)
channelbar set notes
# Output: Enter message (Ctrl+D to send):

# Send clipboard content (macOS)
pbpaste | channelbar set clipboard -s "clipboard"

# Send command output directly
ls -la | channelbar set shell-output -s "ls"

Using Channel Templates

Custom output formats for different use cases:

# Create channel with simple template
channelbar create alerts \
  --template-cli-latest "[{source}] {message}" \
  --template-cli-history "{time#HH:mm} [{source}] {message}"

# Messages are then formatted:
channelbar set alerts "CPU load high" -s "monitor"
channelbar get alerts
# Output: [monitor] CPU load high

channelbar list alerts
# Output:
# 14:32 [monitor] CPU load high
# 14:28 [backup] Backup started
# 14:15 [deploy] Version 1.2.3 deployed

---

Tips and Best Practices

Efficient Usage

1. Quiet mode in scripts: Use -q to suppress unnecessary output
2. Check exit codes: Use exit codes for error handling in scripts
3. JSON for automation: Use --json when output needs to be processed
4. Use context: Store metadata in channel context for structured information

Security

1. Protect API keys: Never store cloud API keys in scripts, use the configuration
2. Sensitive data: Do not send passwords or sensitive data through channels
3. Buffer permissions: Each buffer has its own permissions in the cloud