Add a command that prints a Connect access token for other tools #21

Summary

Add a command that prints a valid Connect access token for a saved server, refreshing it first if needed. Other tools could then use the credentials from posit connect login without reading posit-cli's credential store themselves.

posit connect token [-s URL | -n NAME] [--format json]

Motivation

posit connect login makes OAuth the recommended way to sign in to Connect, so users don't have to create and manage API keys. The Connect SDKs (posit-sdk-py and connectapi) still require an API key, so a user who signed in with posit connect login has to create one separately to use them.

The SDKs could read the stored credentials directly, but that would be fragile:

• The storage format is internal. Tokens live in the system keyring (service rsconnect-python, username {url}:access_token / {url}:refresh_token), with oauth_* fields in servers.json as a fallback. Neither is a public contract, and both would change if the CLI is rewritten (see Build a standalone binary CLI to replace the Python and R publishing clients #19).
• Refresh tokens rotate. After a refresh, the CLI writes back the new refresh token. If another tool refreshed on its own without writing back with the same keyring and file behavior, the CLI's stored token would stop working, or the other way round. Two writers would also race.
• R can't easily read a keyring entry written by Python. connectapi would need its own copy of the lookup logic.

A command avoids all three. The CLI stays the only thing that reads, refreshes, and writes stored credentials, and any language can call it. This is the same pattern as gh auth token, gcloud auth print-access-token, git credential helpers, and kubectl exec plugins.

Proposed behavior

• Server selection works like other commands: -s/--server URL or -n/--name NAME, falling back to CONNECT_SERVER.

• If the stored access token is expired or close to expiring, refresh it and persist the new tokens before printing.

• Default output is the bare access token on stdout, so $(posit connect token) works in shell scripts.

• --format json prints machine-readable output, for example:

  {"access_token": "...", "token_type": "Bearer", "expires_at": 1793000000, "server": "https://connect.example.com"}

  expires_at lets callers call the command again before the token expires instead of waiting for a 401.

• Print nothing on stdout and exit non-zero when there are no stored OAuth credentials for the server, or when the refresh fails (for example, the grant was revoked). The error message on stderr should say to run posit connect login. Distinct exit codes for "not logged in" and "refresh failed" would let callers give better messages.

• Never prompt or start an interactive login. Callers are often non-interactive (scripts, notebooks, SDKs).

• Servers registered with an API key: either print nothing and exit non-zero, or provide a separate opt-in. Printing API keys by default seems riskier than printing short-lived access tokens.

How the SDKs would use it

When the user doesn't pass an API key and CONNECT_API_KEY isn't set, the SDK runs posit connect token -s $CONNECT_SERVER --format json and sends Authorization: Bearer <access_token>. It runs the command again shortly before expires_at, and once more after a 401. An API key always takes precedence, which matches how posit-cli itself handles precedence. This keeps CI and content running on Connect working unchanged.

Open questions

• Command name: token, auth token, or print-token?
• Should the JSON output schema and exit codes be documented as a stable interface, so the SDKs can rely on them across posit-cli versions (including a possible rewrite)?
• Concurrency: if several processes call the command at the same time while a refresh is due, should the CLI lock the store so only one refresh happens?