clisense

A fast, keyboard-driven terminal UI for administering a Typesense instance — built with Bubble Tea.

clisense gives you a tabbed, full-screen TUI to browse and manage the building blocks of a Typesense deployment without juggling curl commands: collections, aliases, natural-language search models, curations, synonyms, stopwords, presets, and conversation models. Each resource has an embedded JSON editor seeded from sensible templates, plus guided wizards for the trickier ones.

Targets the Typesense API as documented for v30.2.

---

Features

• Polished terminal UI — an app header, a scrolling tab bar, and titled rounded-border panels with a focus-highlighted active pane, built on an adaptive (light/dark aware) lipgloss color theme.
• Tabbed admin console — switch between resource types with number keys or Tab/Shift+Tab.
• Collections — list, inspect, update (PATCH), delete, and run ad-hoc document searches.
• Aliases — list, view, upsert, and delete collection aliases.
• NL Search Models — manage natural-language search models.
• Curations — manage curation sets, with a step-by-step curation wizard and a document picker (Ctrl+F) to pin/hide results.
• Synonyms — manage synonym sets with a dedicated synonym wizard.
• Stopwords — manage stopword sets.
• Presets — manage reusable search presets.
• Conversations — manage conversation models and test conversational search.
• API Keys — list keys with their scoped actions/collections, create new keys, and delete them. The generated secret is shown once at creation time (Typesense never returns it again), so copy it immediately. Keys are immutable, so editing is intentionally disabled.
• Analytics — manage analytics rules (popular_queries, nohits_queries, counter, log): create, edit, and delete.
• Cluster — operational dashboard showing /health, /stats.json, /metrics.json, and /debug, plus confirm-gated maintenance operations: create snapshot, compact the on-disk DB, trigger leader re-election (vote), and clear the search cache.
• Embedded JSON editor — every create/update flow opens a JSON editor pre-filled from a template.
• First-run setup — a guided setup screen captures your Typesense URL and API key, persisted to a config file.

Requirements

• Go 1.25+ (only needed to build from source)
• A reachable Typesense server and an API key with admin privileges

Installation

Download a release binary

Pre-built Linux binaries (amd64 and arm64) are published on the Releases page. Download the archive for your platform, extract it, and put the binary on your PATH:

tar -xzf clisense_*_linux_amd64.tar.gz
sudo mv clisense /usr/local/bin/

Build from source

git clone https://github.com/ekrist1/typesensecli.git
cd typesensecli
go build -o clisense .

Install with go install

go install github.com/ekrist1/typesensecli@latest

The resulting binary is named clisense.

Usage

Launch the TUI:

clisense

On first run (or if no config is found) you'll be dropped into the setup screen. Enter your Typesense URL (e.g. http://localhost:8108) and API key; they're saved to your config file and reused on subsequent launches. You can change them later from the Settings tab.

Keybindings

Key	Action
1–9	Jump directly to one of the first nine tabs
Tab / Shift+Tab	Cycle to the next / previous tab (use this to reach tabs beyond the ninth)
c	Open the cluster picker (from any normal tab)
q	Quit
Ctrl+C	Quit (always)
Esc	Leave Settings and return to Collections, or the first visible tab if Collections is hidden
Ctrl+F	Open the document picker (in the curation wizard)
← / →	In Settings, cycle through configured clusters (and the + new slot)

When a modal, wizard, or text input is open, q, the number keys, and Tab are passed through to the input instead of triggering global navigation.

Configuration

Configuration lives in a TOML file:

• $XDG_CONFIG_HOME/clisense/config.toml if XDG_CONFIG_HOME is set, otherwise
• ~/.config/clisense/config.toml

It is created automatically by the setup screen, but you can also write it by hand:

[global]
default_cluster = "local"

[clusters.local]
url = "http://localhost:8108"

[clusters.production]
url = "https://typesense.example.com"

[tabs]
order = [
  "collections",
  "aliases",
  "nl_models",
  "curations",
  "synonyms",
  "stopwords",
  "presets",
  "conversations",
  "api_keys",
  "analytics",
  "cluster",
  "settings",
]

global.default_cluster selects the cluster used on launch. Press c from any normal tab to open the cluster picker, choose with ↑ / ↓ or j / k, then press Enter to switch and save it as the default. In Settings, cycle through configured clusters (and a trailing + new slot) with ← / → while focused on the Cluster field.

The tabs.order list controls both which tabs are shown and where they appear. Remove a tab ID to hide it, or reorder the IDs to change the tab bar placement. Valid IDs are collections, aliases, nl_models, curations, synonyms, stopwords, presets, conversations, api_keys, analytics, cluster, and settings.

A legacy config.yaml in the same directory is still loaded if no config.toml is present.

config.toml and secrets.toml are written with 0600 permissions. secrets.toml is the sensitive file because it holds your API keys.

Secrets

API keys are kept in a sidecar secrets.toml next to config.toml so the main config can be committed to a dotfiles repo. Both files live in the same directory.

# secrets.toml — keep out of version control
[clusters.local]
api_key = "your-local-admin-api-key"

[clusters.production]
api_key = "your-production-admin-api-key"

The first time clisense loads a config.toml that still has inline api_key values, it migrates them into a freshly written secrets.toml and rewrites config.toml without the keys. Subsequent saves keep them split. Add secrets.toml to your .gitignore (or use **/secrets.toml) before committing.

Project layout

.
├── main.go                  # entrypoint: load config, start the TUI
├── internal/
│   ├── config/              # read/write the on-disk TOML config
│   ├── client/              # thin HTTP wrapper + Typesense endpoint helpers
│   ├── templates/           # embedded JSON skeletons for the editor
│   └── tui/
│       ├── app.go           # root model, tab routing, global keybindings
│       ├── components/      # reusable widgets (JSON editor, tab bar, doc picker, …)
│       └── screens/         # one screen per resource type + setup/settings
└── .goreleaser.yaml         # release build configuration

The client package is intentionally thin: each endpoint helper returns the (method, path) pair for a Typesense API route, and Client.Do performs the request. HTTP error statuses (4xx/5xx) are returned as data so the UI can render the server's error message.

Development

go test ./...      # run the test suite
go build -o clisense .
go vet ./...

Releasing

Releases are produced by GoReleaser and automated via GitHub Actions. Pushing a semver tag builds the Linux binaries and publishes a GitHub Release:

git tag v0.1.0
git push origin v0.1.0

See .github/workflows/release.yml and .goreleaser.yaml.

License

No license has been declared yet. Add a LICENSE file to clarify how others may use this project.