Use src in scripts and agents#

Your script or agent needs a few values from the forge: issue numbers, a pull request title, the status of a run. The tables that src prints are for people. A script that cuts them apart breaks when a table changes.

src prints JSON with only the fields that you ask for. It filters that JSON with jq, or formats it with a Go template. The flags and the field names are the same as in gh.

1. Ask for the fields with --json#

src issue list --json number,title

[
  {
    "number": 12,
    "title": "Login fails on Safari"
  },
  {
    "number": 9,
    "title": "Add dark mode"
  }
]

• To see the fields of a command, give --json with no field names. src lists the fields, and exits with 1.
• A field that the forge has no value for is null.
• In a terminal, the JSON is indented and in color. In a pipe or a file, it is on one line.
• Most list and view commands have --json. src <command> --help shows it.

2. Filter with --jq#

--jq runs a jq filter on the JSON. jq is built into src, so you install nothing.

src issue list --json number,title --jq '.[] | "#\(.number) \(.title)"'

#12 Login fails on Safari
#9 Add dark mode

• A string result prints as plain text, with no quotes.
• An array or an object prints as JSON.

A CI script can find the failed runs, then read their logs:

src run list --status failure --json databaseId --jq '.[].databaseId'
src run view <run> --log-failed

3. Format text with --template#

--template formats the JSON with a Go template, with gh's functions.

src pr list --json number,title,author --template '{{range .}}{{tablerow .number .title .author.login}}{{end}}'

7  Count down to zero  alem
5  Add dark mode       sam

The functions of gh:

• tablerow and tablerender put the fields in aligned columns.
• timeago gives the age of a time: {{timeago .createdAt}} prints 2 days ago.
• truncate cuts a text: {{truncate 40 .title}}.
• color and autocolor color a text in a terminal: {{color "green" .title}}.
• join, pluck, timefmt and hyperlink, and Go's printf, len, eq and more.

This prints the age of each open issue:

src issue list --json number,title,createdAt --template '{{range .}}#{{.number}} {{.title}} ({{timeago .createdAt}}){{"\n"}}{{end}}'

4. Read any REST route with src api#

src api sends a request to the REST API with your login. --paginate reads every page of a list:

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

• {owner} and {repo} come from the repository of your clone.
• A list gives 100 items and a next cursor on each page. --paginate asks for the next page until there is none.
• --jq and --template run on each page.
• --paginate works with GET only.

To keep all the pages in one JSON array, add --slurp:

src api 'repos/{owner}/{repo}/issues' --paginate --slurp > issues.json

Each item of the array is one page, with its items. --slurp does not work with --jq or --template.

Done#

src issue list --json number --jq '.[].number'

Your script gets the issue numbers, one on each line, and nothing else to cut apart. An agent runs the same commands. To give a script or an agent a login, see scripts and CI.