# 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:

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

For development:

```sh
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:

```sh
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:

```sh
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.

```sh
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.

```sh
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.

```sh
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.

```sh
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`:

```sh
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.