---
title: Agents and scripts
description: 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

```sh
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:

```json
{
  "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`:

```text
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.