hearth/docs/gitea-kanban-cli.md

Gitea Kanban CLI

gitea-kanban is the non-interactive interface for native Gitea Projects. It shares its configuration, API client, models, permissions, and operations with gitea-kanban-tui.

Installation

The Nix package installs both binaries:

nix build .#gitea-kanban-tui
./result/bin/gitea-kanban --help
./result/bin/gitea-kanban-tui --help

For development:

cargo run --manifest-path package/gitea-kanban-tui/Cargo.toml \
  --bin gitea-kanban -- --help

Configuration

Configuration can be supplied with flags or environment variables. A project selector is required, and exactly one selector must be supplied.

Flag	Environment	Description
--url	GITEA_URL	Gitea base URL
--token-file PATH	GITEA_TOKEN_FILE	File containing API token
—	GITEA_TOKEN	Token fallback when no token file is configured
--project NAME	GITEA_PROJECT	Exact, case-sensitive project name
--project-id ID	GITEA_PROJECT_ID	Project ID; useful for duplicate names
OWNER	GITEA_OWNER	Repository owner
REPO	GITEA_REPO	Repository name

Precedence:

1. Command-line flags and positional arguments.
2. Token file from --token-file or GITEA_TOKEN_FILE.
3. GITEA_TOKEN when no token file is configured.

Token files must be regular files and must not be group- or world-readable on Unix. Remote URLs must use HTTPS. Plain HTTP is accepted only for literal loopback IP addresses (127.0.0.1 or ::1) during local development.

Example:

export GITEA_URL=https://gitea.example
export GITEA_TOKEN_FILE="$HOME/.config/gitea/token"
gitea-kanban --project Kanban owner repo board

Commands

board

Print selected project, columns, and issues:

gitea-kanban --project Kanban owner repo board

Output includes issue numbers and titles. Server-provided terminal control characters are removed before output.

create

Create an issue and assign it to selected project. The issue starts in the project's default column.

gitea-kanban --project Kanban owner repo create \
  --title "Fix deployment" \
  --body "Investigate failed rollout"

edit

Replace issue title and body. Issue must be assigned to selected project.

gitea-kanban --project Kanban owner repo edit 42 \
  --title "Updated title" \
  --body "Updated description"

move

Move an issue to a project column. ISSUE_ID is the global Gitea issue ID, not the repository issue number. --sorting is optional.

gitea-kanban --project Kanban owner repo move 123 --column-id 7
gitea-kanban --project Kanban owner repo move 123 --column-id 7 --sorting 2

delete

Delete an issue assigned to selected project. This is irreversible and requires explicit confirmation with --yes:

gitea-kanban --project Kanban owner repo delete 42 --yes

Deletion also requires repository administrator permission in this Gitea fork.

Permissions and server behavior

• The repository Projects unit must be enabled.
• Project operations require repository Projects write permission.
• Issue create/edit follows Gitea issue permissions.
• Delete requires repository administrator permission.
• Closed projects, archived repositories, disabled Projects units, foreign project IDs, and issues outside selected project are rejected.
• API failures return a non-zero exit status. Authentication and HTTP status guidance is shown without printing server response bodies or tokens.

Related interface

Use gitea-kanban-tui for keyboard navigation over the same native Projects API. Both binaries use the same configuration and server-side authorization.