gt-api1

Usage

Overview

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.

Options

-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

Options inherited from parent commands

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

Examples

$ 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'