GitHub Projects V2 terminal board viewer. Fetches project data via the GitHub GraphQL API and renders it as a Kanban-style board in your terminal.
- Python 3.10+
- gh CLI authenticated with the
read:projectscope.- First time:
gh auth loginthengh auth refresh -s read:project - Already authenticated: Ensure
gh auth refresh -s read:projectis added
- First time:
Run once without installing anything permanently:
uvx --from git+https://github.com/rudolfjs/cliject cliject board 4Install persistently so cliject is on your PATH:
uv tool install git+https://github.com/rudolfjs/cliject
cliject board 4Pin to a specific tag or commit:
uvx --from git+https://github.com/rudolfjs/cliject@v0.1.0 cliject board 4Install uv globally with pixi to get uvx on your PATH, then use it as above:
pixi global install uv
uvx --from git+https://github.com/rudolfjs/cliject cliject board 4pip install -e ".[dev]"# Personal projects
cliject list
# Organization projects
cliject list --org <orgname>
# Include closed projects
cliject list --closed# By project number
cliject board 4
# Use the configured default board (no number needed)
cliject board
# Org project
cliject board 4 --org <orgname>
# Use the configured default board for an org
cliject board --org <orgname>
# Group by a different single-select field
cliject board 4 --group-by "Priority"
# Only show items assigned to you
cliject board 4 --me
# Show empty columns
cliject board 4 --show-empty
# List view (items as bullet list under status headings)
cliject board 4 --view list
# Kanban view (default)
cliject board 4 --view kanban| Command | Flag | Description |
|---|---|---|
list |
--org, -o |
GitHub organization login |
list |
--closed |
Include closed projects |
board |
(number) | Project number — optional if a default is configured |
board |
--org, -o |
GitHub organization login |
board |
--group-by, -g |
Field name to group columns by (default: Status) |
board |
--me |
Only show items assigned to you |
board |
--show-empty |
Show columns that have no items |
board |
--view, -v |
Display style: kanban (default) or list |
Create ~/.config/cliject/config.json to set default board numbers:
{
"default_board": 4,
"default_view": "list",
"orgs": {
"my-org": {
"default_board": 7
},
"another-org": {
"default_board": 2
}
}
}default_board— used bycliject boardwith no number and no--orgdefault_view— preferred display style:"kanban"(default) or"list"; overridden by--vieworgs.<name>.default_board— used bycliject board --org <name>with no number
cliject/
├── auth.py # gh CLI token retrieval
├── api.py # GraphQL client and paginator
├── config.py # Config file loader (~/.config/cliject/config.json)
├── queries.py # GraphQL query strings
├── models.py # Dataclasses (Project, Board, BoardItem, …)
├── board.py # Business logic: fetch_projects, fetch_board
├── render.py # Rich terminal rendering
└── main.py # Typer CLI entry point
To run ruff linting along with pytest you can do it the following way:
# install dev packages
pip install -e ".[dev]"
# run linting
ruff check cliject
ruff format --check cliject
# run tests
pytest