Agents and scripts

Drive rolle from a script or a coding agent without handling credentials.

rolle works from a script or an agent as it works from a terminal. The rule: ask rolle for a profile name, never for keys. The AWS SDK in your tool fetches credentials through credential_process. No credential passes through the agent’s context or transcript.

Loop

rolle session list --json                 # what exists, and what is active
rolle start "Acme/Admin" --json           # start it; the reply names the profile
AWS_PROFILE=default terraform plan        # every AWS tool works from here
rolle stop "Acme/Admin"

Azure and Google Cloud sessions have no profile. Use eval "$(rolle env <name>)" in the shell that runs the tool.

Shapes

--json prints an object for start and an array for session list, status, and integration list. A session:

{
  "id": "6f1c…",
  "name": "Acme/Admin",
  "kind": "aws-sso-role",
  "cloud": "aws",
  "status": "active",
  "region": "us-east-1",
  "profile": "default",
  "accountId": "111111111111",
  "roleName": "Admin",
  "integration": "acme",
  "expires": "2026-09-12T20:14:03Z"
}

Integrations report signedIn, and for AWS the token expires. No shape carries a secret.

Exit codes

Code	Meaning	Action
`0`	Done
`1`	Error. The message is on stderr	Show it to a person
`3`	Sign-in needed	Stop. Ask a person to run `rolle integration login <alias>`. Sign-in opens a browser and needs a person to approve
`4`	The session or integration does not exist	Run `rolle session list --json` and pick from it

Agent instructions

Add this to the instructions file your agent reads, for example AGENTS.md or CLAUDE.md:

Cloud credentials come from rolle. Run `rolle session list --json` to see the
sessions, `rolle start <name> --json` to start one, and use the `profile` it
returns as AWS_PROFILE. Never run `rolle env` or `rolle creds`. If a command
exits with code 3, stop and ask me to sign in.

Notes

rolle session list omits hidden sessions. --all includes them.
--debug prints the host of every network request.
A session an agent starts shows in the desktop app and the tray with its countdown. It stops when it expires.