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. Open the browser consent flow and save a refresh-backed customer session:

aient auth login --print-url
aient auth login --profile client-a --print-url

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`.
`--print-url`	Print the one-time authorization URL instead of opening a browser. Keep the command running while approving it.
`--project-access=auto`	In the nearest configured project, install or reconcile bounded managed access. This is the default.
`--project-access=none`	Keep only the host login and remove managed access for the nearest configured project.

On macOS, project access keeps refresh authority in Keychain and installs a launchd user service that rotates a 15-minute envelope under the Git common directory for up to 90 days. Login returns only after that exact manager-owned renewal is verified. The terminal can then close; no foreground process or PID owns renewal. Linux managed renewal remains preview pending a real systemd-user and D-Bus Secret Service renewal, restart, and logout canary. Use --project-access=none for host-only login when you do not explicitly want to opt into that preview. 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. Customer MCP management adds mcp_connections:read and mcp_connections:manage. Run aient auth login again if an existing profile receives 403 for aient environment mcp after upgrading to a CLI release that includes those commands.

`aient auth status`

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

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. From a configured project with no explicit profile, status discovers the repository-private access envelope, verifies its product context, and reports safe lease metadata without reading host refresh authority. A present invalid or expired project envelope fails closed instead of falling back to a host profile. An explicit --profile selects the host recovery view, including derived managed-service health.

`aient auth logout`

Revoke and remove only the selected login:

aient auth logout --profile client-a

Before revoking the selected profile, logout stops and removes every managed project service installed for that profile. A cleanup failure is reported while credential revocation still proceeds. Logging out one profile does not remove another organisation’s profile.

`aient auth profiles`

List locally known named profiles:

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:

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:

profile: client-a
organisation: 11111111-1111-4111-8111-111111111111
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 canonical lowercase organisation UUID 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:

An explicit access-only source: --access-token-file, AIENT_ACCESS_TOKEN_FILE, or AIENT_ACCESS_TOKEN.
--profile NAME.
AIENT_PROFILE.
A valid <git-common-dir>/aient/access-v1.json belonging to the nearest configured project.
The profile named by the nearest .aient/config.yaml.
The user default selected by auth profiles default.
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:

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.
`--renew-for DURATION`	Keep an explicit file export renewed for `1m` to `90d`; the foreground caller owns that lifecycle.
`--store-in-project`	Install or reconcile manager-owned access for the nearest configured project for up to 90 days.

Use the project form to repair an already logged-in host profile without re-running browser OAuth:

aient --profile client-a auth export --store-in-project

In Aient CLI 0.10.16 and newer, this returns after the manager-owned renewer is verified. It is not the old foreground exporter contract.

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.

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.

`aient auth exec`

Run a trusted local task with a renewable, access-only credential rather than exposing the selected profile or its refresh token:

aient auth exec --profile client-a -- ./trusted-wrapper

The child receives AIENT_ACCESS_TOKEN_FILE only. The CLI removes Aient profile, token, and sandbox-control variables from the child environment, creates a temporary access-only file, renews it while the task runs, and removes it when the task finishes. auth exec requires a refresh-backed customer profile. It rejects an imported access token and operator authority. If you do not provide --profile, the nearest project configuration must contain a canonical organisation UUID. By default, the delegated credential covers sandbox reads, creation, deletion, execution, shell access, file operations, and authorised environment use. Use repeatable --scope only when the task needs a different exact scope set; it replaces the default set. Repository-write and pull-request scopes also require an exact project repository, a matching origin or upstream remote, and --confirm-repository OWNER/NAME.

auth exec minimises Aient credentials; it is not a local process sandbox. A same-user child can still reach the host filesystem, home directory, credential store, session, and sibling processes. Use an external confinement boundary for untrusted code.

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.

Reference

Changelog

Authentication and project profiles

Authentication and project profiles

`aient auth status`

`aient auth logout`

`aient auth profiles`

`aient auth profiles default`

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

Profile resolution order

`aient auth export`

`aient auth exec`

Environment variables

​Authentication and project profiles

​aient auth login

​aient auth status

​aient auth logout

​aient auth profiles

​aient auth profiles default

​Bind a checkout with .aient/config.yaml

​Profile resolution order

​aient auth export

​aient auth exec

​Environment variables

Authentication and project profiles

`aient auth login`

`aient auth status`

`aient auth logout`

`aient auth profiles`

`aient auth profiles default`

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

Profile resolution order

`aient auth export`

`aient auth exec`

Environment variables