A terminal-based search and kanban board for beads issue tracking.

• Query syntax for filtering issues
• Fields: type, priority, status, blocked, ready, label, title, id, created, updated
• Operators: = != < > <= >= ~ (contains) !~ (not contains) in not-in
• Boolean logic: and, or, not, parentheses
• Sorting: order by field asc/desc
• Date filters: today, yesterday, -7d, -24h, -3m

• Four-column default layout: Blocked, Ready, In Progress, Closed
• Fully customizable columns with BQL queries or view an issues dependency tree
• Multi-view support - create unlimited board views
• Real-time auto-refresh when database changes
• Column management: add, edit, reorder, delete

• Full-screen BQL-powered search interface
• Save searches as kanban columns
• Create new views from search results
• Sub-mode for viewing issue dependencies and hierarchies

• View detailed issue information with markdown rendering
• Edit priority, status, and labels inline
• Navigate to dependency issues
• Copy issue IDs to clipboard

Use ctrl+space to switch modes between Kanban and Search or while on a column use / to be dropped into search mode with the current columns BQL query.

Use ctrl+s from search mode to save the BQL query to a new or existing view

Use a from kanban mode to add a new column

Use h and l to move left and right between columns, ctrl+h / ctrl+l to move column positions and ctrl+n / ctrl+p to switch between views. Use ctrl+v to open the view menu to create, rename or delete a view.

• A beads-enabled project (.beads/ directory with beads.db)

curl -sSL https://raw.githubusercontent.com/zjrosen/perles/main/install.sh | bash

brew tap zjrosen/perles
brew install perles

Requires Go 1.21+

go install github.com/zjrosen/perles@latest

git clone https://github.com/zjrosen/perles.git
cd perles
make install
perles

Pre-built binaries for Linux and macOS (both Intel and Apple Silicon) are available on the Releases page.

1. Download the archive for your platform
2. Extract: tar -xzf perles_*.tar.gz
3. Move to PATH: sudo mv perles /usr/local/bin/
4. Verify: perles --version

Run perles in any directory containing a .beads/ folder:

cd your-project
perles

The default view includes these columns (all configurable via BQL):

Perles uses BQL (Beads Query Language) to filter and organize issues. BQL is used in column definitions and search mode.

field operator value [and|or field operator value ...]

# AND - both conditions must match
status = open and priority = P0

# OR - either condition matches
type = bug or type = feature

# NOT - negate a condition
not blocked = true

# Parentheses for grouping
(type = bug or type = feature) and priority <= P1

# Relative dates
created >= -7d          # Last 7 days
updated >= -24h         # Last 24 hours
created >= -3m          # Last 3 months

# Named dates
created >= today
created >= yesterday

# Single field
status = open order by priority

# Multiple fields with direction
type = bug order by priority asc, created desc

The expand keyword includes related issues in your search results, allowing you to see complete issue hierarchies and dependency chains.

# Basic syntax
<filter> expand <direction> [depth <n>]

# Get an epic and all its children
type = epic expand down

# Get an epic and all descendants (unlimited depth)
type = epic expand down depth *

# Get an issue and everything blocking it
id = bd-123 expand up

# Get an issue and all related issues (both directions)
id = bd-123 expand all depth *

# Get all epics with their full hierarchies
type = epic expand all depth *

# Critical bugs
type = bug and priority = P0

# Ready work, excluding backlog
status = open and ready = true and label not in (backlog)

# Recently updated high-priority items
priority <= P1 and updated >= -24h order by updated desc

# Search by title
title ~ authentication or title ~ login

# Epic with all its children
type = epic expand down depth *

Perles looks for configuration in these locations (in order):

1. --config flag
2. .perles/config.yaml (current directory)
3. ~/.config/perles/config.yaml

# Path to beads database directory (default: current directory)
# beads_dir: /path/to/project

# Auto-refresh when database changes
auto_refresh: true

# UI settings
ui:
  show_counts: true
  show_status_bar: true

# Theme (use a preset or customize colors)
theme:
  # preset: catppuccin-mocha  # Uncomment to use a theme preset
  # colors:                    # Override specific colors
  #   text.primary: "#FFFFFF"
  #   status.error: "#FF0000"

# Board views
views:
  - name: Default
    columns:
      - name: Blocked
        type: bql
        query: "status = open and blocked = true"
        color: "#FF8787"
      - name: Ready
        query: "status = open and ready = true"
        color: "#73F59F"
      - name: In Progress
        type: bql
        query: "status = in_progress"
        color: "#54A0FF"
      - name: Closed
        type: bql
        query: "status = closed"
        color: "#BBBBBB"

  - name: Bugs Only
    columns:
      - name: Open Bugs
        type: bql
        query: "type = bug and status = open"
        color: "#EF4444"
      - name: In Progress
        type: bql
        query: "type = bug and status = in_progress"
        color: "#F59E0B"
      - name: Fixed
        type: bql
        query: "type = bug and status = closed"
        color: "#10B981"

  - name: Work
    columns:
      - name: Current
        type: tree
        issue_id: bd-123
        tree_mode: child
        color: "#EF4444"

Perles supports comprehensive theming with built-in presets and customizable color tokens.

Use a built-in theme preset by adding to your config:

theme:
  preset: catppuccin-mocha

Run perles themes to see all available presets:

Override specific colors while using a preset:

theme:
  preset: dracula
  colors:
    status.error: "#FF0000"
    priority.critical: "#FF5555"

Or create a fully custom theme:

theme:
  colors:
    text.primary: "#FFFFFF"
    text.muted: "#888888"
    status.success: "#00FF00"
    status.error: "#FF0000"
    border.default: "#444444"
    border.focus: "#FFFFFF"

Colors are organized by category:

See internal/ui/styles/tokens.go for the complete list of 51 color tokens.

Developer mode provides logging and debugging tools for troubleshooting and development.

# Via flag
perles --debug

# Via environment variable
PERLES_DEBUG=1 perles

# With custom log path
PERLES_LOG=/tmp/perles.log perles --debug

• Log file: All log output is written to debug.log (or custom path via PERLES_LOG)
• Log overlay: Press Ctrl+X to view logs in-app without leaving the TUI
• Lifecycle logging: Application startup and shutdown events are logged

When reporting bugs, please include the debug.log file to help with diagnosis:

1. Run perles with --debug flag
2. Reproduce the issue
3. Attach debug.log to your bug report

Run tests:

make test        # Run all tests
make test-v      # Run with verbose output

Some tests use teatest for snapshot testing of TUI output. These tests compare rendered output against golden files stored in testdata/ directories.

When you intentionally change UI output, update the golden files:

make test-update

This regenerates golden files in packages with teatest tests (currently internal/ui/help). Review the changes before committing to ensure they're expected.

MIT