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

comment

Comments are managed on issues assigned to the selected project. Issue values are repository issue numbers. Comment values are global Gitea comment IDs.

gitea-kanban --project Kanban owner repo comment list 42
gitea-kanban --project Kanban owner repo comment add 42 --body "Investigating"
gitea-kanban --project Kanban owner repo comment edit 42 9001 --body "Resolved"
gitea-kanban --project Kanban owner repo comment delete 42 9001 --yes

The CLI verifies that the issue belongs to the selected project and that the comment belongs to that issue before editing or deleting it.

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.