---
title: Agents and scripts
description: Drive rolle from a script or a coding agent without handling credentials.
sidebar:
  order: 9
---

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

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

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

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