> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aient.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and project profiles

> Use browser OAuth, named profiles, folder configuration, and short-lived access-only exports.

# Authentication and project profiles

Aient CLI uses customer OAuth for ordinary development work. Refresh credentials stay in the operating-system credential store; local profile and project files contain non-secret selectors only.

## `aient auth login`

Open the browser consent flow and save a refresh-backed customer session:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient auth login
aient auth login --profile client-a
```

| Flag                          | Meaning                                                        |
| ----------------------------- | -------------------------------------------------------------- |
| `--profile NAME`              | Save or replace the selected named customer profile.           |
| `--issuer URL`                | OAuth issuer. The default is `https://aient.ai`.               |
| `--callback-timeout DURATION` | Maximum time to wait for browser consent. The default is `5m`. |

Use a distinct profile for each organisation context you work in. Existing OAuth sessions may need a new login when Aient introduces additional consented capabilities.

## `aient auth status`

Verify the selected login and display its issuer, organisation, and granted scopes:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient auth status
aient auth status --profile client-a
aient auth status --all
```

`auth status --all` displays local metadata for every profile without refreshing credentials. A status check for a selected refresh-backed profile verifies the live session. For an access-only token, status validates the envelope shape, issuer and audience claims, metadata consistency, and expiry locally; the server verifies its signature and current authority on the first API operation.

## `aient auth logout`

Revoke and remove only the selected login:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient auth logout --profile client-a
```

Logging out one profile does not remove another organisation's profile.

## `aient auth profiles`

List locally known named profiles:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient auth profiles
```

The output includes the current fallback marker and non-secret organisation and issuer metadata. It never prints access or refresh tokens.

## `aient auth profiles default`

Choose the non-secret fallback profile:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient auth profiles default client-a
```

The default is used only when no explicit access token, explicit profile, environment profile, or project profile selects another context.

## Bind a checkout with `.aient/config.yaml`

Create a project file in the checkout or linked worktree:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
profile: client-a
organisation: Example Engineering
repository: example/widget
```

The CLI searches from the selected workspace or current directory upward and uses the nearest `.aient/config.yaml`. Supported keys are:

| Key            | Purpose                                                                              |
| -------------- | ------------------------------------------------------------------------------------ |
| `profile`      | Select a locally logged-in named profile.                                            |
| `organisation` | Assert the expected organisation name during preflight.                              |
| `repository`   | Supply an `owner/name` repository selector when Git remotes are absent or ambiguous. |

The file is intentionally strict: it accepts only these scalar keys and must not contain credentials. The organisation and repository values are selectors and mismatch checks, never authority.

### Profile resolution order

For each invocation, Aient resolves authentication in this order:

1. An explicit access-only source: `--access-token-file`, `AIENT_ACCESS_TOKEN_FILE`, or `AIENT_ACCESS_TOKEN`.
2. `--profile NAME` or `AIENT_PROFILE`.
3. The nearest `.aient/config.yaml`.
4. The user default selected by `auth profiles default`.
5. Compatibility profile `customer`.

Conflicting explicit sources fail locally. For example, different values in `--profile` and `AIENT_PROFILE` are rejected instead of silently choosing one. A portable access token and refresh-profile selection are also mutually exclusive for the same invocation.

## `aient auth export`

Export a shorter-lived access-only credential for a child process, CI job, or another machine. Prefer a uniquely named, mode-`0600` file outside every uploaded workspace:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
TOKEN_DIR="$(mktemp -d)"
cleanup_aient_access() {
  rm -f "${TOKEN_DIR}/access.json"
  rmdir "${TOKEN_DIR}" 2>/dev/null || true
}
trap cleanup_aient_access EXIT
aient auth export --profile client-a --format file --ttl 10m \
  --output "${TOKEN_DIR}/access.json"

aient --access-token-file "${TOKEN_DIR}/access.json" \
  sandbox list --environment development
cleanup_aient_access
trap - EXIT
```

| Flag             | Meaning                                                                            |
| ---------------- | ---------------------------------------------------------------------------------- |
| `--profile NAME` | Required refresh-backed source profile.                                            |
| `--format env`   | Print a shell assignment containing the live bearer token.                         |
| `--format json`  | Print a JSON access envelope containing the live bearer token.                     |
| `--format file`  | Atomically write a mode-`0600` JSON access envelope.                               |
| `--output PATH`  | Required destination for `file` format.                                            |
| `--ttl DURATION` | Requested lifetime from `1m` to `1h`; default `15m`. Actual expiry may be shorter. |

<Warning>
  The `env` and `json` formats deliberately print a live bearer token. Use them only when the receiving system requires stdout, disable shell tracing, keep the output out of logs and transcripts, and unset or delete the credential when the receiving process finishes.
</Warning>

An export contains no refresh token, environment secret, repository credential, or GitHub token. Imported access-only credentials are not refreshed or persisted by the CLI. When one expires, export another or sign in on that machine.

The CLI refuses to upload the active access-token file—or a hard link to it—through workspace sync, raw upload, or `files put`.

## Environment variables

| Variable                  | Use                                                         |
| ------------------------- | ----------------------------------------------------------- |
| `AIENT_PROFILE`           | Select one named refresh-backed profile.                    |
| `AIENT_ACCESS_TOKEN`      | Supply one raw short-lived access token. Treat as a secret. |
| `AIENT_ACCESS_TOKEN_FILE` | Read one exported mode-`0600` access envelope.              |