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.

Agent skill

The source-coop skill tells an AI agent when to use the CLI: when you mention Source Cooperative, source.coop or data.source.coop. It sends the agent to --help for the commands, and has it use --json, ask you to sign in, and ask you before it deletes anything.

In Claude Code, install it from this repository's plugin marketplace:

/plugin marketplace add source-cooperative/source-coop-cli
/plugin install source-coop@source-cooperative

The skill is in the open Agent Skills format. For another agent that reads skills, copy the skills/source-coop folder to where that agent looks for them.

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.
All account commands.
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 -

Read data

A product's data is at s3://ACCOUNT/PRODUCT/ on the data proxy (--proxy-url, https://data.source.coop by default). Public data needs no sign-in; Access Data shows each tool's settings. Restricted data and writes need the credentials from creds (see Reading data with AWS tools).

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.