tp issue

Issues on the repo's own forge, from the command line. Issues live on the release remote's forge — Forgejo (or Gitea) or GitLab; GitHub is a mirror by convention and never holds them.

Commands

Command Does Prints
list open issues #N LABELS title per line, ascending; nothing if none
list closed / list all issues in that state #N [state] LABELS title per line
show N one issue with its comments title, state, url, body, comments
create TITLE [-body FILE|-] opens an issue #N url
edit N [-title T] [-body FILE|-] changes title and/or body #N url
comment N BODY... adds a comment the comment's url
close N / reopen N changes state #N -> closed|open

-json on any subcommand prints the result as JSON instead — an issue (number, title, state, body, url), a list of them, a comment, or for show the issue with a comments list. -body - reads the body from stdin. Flags may come before or after the arguments.

Listing prints fixed-width columns: the number, the state when the list is not of open issues only, then LABELS, a 20-character prefix of the first labels in forge order, present only when some listed issue has a label. The slots depend on the most labels any listed issue has:

Labels Slots Label fits Else cut to
1 one of 20 19 17 + ..
2 two of 10 9 7 + ..
3 or more 8, 7, 5 7, 6, 4 5, 4, 2 + ..
#46  roadmap story  fix  Custom step ordering
#48  roadmap             tp adr: number, scaffold, supersede

Listing reads every page of results and excludes pull requests. Any API failure prints the HTTP status and the forge's message and exits 1; a token the forge quotes back is redacted.

Which forge and token

The same resolution as tp release, with no configuration of its own:

  • Remote — release_remote in task-plus.yml, default origin.
  • Forge — the remote's forge: override (or the legacy top-level forge:), else detected from the host name. Hosts without "forgejo", "gitea" or "codeberg" in the name need forge: forgejo.
  • API — Forgejo's https://<host>/api/v1/repos/<owner>/<repo> or GitLab's https://<host>/api/v4/projects/<path>, from an https, git@host: or ssh:// remote. An ssh alias remote (alias:owner/repo) is refused: its web host is unknown.
  • Token — the remote's token_env variable; if unset in the environment, fetched through secrets_provider: bitwarden (needs tp unlock). With no token_env the forge's default variable is read (GITLAB_TOKEN; CODEBERG_APIKEY, FORGEJO_TOKEN or GITEA_TOKEN), else requests go unauthenticated, which works for reading a public repo; writes refuse to run without a token.

On GitLab a comment is a note, show leaves out the system notes GitLab adds for its own events, and a label is put on by name rather than id.

remotes:
  - name: origin
    forge: forgejo
    token_env: BYTESTONE_FORGEJO_TOKEN