Scripts and AI agents

source-coop --help ends with a summary of this section. The --help of each command shows its flags and examples. Thus an AI agent can learn the CLI from the CLI.

Output

Data goes to stdout. Messages go to stderr. Thus url=$(source-coop product create ...) works.
On a terminal, output is for people. It has color, unless NO_COLOR is set or CLICOLOR=0. Lists show in your pager: $SOURCE_PAGER, $PAGER, then less -FRX. --no-pager or SOURCE_PAGER=cat prints directly.
When piped, output is plain, with no pager.
-v (--verbose) prints the HTTP requests and responses on stderr.

JSON

These commands accept --json:

auth status and auth logout.
product list, view, create, edit and delete.
All member and invitation commands.
service-account list, view, create, edit and delete, and sign-in add, edit and remove.

Commands that change data print the record after the change. service-account edit --json prints the account as view --json does.

With --json:

stdout contains one JSON document and nothing else. Notes and progress go to stderr.
Field names are the API's. Times are RFC 3339.
New fields can be added. Fields are not renamed or removed.

These commands do not accept --json, because their output is already for machines: creds (--format), auth token (a token), api (the API's response), completions (a shell script) and service-account usage (a workflow or shell exports). auth login does not accept it either, because it uses the browser. Use auth status --json after it.

With --json, an error is also JSON, on stderr. If the error came from the API, it contains the data of the API's RFC 9457 problem:

code and status.
type: a URL to a page that explains the error and what to do.
request_id: give it if you report the error.
field_errors: if the API refused the input, the fields to correct, by path (metadata.title).

{"error": {"code": "invalid", "message": "…", "status": 400, "field_errors": {"title": ["…"]}, "type": "https://source.coop/api/problems/invalid", "request_id": "…"}}

Exit codes

All commands use the same exit codes:

Code	Meaning
0	Success
1	Other failure, including a cancelled prompt
2	Incorrect command-line usage
3	The API refused the input (HTTP 400, 409, 422). Correct the named fields and try again.
4	Not signed in, or not allowed (HTTP 401, 403)
5	Not found (HTTP 404)
130	Interrupted (`Ctrl`+`C`)

Without a terminal: errors, --json, exit codes and -F -

Use the API without signing in

If SOURCE_TOKEN is set, the CLI sends it to the API instead of the session's access token. Thus a script or CI job can use the API without auth login.

Use your session with other tools

auth token prints the session's access token for the source.coop API. If the token has expired, it renews it first.

curl -H "Authorization: Bearer $(source-coop auth token)" https://source.coop/api/v1/...

auth token: the session's access token, for curl

To send a request through the CLI, see Any API request.