GT-API(1) gitea-cli Manual GT-API(1)

gt-api - Make an authenticated Gitea API request

gt api <endpoint> [flags]

Make an authenticated request to the Gitea API of the selected instance and print the response.

The endpoint is a path under /api/v1, such as repos/{owner}/{repo}/issues, or a URL of the instance's API. The placeholders {owner} and {repo} take the repository of the current directory or --repo, and {branch} the checked-out Git branch.

The method is GET, or POST when fields or --input supply a request body; -X selects another. Fields become query parameters of GET and HEAD requests and a JSON body otherwise:

-f, --raw-field name=value a string value
-F, --field name=value a typed value: true, false, null, numbers, arrays and
objects are JSON, @FILE reads a file and @- stdin

--paginate follows the next-page links of a GET request, or asks for the next page of a list that Gitea counts in X-Total-Count without links, and prints every page on its own line. --jq filters each JSON response with a jq expression and prints strings without quotes; jq does not need to be installed.

On a terminal, JSON responses are indented and colored. A response outside 2xx prints its body, then fails with the HTTP status.

-F, --field=[] Add a typed parameter in key=value format; @FILE or @- reads a file or stdin

-H, --header=[] Add an HTTP request header in name:value format

-h, --help[=false] help for api

-i, --include[=false] Print the response status and headers to stderr

--input="" Read the request body from a file, or stdin with -

--max-pages=1000 Stop --paginate after this many pages; reaching the default fails

-X, --method="GET" HTTP method

--output-file="" Write the complete response to a new file

--paginate[=false] Follow next-page links and print every page

-f, --raw-field=[] Add a string parameter in key=value format

--silent[=false] Do not print the response body

--verbose[=false] Print the request and the response status and headers to stderr

--cwd="" Working directory for repository discovery

--debug[=false] Log the method, URL, status, and duration of each HTTP request to stderr

--host="" Gitea instance URL, including any base path

--interactive[=false] Allow prompts with machine output

-q, --jq="" Filter JSON output using a jq expression; implies --json

--no-input[=false] Disable prompts and implicit editor/browser interactions

--remote="" Git remote used for repository discovery

-R, --repo="" Select a repository as OWNER/REPO or URL

--sudo="" Perform API requests as this user (requires an administrator account)

--user="" Account name on the selected instance

$ gt api user --jq .login
# Create an issue: -f sends strings, -F typed values
$ gt api repos/{owner}/{repo}/issues -f title="Crash on start" -F labels='[3]'
$ gt api user/repos --paginate --jq '.[].full_name'

gt(1)

Nov 2026 gitea-cli