TopicConsole

A cross-platform desktop client for Apache Pulsar®. Built for developers who want clarity, not complexity.

English · 简体中文

---

Status: TopicConsole is v0.1.x — early and actively developed. APIs and UI may change before 1.0. Feedback and bug reports are very welcome.

Table of Contents

• Why TopicConsole?
• Features
• Screenshots
• Installation
• Quick Start
• Configuration
• Building from Source
• Architecture
• Tech Stack
• Contributing
• License

Why TopicConsole?

Most streaming GUIs are heavy, slow, or require a running server. TopicConsole is a single self-contained binary (~15 MB) that connects directly to your Pulsar brokers — no Docker, no JVM, no cloud account.

	TopicConsole	Typical alternatives
Install size	~15 MB binary	200–500 MB + JVM / Docker
Startup	Instant	5–30 seconds
Read without side effects	Observer mode — reads without creating a durable subscription	Rare or absent
Credentials	Stored in a local config file	Config files
Platforms	macOS · Windows · Linux	Often macOS / Linux only

No Docker. No JVM. No cloud account.

Features

🔎 Stream messages in real time

• Observer mode — read with a Pulsar Reader, without creating a durable subscription
• Subscription mode — consume through a Pulsar subscription and acknowledge when you're ready
• Live regex filter — filter by key / value while the stream is running
• Multi-tab — stream multiple topics side by side
• Export — save the message buffer to JSON or CSV
• Virtualized list — 50 000+ messages, no freezing

🛠️ Admin operations

• Browse live Pulsar tenants and namespaces, then manage topics in the main view
• Create non-partitioned or partitioned persistent topics; delete non-partitioned persistent topics
• View namespace-level topic, producer, consumer, subscription, and backlog counts
• List topic subscriptions from Pulsar Admin
• Produce messages with key, value, and headers; matching local Avro schemas encode JSON values automatically

🔌 Broker connections

• Pulsar service / admin URLs with live tenant and namespace discovery
• Multiple named credentials per broker — swap active credentials from the dashboard
• Import / export settings as JSON backup (includes topic groups and pinned topics)

📁 Topic organisation

• Pinned topics — star your most-used topics so they always appear first
• Topic groups — organise topics into named folders
• Advanced search — scan from the beginning with bounded matches and regex filters

🖥️ Brokers

• Manage Pulsar brokers as one flat list — no environment grouping in the UI
• Switch configs instantly from the top bar or ⌘K without disrupting running sessions

Screenshots

Installation

Download the latest build from the Releases page.

Platform	File	Notes
macOS (Apple Silicon)	topicconsole-darwin-arm64.zip	Drag TopicConsole.app to Applications
macOS (Intel)	topicconsole-darwin-amd64.zip	Drag TopicConsole.app to Applications
Windows	topicconsole-amd64-installer.exe	Requires WebView2 (pre-installed on Windows 11)
Linux	topicconsole-linux-amd64.tar.gz	See Linux notes below

macOS — first launch: right-click the app → Open if blocked by Gatekeeper. If you see "TopicConsole.app is damaged and can't be opened", clear the quarantine attribute:

xattr -cr /path/to/TopicConsole.app

Linux runtime dependencies for the published build:

The Linux archive built by GitHub Actions uses Wails' webkit2_41 build tag. On Debian/Ubuntu systems that provide WebKitGTK 4.1, install:

sudo apt-get install libgtk-3-0 libwebkit2gtk-4.1-0 libsecret-1-0

Quick Start

1. Launch TopicConsole — the main window opens with an empty sidebar.
2. Press ⌘, (macOS) or Ctrl+, (Windows/Linux) to open Settings.
3. Click Add Broker, fill in the Pulsar service / admin URLs, then Test Connection.
4. Save and close Settings — your config appears in the top bar.
5. Use the left sidebar to select a tenant and namespace, then manage topics in the main view.
6. Click a topic → Observe (reader, no durable cursor) or Consume (subscription with ack).

Keyboard shortcuts

Shortcut	Action
⌘K / Ctrl+K	Broker switcher
⌘, / Ctrl+,	Settings

Configuration

File	Location
.topicconsole.json	The current working directory if the file already exists there; otherwise $HOME/.topicconsole.json

.topicconsole.json stores Pulsar broker URLs, connection metadata, topic groups, pinned topics, and Pulsar bearer tokens in plaintext. Back it up or inspect it freely — and keep in mind that anyone with read access to the file can read your tokens.

Building from Source

Prerequisites: Go 1.25+, Node.js 18+, and the Wails CLI.

# 1. Install the Wails CLI
go install github.com/wailsapp/wails/v2/cmd/wails@v2.13.0

Platform prerequisites:

• macOS: xcode-select --install
• Linux: sudo apt-get install libgtk-3-dev libwebkit2gtk-4.1-dev libsecret-1-dev
• Windows: WebView2 runtime (pre-installed on Windows 11)

# 2. Clone and run
git clone https://github.com/yanbo92/topicconsole.git
cd topicconsole

make dev        # development with hot reload  (equivalent to: wails dev)
make build      # production build for the current platform

For a Linux build that matches the published Actions artifact, use make build-linux so the webkit2_41 build tag is applied.

Build other local platforms with the included Makefile targets:

make build-mac       # macOS Intel        (darwin/amd64)
make build-mac-arm   # macOS Apple Silicon(darwin/arm64)
make build-linux     # Linux amd64

Windows executables and NSIS installers are built only by GitHub Actions. Use the workflow's manual dispatch for a selected target, or push a v* tag to build the full release matrix.

Output lands in build/bin/. See make help for the full target list, and ARCHITECTURE.md for how the pieces fit together.

Other useful targets:

make check          # go vet + go test
make lint           # go vet + frontend ESLint
make verify         # full local verification (lint + tests + frontend build)
make pulsar-up      # spin up a local Pulsar standalone via Docker for testing

Architecture

• main.go boots Wails, embeds frontend/dist, and binds a single App.
• app.go is the Wails RPC boundary — public methods on App are callable from the frontend.
• internal/ holds the backend domain logic, persistence, broker integrations, and lifecycle managers.
• frontend/src/ is the React desktop UI; frontend/src/shared/api/ is the single entry point for Wails bindings.

See ARCHITECTURE.md for the full package map, event flow, and invariants.

Tech Stack

Layer	Technology
Native window & RPC bridge	Wails v2
Pulsar client	pulsar-client-go
UI components	shadcn/ui + Tailwind CSS
State management	Zustand
Frontend build	Vite + React 18 + TypeScript
List virtualisation	@tanstack/react-virtual

Contributing

Pull requests are welcome! For larger changes, please open an issue first to discuss what you'd like to change.

After changing public methods on the App struct, regenerate the TypeScript bindings:

make generate      # equivalent to: wails generate module

Before opening a PR, make sure local checks pass:

make verify

License

TopicConsole is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

This project is derived from kafkalet, which is licensed under the MIT License. MIT-licensed portions originating from kafkalet remain under MIT; see NOTICE for the full attribution and the third-party license text.

---

_{Apache Pulsar® is a registered trademark of the Apache Software Foundation. TopicConsole is an independent project and is not affiliated with or endorsed by the ASF.}