hearth/package/gitea-kanban-tui/README.md

gitea-kanban

Native Projects Kanban tools for custom Gitea fork. gitea-kanban-tui provides the keyboard interface; gitea-kanban provides the command-line interface.

Configuration

Required configuration can come from flags or environment variables:

Flag	Environment	Meaning
--url	GITEA_URL	Gitea base URL
--token-file	GITEA_TOKEN_FILE	File containing API token
—	GITEA_TOKEN	API token fallback when no token file is configured
--project	GITEA_PROJECT	Exact native project name
--project-id	GITEA_PROJECT_ID	Native project ID instead of name
positional OWNER	GITEA_OWNER	Repository owner
positional REPO	GITEA_REPO	Repository name

Native mode requires an enabled repository Projects unit, project read/write repository permission, and a token with read:issue/write:issue scope. Issue creation/editing follows Gitea issue permissions; deletion requires repository admin permission in this fork. Token values are sent only through Gitea's Authorization header and are never printed. Token-file input takes precedence over environment variables. Remote URLs must use HTTPS; plain HTTP is accepted only for loopback development.

export GITEA_URL=https://gitea.hectic-lab.com
export GITEA_TOKEN_FILE="$HOME/.config/gitea/token"
cargo run --manifest-path package/gitea-kanban-tui/Cargo.toml --bin gitea-kanban-tui -- \
  --project Kanban yukkop util.nix

Alternatively:

nix develop .#ratatui
cargo run --manifest-path package/gitea-kanban-tui/Cargo.toml --bin gitea-kanban-tui -- \
  --project-id 1 owner repo

Keys

• Arrow keys or h/j/k/l: focus column/card
• H/L: move focused card left/right
• r: refresh project columns and issues
• ?: toggle help
• q: quit

CLI

Both binaries use same configuration and API client. CLI commands:

gitea-kanban --project Kanban owner repo board
gitea-kanban --project Kanban owner repo create --title "Fix issue" --body "Details"
gitea-kanban --project Kanban owner repo edit 42 --title "Updated" --body "Changed"
gitea-kanban --project Kanban owner repo move 123 --column-id 7
gitea-kanban --project Kanban owner repo delete 42 --yes

delete requires repository admin permission. move takes global issue and project-column IDs.

Native mode reads /projects, project columns, and each column's issues. Moves use the issue's global API id and destination column id; optional sorting is supported by the server API. Project names are exact, case-sensitive matches; use --project-id when duplicate names exist. Empty native boards render normally. n creates an issue assigned to the selected project, e edits the focused issue title/body, and d deletes it after confirmation. In the editor, Enter switches from title to body, Tab switches fields, Ctrl-S saves, and Esc cancels. Closed projects, archived repositories, disabled Projects units, unassigned issues, and cross-repository IDs are rejected by the server.

Development

nix develop .#ratatui
cargo fmt --manifest-path package/gitea-kanban-tui/Cargo.toml -- --check
cargo clippy --manifest-path package/gitea-kanban-tui/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path package/gitea-kanban-tui/Cargo.toml
nix build .#gitea-kanban-tui