📋 termboard

A local Kanban board that lives entirely in your terminal. No cloud, no accounts, no app to open — just a JSON file and a command.

╭──────────────────────────────────────────────────────────────╮
│ 📋  Termboard  my-project                          14:32:01  │
│                                                              │
│ ○ TODO (3)            ◐ IN PROGRESS (2)    ● DONE (4)        │
│ ─────────────────     ─────────────────    ─────────────── │
│ 🟡 Fix login bug       🔵 Write tests       ✓ Deploy v1.1    │
│    📅 2026-03-17 (3d)     🔴 Code review    ✓ Fix navbar     │
│    Update README                            ✓ Dark mode      │
│    Write docs                               ✓ Add CI         │
│                                                              │
│ 9 cards · 4 done  ·  /home/user/project/.termboard.json      │
╰──────────────────────────────────────────────────────────────╯

Install

# Download
curl -o ~/.local/bin/termboard https://raw.githubusercontent.com/you/termboard/main/termboard.py

# Make executable
chmod +x ~/.local/bin/termboard

Requirements: Python 3.10+, no dependencies beyond stdlib.

Or just copy termboard.py anywhere on your $PATH.

---

Quick start

termboard add "Fix login bug !2 #backend" --due 3d
termboard add "Write docs #docs"
termboard doing #1
termboard done #1
termboard

---

Commands

add — create a card

termboard add "Title"
termboard add "Title !2 #tag" --due 3d --col doing

Flag	Short	Description
--col	-c	Starting column: todo (default), doing, done
--priority	-p	1 critical · 2 high · 3 normal
--tag	-t	One or more tags: --tag backend auth
--due	-d	Due date: YYYY-MM-DD, 3d, 2w

Inline syntax — embed priority and tags directly in the title:

termboard add "Fix login bug !2 #backend #auth" --due 3d
#                             ↑ prio    ↑ tags

move / column shortcuts — move a card

termboard move #1 doing       # explicit
termboard doing #1            # shortcut
termboard todo #1             # back to todo
termboard wip #1              # alias for doing
termboard in-progress #1      # alias for doing
termboard backlog #1          # alias for todo

Column aliases:

Shortcut	Resolves to
todo, backlog, t	TODO
doing, wip, in-progress, d	IN PROGRESS
done, finished, complete, x	DONE

done — mark as done

termboard done #1
termboard done "login bug"    # partial title match also works

edit — update a card

termboard edit #1 --title "New title"
termboard edit #1 --priority 1
termboard edit #1 --due 7d
termboard edit #1 --due none          # clear due date
termboard edit #1 --tag backend auth  # replace all tags
termboard edit #1 --notes "blocked by PR #42"

Flags can be combined:

termboard edit #1 --title "Fix login !1 #backend" --due 2026-03-20

remove — delete a card

termboard remove #1
termboard rm #3
termboard del #5

list — show the board

termboard           # bare invocation works too
termboard list
termboard list --tag backend    # filter by tag
termboard ls --tag auth

watch — live view

Refreshes automatically, like htop. Press Ctrl+C to quit.

termboard watch
termboard watch --tag backend       # filtered live view
termboard watch --interval 5        # refresh every 5s (default: 2s)

stats — weekly productivity

termboard stats

  📊  Termboard Stats  my-project

  Progress
  ████████████░░░░░░░░░░░░░░░░░░  40% complete

  ○  Todo          3
  ◐  In Progress   2
  ●  Done          4
  ────────────────────────
     Total         9

  This week
  ✓  Completed      4
  +  Added          6
  ↓  Balance       -2

  Top Tags
  #backend          ▪▪▪▪  4
  #docs             ▪▪    2
  #frontend         ▪     1

  Recently completed
  ✓  Deploy v1.1   2026-03-14
  ✓  Fix navbar    2026-03-13

boards — list all boards

termboard boards

---

Card references

Every card gets an ID when created, shown as #1, #2, etc. in the board view. You can reference cards by:

• ID: #1 or just 1
• Partial title: "login" matches "Fix login bug" if unambiguous

termboard done #3
termboard done 3          # same
termboard done "login"    # matches by title

---

Priority levels

Set inline (!1) or via --priority:

Level	Label	Color	Meaning
!1	🔴	Red	Critical
!2	🟡	Yellow	High
!3	🔵	Blue	Normal
(none)	·	Gray	No priority

---

Due dates

Format	Meaning
2026-03-20	Specific date
3d	3 days from today
2w	2 weeks from today
none / clear / -	Remove due date

Due dates are color-coded in the board view:

• 🚨 Red+bold — overdue
• ⏰ Red — due today or tomorrow
• 📅 Yellow — due within 3 days
• 📅 Gray — due later

---

Data storage

Termboard automatically picks the right location:

Context	File
Inside a git repo	<repo-root>/.termboard.json
Anywhere else	~/.termboard/<folder-name>.json

This means each git project gets its own board automatically, with zero configuration. The JSON file is human-readable and can be committed to the repo if you want to share it with your team.

{
  "cards": [
    {
      "id": 1,
      "title": "Fix login bug",
      "col": "doing",
      "priority": 2,
      "tags": ["backend", "auth"],
      "due": "2026-03-17",
      "created": "2026-03-14",
      "done_at": null,
      "notes": ""
    }
  ],
  "next_id": 2
}

---

Tips

Shell alias for speed:

alias tb="termboard"

tb add "Quick fix !1"
tb doing #1
tb done #1

Add to .gitignore if you don't want to share it:

.termboard.json

Or commit it to share with your team:

git add .termboard.json
git commit -m "chore: add project board"

Watch a filtered view while working on a feature:

termboard watch --tag auth