nprasad2077/docs

1 Fork 0

mirror of https://gitea.com/gitea/docs.git synced 2026-11-05 17:45:46 +00:00

Files

T

bircni 55c3a392a1 feat: generate the gt command reference from gitea/cli

update_cli_docs.sh runs gt's own generator and lays the pages out for the
site: one directory per command group, front matter, titles, sidebar
order, fenced help text and rewritten links. --released succeeds while no
series is documented. A weekly workflow proposes updates like the runner's.

Signed-off-by: bircni <[email protected]>

2026-10-22 11:28:15 +02:00

3.6 KiB

Raw Blame History

sidebar_position, description

sidebar_position	description
3	Make an authenticated Gitea API request

gt api

Make an authenticated Gitea API request

Synopsis

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.

gt api <endpoint> [flags]

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'

Options

  -F, --field key=value       Add a typed parameter in key=value format; @FILE or @- reads a file or stdin
  -H, --header name:value     Add an HTTP request header in name:value format
  -h, --help                  help for api
  -i, --include               Print the response status and headers to stderr
      --input file            Read the request body from a file, or stdin with -
      --max-pages int         Stop --paginate after this many pages; reaching the default fails (default 1000)
  -X, --method method         HTTP method (default "GET")
      --output-file file      Write the complete response to a new file
      --paginate              Follow next-page links and print every page
  -f, --raw-field key=value   Add a string parameter in key=value format
      --silent                Do not print the response body
      --verbose               Print the request and the response status and headers to stderr

Options inherited from parent commands

      --cwd directory       Working directory for repository discovery
      --debug               Log the method, URL, status, and duration of each HTTP request to stderr
      --host URL            Gitea instance URL, including any base path
      --interactive         Allow prompts with machine output
  -q, --jq expression       Filter JSON output using a jq expression; implies --json
      --json fields[="*"]   Output JSON with the specified comma-separated fields, or all fields
      --no-input            Disable prompts and implicit editor/browser interactions
      --remote remote       Git remote used for repository discovery
  -R, --repo OWNER/REPO     Select a repository as OWNER/REPO or URL
      --sudo user           Perform API requests as this user (requires an administrator account)
      --user name           Account name on the selected instance
  -y, --yes                 Accept confirmations without prompting

3.6 KiB Raw Blame History