Alloy TUI Guide & Keybinding Cheat Sheet

The Alloy TUI is a terminal-based interface for managing projects, tickets, and sprints. It uses vim-style modal editing — if you know vim, you already know how to navigate.

Launching the TUI

# Default — connects to http://localhost:3000
cargo run --bin alloy-tui

# Custom API server
ALLOY_BASE_URL=https://api.example.com cargo run --bin alloy-tui

# Or export first
export ALLOY_BASE_URL=http://localhost:3000
cargo run --bin alloy-tui

If you have the alloy-tui binary on your PATH:

alloy-tui
ALLOY_BASE_URL=https://api.example.com alloy-tui

Configuration

Variable	Default	Description
`ALLOY_BASE_URL`	`http://localhost:3000`	Alloy API server URL
`ALLOY_ORG_ID`	(auto-discovered)	Organization ID override

Auto-Discover Behavior

On startup the TUI automatically discovers your organization:

If ALLOY_ORG_ID is set, that value is used directly.
Otherwise, once connected to the API, the TUI calls GET /api/v1/auth/me and extracts org_id from the response.
After org_id is resolved, projects, tickets, and labels are fetched automatically.

This means you can launch the TUI without any configuration beyond ALLOY_BASE_URL and a valid API key — the org is detected for you.

Modes

The TUI has four modes, displayed in the status bar with distinct colors.

Mode	Color	How to enter	How to exit	Purpose
Normal	Blue	`Esc` from any mode	—	Navigate, select, trigger actions
Insert	Green	`i` from Normal	`Esc`	Edit text fields
Command	Yellow	`:` from Normal	`Esc` or `Enter`	Run commands like `:q`, `:sort`
Search	Magenta	`/` from Normal	`Esc`	Real-time ticket search

If you are new to vim-style modes: you start in Normal mode. Press keys to navigate (they are not typed into a text field). Switch to Insert mode to type text, Command mode to enter commands, or Search mode to filter tickets. Press Esc to return to Normal.

Views

Ticket List

The default view. Shows all tickets in a table with columns for Key, Title, Status, Assignee, and Priority.

Key	Action
`j` / `Down`	Move cursor down
`k` / `Up`	Move cursor up
`gg`	Jump to first ticket
`G`	Jump to last ticket
`Enter`	Open ticket detail
`Tab`	Cycle project filter (All → each project → All)
`/`	Enter Search mode
`n`	Create new ticket (see Ticket Creation)
`l`	Manage labels on selected ticket
`t`	Log time against selected ticket
`d`	Delete selected ticket
`D`	Cascade delete (ticket + dependents)
`?`	Show help overlay
`q`	Quit

Ticket Detail

Full view of a single ticket: status, priority, assignee, reporter, sprint, timestamps, description (word-wrapped), and comments.

Key	Action
`j` / `Down`	Scroll down
`k` / `Up`	Scroll up
`gg`	Scroll to top
`G`	Scroll to bottom
`n`	Create new ticket
`l`	Manage labels on this ticket
`t`	Log time against this ticket
`d`	Delete this ticket
`D`	Cascade delete (ticket + dependents)
`Esc` / `q`	Return to ticket list

Sprint Board

Horizontal kanban board showing tickets grouped by status columns.

Key	Action
`h` / `Left`	Move to previous column
`l` / `Right`	Move to next column
`Tab`	Next column
`Shift+Tab`	Previous column
`j` / `Down`	Move down within column
`k` / `Up`	Move up within column
`gg`	Jump to top of column
`G`	Jump to bottom of column
`Enter`	Open ticket detail
`b`	Toggle burndown chart
`L`	Manage labels on selected ticket
`t`	Log time against selected ticket
`d`	Delete selected ticket
`D`	Cascade delete (ticket + dependents)
`Esc` / `q`	Return to ticket list

Open a sprint board with the :sprint <sprint-id> command.

Quick Actions

Available from Ticket List, Ticket Detail, and Sprint Board views.

Key	Action	Popup behavior
`s`	Change status	Select from: Backlog, Todo, InProgress, InReview, Done, Cancelled
`a`	Assign ticket	Select from known assignees, or Unassign
`c`	Add comment	Type comment text, Enter to submit
`p`	Change priority	Select from: Urgent, High, Medium, Low, None
`n`	Create ticket	Enter title and priority, Enter to submit
`l`	Manage labels	Toggle labels on/off for a ticket (`L` on sprint board)
`t`	Log time	Enter duration (minutes) and activity type
`d`	Delete ticket	Confirm deletion (Cancel selected by default)
`D`	Cascade delete	Preview dependents, then confirm

Inside a popup:

Key	Action
`j` / `Down`	Move selection down
`k` / `Up`	Move selection up
`Tab`	Switch between fields (multi-field popups)
`Enter`	Confirm selection/submit
`Esc`	Cancel and close popup

The comment popup accepts free-text input. Type your comment and press Enter to submit or Esc to cancel.

Ticket Creation

Press n to open the ticket creation popup. It has two fields:

Field	Input type	Notes
Title	Text	Required — popup will not submit if empty
Priority	Selector	Urgent, High, Medium, Low, None (default)

Use Tab to switch between the Title and Priority fields. In the Priority field, j/k cycle through options. Press Enter to create the ticket or Esc to cancel.

The ticket is created in the currently selected project. The reporter is set to the authenticated user automatically.

Label Management

Press l (or L on the sprint board) to open the label popup for the selected ticket. The popup lists all organization labels with a toggle indicator:

✓ label-name (#COLOR) — label is attached to the ticket
label-name (#COLOR) — label is not attached

Navigate with j/k and press Enter to toggle a label on or off. Press Esc to close the popup.

Time Logging

Press t to open the time logging popup for the selected ticket. It has two fields:

Field	Input type	Notes
Duration	Number	Minutes (1–1440). Only digits accepted
Activity Type	Selector	Coding, Testing, CodeReview, Design, Architecture, PM, Requirements, Training, Maintenance, BugFixing, Documentation, Deployment, Meetings

Use Tab to switch between fields. The default activity type is Coding. Press Enter to submit or Esc to cancel. The time entry is logged for today’s date against the selected ticket.

Delete

Press d to delete the selected ticket. A confirmation popup appears with Cancel selected by default for safety. Select “Yes, delete” and press Enter to confirm.

If the ticket has dependents (comments, etc.), the simple delete returns a 409 Conflict. Use D instead for cascade delete:

A dry-run request previews what will be deleted (e.g., comment count).
A confirmation popup shows “Yes, delete ticket + N comments” and “Cancel”.
On confirmation the ticket and all dependents are removed.

After deletion the ticket is removed from the local list and the cursor adjusts automatically.

Burndown Chart

When viewing a sprint board, a burndown chart is displayed at the bottom showing sprint progress over time. The chart includes:

Sprint date range (start to end)
Total tickets vs completed/remaining count
Completion percentage
Progress sparkline

Press b to toggle the burndown chart on or off. It is shown by default when opening a sprint board.

Sprint Management

Sprint operations are available via command mode (:sprint).

Command	Description
`:sprint <id>`	Open sprint board for the given sprint ID
`:sprint list`	List all sprints in the current project
`:sprint create <name> <start> <end>`	Create a new sprint (dates: YYYY-MM-DD)
`:sprint start <sprint-id>`	Start a planned sprint
`:sprint complete <sprint-id>`	Complete an active sprint

Examples:

:sprint list
:sprint create Sprint-4 2026-04-01 2026-04-14
:sprint start abc123-def456
:sprint complete abc123-def456
:sprint abc123-def456

Command Mode

Press : to enter Command mode. Type a command and press Enter to execute.

Command	Description
`:q` / `:quit`	Exit the application
`:filter status=X`	Filter tickets by status (e.g., `:filter status=Todo`)
`:filter`	Clear status filter
`:sort field:dir`	Sort tickets (e.g., `:sort priority:desc`)
`:sort`	Clear sort, return to default order
`:sprint <id>`	Open sprint board for given sprint ID
`:sprint list`	List sprints in current project
`:sprint create <name> <start> <end>`	Create a new sprint
`:sprint start <id>`	Start a planned sprint
`:sprint complete <id>`	Complete an active sprint
`:project <key>`	Switch to a specific project by key
`:project`	Clear project filter (show all)

Sort fields: priority, status, title, assignee Sort directions: asc (default), desc

Command mode helpers:

Key	Action
`Tab`	Auto-complete command name
`Up`	Previous command from history
`Down`	Next command from history
`Backspace`	Delete character (empty → Normal mode)
`Esc`	Cancel, return to Normal mode

Search

Press / to enter Search mode. Type to filter tickets in real time.

Matches against ticket key, title, and status (case-insensitive)
Press Esc to stop searching (matches remain highlighted)
Press n for next match, N for previous match (in Normal mode)
Filtering respects active project and status filters

Complete Keybinding Reference

Normal Mode — Global

Key	Action
`:`	Enter Command mode
`/`	Enter Search mode
`?`	Show help overlay
`q`	Quit application
`Esc`	Return to Normal mode / close popup

Key	Action
`j` / `Down`	Move down / scroll
`k` / `Up`	Move up / scroll
`gg`	Jump to top
`G`	Jump to bottom
`h` / `Left`	Previous column (sprint board)
`l` / `Right`	Next column (sprint board)
`Tab`	Next column / cycle project filter
`Shift+Tab`	Previous column (sprint board)
`Enter`	Open ticket detail

Normal Mode — Actions

Key	Action	Views
`s`	Change status	List, Detail, Board
`a`	Assign ticket	List, Detail, Board
`c`	Add comment	List, Detail, Board
`p`	Change priority	List, Detail, Board
`n`	Create ticket	List, Detail
`l`	Manage labels	List, Detail
`L`	Manage labels	Sprint Board
`t`	Log time	List, Detail, Board
`d`	Delete ticket	List, Detail, Board
`D`	Cascade delete	List, Detail, Board
`b`	Toggle burndown	Sprint Board

Search Mode

Key	Action
any	Appended to search query
`Esc`	Exit search (matches highlighted)
`n`	Next match (after exiting search)
`N`	Previous match

Key	Action
`j` / `Down`	Move selection down
`k` / `Up`	Move selection up
`Tab`	Switch field (multi-field popups)
`Enter`	Confirm / submit
`Esc`	Cancel / close
`Backspace`	Delete character (text fields)

TUI Layout

┌──────────────────────────────────────────────────────────────────┐
│                                                                  │
│                      Main Content Area                           │
│                                                                  │
│   Ticket List ─────────────────────────────────────────────────  │
│   ┌──────────┬────────────────────┬────────────┬──────────────┐  │
│   │ Key      │ Title              │ Status     │ Priority     │  │
│   ├──────────┼────────────────────┼────────────┼──────────────┤  │
│   │ PROJ-1   │ Fix login bug      │ InProgress │ High         │  │
│   │ PROJ-2   │ Add dark mode      │ Todo       │ Medium       │  │
│   │ PROJ-3   │ Update docs        │ Done       │ Low          │  │
│   └──────────┴────────────────────┴────────────┴──────────────┘  │
│                                                                  │
│   — or —                                                         │
│                                                                  │
│   Ticket Detail ───────────────────────────────────────────────  │
│   ┌────────────────────────────────────────────────────────────┐ │
│   │ Status: InProgress   Priority: High                        │ │
│   │ Assignee: alice      Reporter: bob                         │ │
│   │ Sprint: Sprint 3     Created: 2026-03-01                   │ │
│   │                                                            │ │
│   │ Description                                                │ │
│   │ ────────────────────────────────────                       │ │
│   │ [scrollable content with word wrapping]                    │ │
│   │                                                            │ │
│   │ Comments                                                   │ │
│   │ ────────────────────────────────────                       │ │
│   │ alice (2026-03-02): Looks good to me                       │ │
│   └────────────────────────────────────────────────────────────┘ │
│                                                                  │
│   — or —                                                         │
│                                                                  │
│   Sprint Board (kanban) ───────────────────────────────────────  │
│   ┌───────────────┬───────────────┬───────────────┐              │
│   │ Todo (3)      │ InProgress (2)│ Done (4)      │              │
│   ├───────────────┼───────────────┼───────────────┤              │
│   │ PROJ-1: Fix   │ PROJ-3: API  │ PROJ-2: Docs  │              │
│   │ PROJ-4: Auth  │ PROJ-5: Test │ PROJ-6: Setup │              │
│   │ PROJ-7: UI    │              │ PROJ-8: CI    │              │
│   │               │              │ PROJ-9: Deps  │              │
│   └───────────────┴───────────────┴───────────────┘              │
│   ┌────────────── Burndown ──────────────────────┐               │
│   │ Sprint 3 (2026-03-01 → 2026-03-14)  67%     │               │
│   │ Total: 9  Done: 6  Remaining: 3             │               │
│   │ ▁▂▃▄▅▆▇█ progress sparkline                 │               │
│   └──────────────────────────────────────────────┘               │
│                                                                  │
├──────────────────────────────────────────────────────────────────┤
│ [NORMAL] Connected │ [PROJ] 2/15                    Status Bar   │
└──────────────────────────────────────────────────────────────────┘

The status bar shows:

Mode indicator — current mode with colored background
Connection status — whether the API is reachable
Context info — varies by view:
- Ticket List: project key and cursor position (e.g., [PROJ] 5/23)
- Sprint Board: sprint name, date range, progress, and board position
- Command/Search mode: the command or search buffer being typed

Alloy Documentation