src api

Makes an authenticated HTTP request to the SourceCraft REST API and prints the response.

The path argument should be a path of a SourceCraft REST API endpoint.

Placeholder values {org} (or {owner}) and {repo} in the path get
replaced with values from the repository of the current directory or the
repository selected with the global -R/--repo flag.

The default HTTP request method is GET, and POST if any parameters were added or
a request body is supplied via --input. Override the method with -X/--method.

Pass one or more -f/--raw-field values in key=value format to add static string
parameters to the request payload. To add non-string or placeholder-determined
values, use -F/--field. Adding request parameters automatically switches the
request method to POST; to send them as a GET query string instead, use
--method GET.

The -F/--field flag has magic type conversion based on the format of the value:

• literal values true, false, null, and integer numbers get converted to
  appropriate JSON types;
• placeholder values {org} (or {owner}) and {repo} get populated with
  values from the current repository;
• if the value starts with @, the rest is interpreted as a filename to read the
  value from. Pass @- to read from standard input.

To pass nested parameters, use key[subkey]=value syntax. To pass arrays, declare
multiple fields with key[]=value1, key[]=value2. To pass an empty array, use
key[] without a value.

To pass a pre-constructed request body, read it from a file with --input (use -
to read from standard input). When passing the body this way, any parameters
specified via field flags are added to the query string of the endpoint URL.

Pass -q/--jq to filter the JSON response through a jq expression. The results are
printed one per line; a successful but empty response and a non-2xx error body
are passed through untouched.

Pass -t/--template to format the JSON response with a Go template. A successful
but empty response and a non-2xx error body are passed through untouched.

Pass --paginate to fetch all pages of a list endpoint by following the
next_page_token of each response (page_size defaults to 100 when not set). The
pages are merged by concatenating their single top-level array field into one
flat JSON array — so --jq and --template see an array, not the per-page
envelope. Pass --slurp to instead collect the raw page objects into an outer
JSON array.

Pass --silent to discard the response body; the exit code still reflects the
HTTP status.

Pass the global -V/--verbose flag to dump the full HTTP request and response
(method, URL, headers, and body) to standard error for debugging.

Usage

src api <path> [flags]

Examples

Get the authenticated user

src api user

List issues in the current repository

src api repos/{owner}/{repo}/issues

Post an issue comment

src api repos/{owner}/{repo}/issues/123/comments -f body='Hi from the CLI'

Add parameters to a GET request

src api -X GET repos/{owner}/{repo}/issues -f filter='status = open'

Use a JSON file as the request body

src api repos/{owner}/{repo}/pulls --input body.json

Set a custom HTTP header

src api -H 'Accept: application/json' user

Include response status line and headers

src api -i user

Filter the response with jq (list responses are envelopes, e.g. {"issues": [...]})

src api repos/{owner}/{repo}/issues -q '.issues[].title'

Format the response with a Go template

src api repos/{owner}/{repo}/issues --template '{{range .issues}}{{.title}}not_var{{"\n"}}{{end}}'

Fetch all pages, merged into one flat array

src api repos/{owner}/{repo}/issues --paginate -q '.[].title'

Flags

Flag	Description
-F, --field key=value	Add a typed parameter in key=value format (use "@" or "@-" to read from a file or stdin)
-H, --header key:value	Add an HTTP request header in key:value format
-i, --include	Include HTTP response status line and headers in the output
--input file	The file to use as the request body (use "-" to read from standard input)
-q, --jq string	Query to select values from the response using jq syntax
-X, --method string	The HTTP method for the request (default "GET")
--paginate	Make additional HTTP requests to fetch all pages of results
-f, --raw-field key=value	Add a string parameter in key=value format
--silent	Do not print the response body
--slurp	Use with "--paginate" to return an array of all pages of results
-t, --template string	Format JSON output using a Go template

Inherited flags

Flag	Description
--env string	Override Sourcecraft environment (use 'src envs' to list available)
--json string	Output JSON, optionally filtered (--json or --json=field1,field2)
--json-compact string	Output compact JSON, optionally filtered
-R, --repo string	Select another repository using OWNER/REPO format
-V, --verbose	Enable debug logging output

Learn more

Use src api <subcommand> --help for more information about a command.