Agents and scripts

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

rolle works from a script or an agent the same way it works from a terminal. The rule that keeps this safe: ask rolle for a profile name, never for keys. The AWS SDK inside your tool fetches credentials through credential_process when it needs them, so they never pass through the agent’s context or its transcript.

The 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 looks like this:

{
  "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	What to do
`0`	Done
`1`	Something else failed; the message is on stderr	Show it to a person
`3`	A sign-in is needed	Stop and ask a person to run `rolle integration login <alias>`; a browser step is involved
`4`	The session or integration does not exist	Run `rolle session list --json` and pick from it

Sign-in is the one step an agent must hand back. It opens a browser and needs a person to approve.

Give an agent the recipe

Put this in 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 hides sessions the user hid in the app. Pass --all to include them.
--debug prints the host of every network request, if you want to watch what a script does.
Every session an agent starts shows in the desktop app and the tray with its countdown, and it stops when it expires.