142 lines
4.2 KiB
Markdown
142 lines
4.2 KiB
Markdown
# 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.
|