# atmos auth logout

Use this command to clear local session data (tokens, cached credentials) while preserving your keychain credentials for faster re-authentication. This is useful when switching identities, ending work sessions, or troubleshooting authentication issues.

:::tip Safe by Default
By default, `atmos auth logout` preserves your **keychain credentials** (IAM user access keys, service account credentials) to enable instant re-authentication. It only clears **session data** (AWS SSO tokens, temporary credentials).

To also delete keychain credentials, use the `--keychain` flag. This requires interactive confirmation for safety (bypass with `--force` in CI/CD).
:::

:::warning Browser Sessions Remain Active
This command only removes **local credentials**. It does **not** log you out of web-based sessions with your identity provider (AWS SSO, Okta, etc.). Your browser sessions remain active until you explicitly sign out from the identity provider's website.
:::

## The Problem

Most cloud practitioners never log out of their cloud provider identities. Not because they don't want to, but because the tooling doesn't make it easy.

When you authenticate with cloud providers, credentials get scattered across your filesystem:

- **AWS**: `~/.aws/credentials`, `~/.aws/config`, session tokens
- **Azure**: `~/.azure/` directory with multiple authentication artifacts
- **Google Cloud**: `~/.config/gcloud/` with various credential files

Most cloud provider tools don't provide a simple, comprehensive logout command. You're left to:

- Manually hunt down and delete credential files across different locations
- Navigate through provider-specific web consoles to revoke tokens
- Hope that session expiration handles cleanup for you

This leads to **credential sprawl**: old, forgotten credentials littering your system, many still valid and exploitable.

The `atmos auth logout` command makes credential cleanup explicit, comprehensive, and easy.

## Usage

```shell
atmos auth logout [identity] [options]
```

## Examples

### Logout from Specific Identity

```shell
# Using positional argument
atmos auth logout dev-admin

# Using --identity flag
atmos auth logout --identity dev-admin

# Using short form
atmos auth logout -i dev-admin
```

This removes only this identity's credentials from the system keyring and removes only this identity's profile from AWS config files. Other identities using the same provider are **not affected** and remain usable. The identity configuration in `atmos.yaml` is preserved and can be re-authenticated by running `atmos auth login`.

**Example output:**

```
Logging out from identity: dev-admin

Building authentication chain...
  ✓ Chain: aws-sso → dev-org-admin → dev-admin

Removing credentials...
  ✓ Keyring: aws-sso
  ✓ Keyring: dev-org-admin
  ✓ Keyring: dev-admin
  ✓ Files: ~/.config/atmos/aws/aws-sso/ (XDG-compliant)

Successfully logged out from 3 identities

⚠️  Note: This only removes local credentials. Your browser session
   may still be active. Visit your identity provider to end your
   browser session.
```

### Logout from All Identities

```shell
atmos auth logout --all
```

This removes all identity credentials from the system keyring and removes all identity profiles from AWS config files for all providers. All identity configurations remain in `atmos.yaml` and can be re-authenticated. This is useful when troubleshooting authentication issues or performing a complete credential cleanup.

**Example output:**

```
Logging out from all identities...

Removing all credentials...
  ✓ Keyring: aws-sso
  ✓ Keyring: dev-org-admin
  ✓ Keyring: dev-admin
  ✓ Keyring: prod-admin
  ✓ Files: ~/.config/atmos/aws/aws-sso/ (XDG-compliant)

Successfully logged out from 4 identities

⚠️  Note: This only removes local credentials. Your browser session
   may still be active. Visit your identity provider to end your
   browser session.
```

### Logout from Specific Provider

```shell
atmos auth logout --provider aws-sso
```

This removes all credentials from the system keyring for the provider and all identities that use it, and deletes the entire AWS config directory for the provider (all files). This is the most thorough cleanup and is useful when completely switching providers or AWS organizations.

**Example output:**

```
Logging out from provider: aws-sso

Removing all credentials for provider...
  ✓ Keyring: aws-sso
  ✓ Keyring: dev-org-admin (via aws-sso)
  ✓ Keyring: dev-admin (via aws-sso)
  ✓ Keyring: prod-admin (via aws-sso)
  ✓ Files: ~/.config/atmos/aws/aws-sso/ (XDG-compliant)

Successfully logged out from 4 identities
```

### Interactive Mode

```shell
atmos auth logout
```

When run without arguments, presents an interactive menu to choose what to logout from:

```
? Choose what to logout from:
  ❯ Identity: dev-admin
    Identity: prod-admin
    Identity: dev-readonly
    Provider: aws-sso (removes all identities)
    All identities (complete logout)
```

### Dry Run Mode

```shell
atmos auth logout dev-admin --dry-run
```

Preview what would be removed without actually deleting anything:

```
Dry run mode: No credentials will be removed

Would remove from identity: dev-admin
  • Keyring: aws-sso
  • Keyring: dev-org-admin
  • Keyring: dev-admin
  • Files: ~/.config/atmos/aws/aws-sso/credentials
  • Files: ~/.config/atmos/aws/aws-sso/config

3 identities would be logged out
```

You can also use `--dry-run` with `--all` to preview a complete logout:

```shell
atmos auth logout --all --dry-run
```

```
Dry run mode: No credentials will be removed

Would remove:
  • All identity keyring entries
  • All provider keyring entries
  • Files:
    - ~/.config/atmos/aws/aws-sso/
    - ~/.config/atmos/aws/backup-provider/
```

### Delete Keychain Credentials (Destructive)

By default, logout preserves keychain credentials for instant re-authentication. Use `--keychain` to permanently delete them:

```shell
# Interactive mode with confirmation
atmos auth logout dev-admin --keychain
```

**Interactive confirmation prompt:**

```
Delete keychain credentials for dev-admin?

This will permanently remove:
  • IAM user access keys
  • Service account credentials
  • Provider credentials

Session data will also be cleared.

? Yes, delete credentials / No, keep credentials
```

**For CI/CD (non-interactive):**

```shell
# Bypass confirmation with --force
atmos auth logout dev-admin --keychain --force
```

**What happens:**

- Deletes credentials from system keychain (IAM keys, service account creds)
- Clears session data (AWS SSO tokens, temporary credentials)
- Removes AWS config files
- Requires re-authentication (`atmos auth login`) to use this identity again

**When to use `--keychain`:**

- Permanently removing an identity you no longer need
- Security incident response (credential rotation)
- Switching to different IAM user or service account
- Complete credential cleanup before machine decommission

**When NOT to use `--keychain`:**

- Normal end-of-day logout (preserve keychain for next day)
- Switching between identities temporarily
- Troubleshooting authentication issues

## Quick Reference

Understanding what gets removed:

| Command | Keychain Credentials | Session Data | AWS Config Files | Use When |
|---------|---------------------|--------------|------------------|----------|
| `atmos auth logout <identity>` | **Preserved** | **Cleared** | **Identity profile removed** | End of work session |
| `atmos auth logout <identity> --keychain` | **Deleted** | **Cleared** | **Identity profile removed** | Permanently remove identity |
| `atmos auth logout --provider <name>` | **Preserved** | **Cleared** | **Entire provider directory** | Switch providers |
| `atmos auth logout --provider <name> --keychain` | **Deleted** | **Cleared** | **Entire provider directory** | Permanently remove provider |
| `atmos auth logout --all` | **Preserved** | **Cleared** | **All profiles removed** | Clean session data |
| `atmos auth logout --all --keychain` | **Deleted** | **Cleared** | **All profiles removed** | Complete cleanup |

:::tip Safe by Default
Without `--keychain`, logout preserves your stored credentials (IAM user keys, service account creds) for instant re-authentication. It only clears session data (AWS SSO tokens, temporary credentials).
:::

:::danger Permanent Deletion
Using `--keychain` permanently deletes credentials from your system keychain. You'll need to re-enter IAM user access keys or re-authenticate service accounts when logging in again.
:::

:::tip Re-authentication
All logout commands preserve your `atmos.yaml` configuration. Run `atmos auth login` to re-authenticate with any configured identity.
:::

## Arguments

- **`identity`**
  Name of the identity to logout from. Must match an identity defined in 
  `atmos.yaml`
  . If omitted, enters interactive mode. Can also be specified via the 
  `--identity`
   flag.

## Flags

- **`--identity` (alias `-i`)**

  Specify the identity to logout from. Alternative to using the positional argument. This flag has three modes:
  - **With value** (`--identity admin`): Logout from the specified identity
  - **Without value** (`--identity`): Show interactive selector to choose identity (same as omitting both flag and argument)
  - **Omitted**: Enter interactive mode if no positional argument is provided
  **Environment variables:** `ATMOS_IDENTITY` or `IDENTITY` (checked in that order)
- **`--all`**
  Logout from all identities and providers. Clears session data for all identities. Combine with 
  `--keychain`
   to also remove stored credentials.
- **`--provider`**
  Logout from a specific provider instead of an identity. Clears session data for all identities using this provider. Combine with 
  `--keychain`
   to also remove stored credentials.
- **`--keychain`**

  **Also delete credentials from system keychain** (destructive operation). By default, logout preserves keychain credentials (IAM user access keys, service account credentials) to enable instant re-authentication.

  **When specified:**
  - Requires interactive confirmation (shows what will be deleted)
  - Use `--force` to bypass confirmation in CI/CD environments
  - Permanently removes: IAM user access keys, service account credentials, provider credentials
  - Session data is also cleared (always happens during logout)
  **Example:**
  ```shell
  # Interactive confirmation
  atmos auth logout dev-admin --keychain

  # Non-interactive (CI/CD)
  atmos auth logout dev-admin --keychain --force
  ```
- **`--force`**

  Skip interactive confirmation prompts. Required when using `--keychain` in non-interactive environments (CI/CD pipelines, scripts).

  **Safety note:** Only use with `--keychain` when you're certain you want to delete credentials. This bypasses the confirmation dialog that warns about permanent credential deletion.
- **`--dry-run`**
  Preview what would be removed without actually deleting anything. Shows which session data and (if 
  `--keychain`
   is used) which keychain entries would be deleted. Useful for understanding the scope of logout.

## How It Works

### Default Behavior (Safe by Default)

By default, `atmos auth logout` clears **session data only**:

**Example:** For `atmos auth logout dev-admin` (without `--keychain`):

1. Clears session data:
   - Removes `dev-admin` profile from `~/.config/atmos/aws/aws-sso/credentials`
   - Removes `dev-admin` profile from `~/.config/atmos/aws/aws-sso/config`
   - Clears AWS SSO tokens from `~/.aws/sso/cache/`

2. Preserves keychain credentials:
   - Keyring entry for `dev-admin` is **preserved**
   - Keyring entries for authentication chain (`aws-sso`, `dev-org-admin`) are **preserved**
   - Other identity credentials remain intact

**Next login** (`atmos auth login --identity dev-admin`):

- Uses preserved keychain credentials instantly
- No need to re-enter IAM user access keys
- No need to re-authenticate service accounts
- Faster authentication (skips interactive prompts)

### Destructive Logout with --keychain

Adding `--keychain` permanently deletes credentials from system keychain:

**Example:** For `atmos auth logout dev-admin --keychain`:

1. Requires interactive confirmation (bypass with `--force` in CI/CD)
2. Deletes keychain credentials:
   - Removes keyring entry for `dev-admin`
   - IAM user access keys are permanently deleted
   - Service account credentials are permanently deleted
3. Clears session data (same as default logout)

**Next login** (`atmos auth login --identity dev-admin`):

- Requires re-entering IAM user access keys
- Requires re-authenticating service accounts
- Full authentication flow (no shortcuts)

### Provider Logout

When you log out of a provider using `--provider`, Atmos performs **complete cleanup for that provider**:

**Example:** For `atmos auth logout --provider aws-sso` (without `--keychain`):

1. Logs out each identity using the provider (clears session data for all)
2. Keychain credentials are **preserved** (unless `--keychain` is specified)
3. Deletes entire provider directory: `~/.config/atmos/aws/aws-sso/`

**With `--keychain`:** `atmos auth logout --provider aws-sso --keychain`

1. Deletes provider keyring entry
2. Deletes all identity keyring entries using this provider
3. Deletes entire provider directory

This is the nuclear option when you want to completely remove all traces of a provider.

### Credential Storage Locations

Atmos stores credentials in two locations:

#### 1. System Keyring

Credentials are securely stored in your operating system's keyring:

- **macOS**: Keychain Access
- **Linux**: Secret Service API (GNOME Keyring, KWallet)
- **Windows**: Windows Credential Manager

**Keyring entries** use the identity or provider name as the key with user `atmos-auth`.

#### 2. Provider-Specific Files

Some providers (like AWS) also write credential files for compatibility with other tools:

- **AWS credentials**: `<base_path>/<provider>/credentials`
- **AWS config**: `<base_path>/<provider>/config`

The default base path follows XDG Base Directory Specification (`~/.config/atmos/aws/` on both Linux and macOS), but this can be customized (see [Custom File Paths](#custom-file-paths)).

**Identity logout** selectively removes only that identity's profile from the config files using file locking to prevent conflicts. **Provider logout** (`--provider` flag) deletes the entire provider directory.

### Error Handling

The logout command uses **best-effort cleanup**: it continues even if individual steps fail and reports all errors at the end.

**Example with missing credentials:**

```shell
$ atmos auth logout dev-admin

Logging out from identity: dev-admin

Building authentication chain...
  ✓ Chain: aws-sso → dev-admin

Removing credentials...
  ✓ Keyring: aws-sso
  ✗ Keyring: dev-admin (not found - already logged out)
  ✓ Files: ~/.config/atmos/aws/aws-sso/ (XDG-compliant)

Logged out with warnings (2/3 successful)

Errors encountered:
  • dev-admin: credential not found in keyring
```

The command succeeds (exit code 0) as long as at least one credential was removed.

## Security Considerations

### Browser Sessions Remain Active

:::danger Web Sessions Not Affected
**Important**: The `atmos auth logout` command only removes **locally cached credentials from your filesystem and keychain**.

**Your browser session with the identity provider (AWS SSO, Okta, etc.) remains active and logged in.** Anyone with access to your browser can still access authenticated resources through your active web session.
:::

To completely end your session and fully logout:

1. Run `atmos auth logout` to remove local credentials
2. Visit your identity provider's website (e.g., `https://mycompany.awsapps.com/start`)
3. **Explicitly sign out** from the browser session
4. Close all browser windows

**Why this matters**: If you only run `atmos auth logout` without signing out of your browser, someone using your computer could potentially access your authenticated session through the browser.

### What Gets Removed

**Default logout** (without `--keychain`):

- ✅ AWS credential files (XDG-compliant: `~/.config/atmos/aws/<provider>/credentials`)
- ✅ AWS config files (XDG-compliant: `~/.config/atmos/aws/<provider>/config`)
- ✅ AWS SSO tokens (`~/.aws/sso/cache/`)
- ✅ Empty provider directories

**With `--keychain` flag:**

- ✅ Everything above, PLUS:
- ✅ Credentials stored in system keychain (IAM user keys, service account creds)
- ✅ Provider credentials from system keychain

**Logout does NOT remove:**

- ❌ Browser session cookies
- ❌ Identity provider sessions
- ❌ Credentials stored outside Atmos (e.g., `~/.aws/credentials`)
- ❌ Configuration files (e.g., `atmos.yaml`)

### Audit Trail

All logout operations are logged for security auditing:

```
2025-10-17T10:15:30Z DEBUG Starting logout identity=dev-admin
2025-10-17T10:15:30Z DEBUG Authentication chain built chain=[aws-sso dev-org-admin dev-admin]
2025-10-17T10:15:30Z DEBUG Removing keyring entry alias=aws-sso
2025-10-17T10:15:30Z DEBUG Removing keyring entry alias=dev-org-admin
2025-10-17T10:15:30Z DEBUG Removing keyring entry alias=dev-admin
2025-10-17T10:15:30Z INFO Logout completed identity=dev-admin removed=3
```

Enable debug logging with `ATMOS_LOGS_LEVEL=Debug` to see detailed audit information.

## Troubleshooting

### Identity Not Found

```
Error: identity "myidentity" not found in configuration

Available identities:
  • dev-admin
  • prod-admin
  • dev-readonly

Run 'atmos auth logout' without arguments for interactive selection.
```

**Solution**: Check your `atmos.yaml` configuration and ensure the identity name is spelled correctly.

### Already Logged Out

```
Identity 'dev-admin' is already logged out.
No credentials found in keyring or file storage.
```

This is informational, not an error. The identity has no cached credentials to remove.

### Permission Denied

```
Error: failed to delete credentials from keyring: access denied
```

**Solution**: The system keyring requires authentication. On macOS, you may need to grant Atmos permission in **System Preferences → Security & Privacy → Privacy → Accessibility**.

### Files Not Removed

```
✗ Files: ~/.config/atmos/aws/aws-sso/ (permission denied)
```

**Solution**: Ensure you have write permissions to the Atmos config directory. Check file ownership and permissions:

```shell
# On Linux:
ls -la ~/.config/atmos/

# On macOS:
ls -la ~/Library/Application\ Support/atmos/
```

## Related Commands

- [`atmos auth login`](/cli/commands/auth/login) - Authenticate with an identity
- [`atmos auth whoami`](/cli/commands/auth/whoami) - Show current authentication status
- [`atmos auth validate`](/cli/commands/auth/validate) - Validate authentication configuration
- [`atmos auth env`](/cli/commands/auth/env) - Export authentication environment variables

## Configuration

Logout works with identities and providers defined in your `atmos.yaml`:

```yaml
auth:
  providers:
    aws-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://mycompany.awsapps.com/start

  identities:
    dev-admin:
      kind: aws/permission-set
      via:
        provider: aws-sso
      principal:
        name: AdminAccess
        account:
          name: "dev-account"

    prod-admin:
      kind: aws/permission-set
      via:
        provider: aws-sso
      principal:
        name: AdminAccess
        account:
          name: "prod-account"
```

Running `atmos auth logout dev-admin` removes credentials for `dev-admin` and its authentication chain.

## Advanced Configuration

### Custom File Paths

AWS providers support configurable file storage locations via `spec.files.base_path`. This is useful for:

- **Custom directories**: Store credentials in non-standard locations
- **Container environments**: Use volume mounts at custom paths
- **Multi-user systems**: Isolate credentials per user or project

#### Configuration

In your `atmos.yaml`, add `spec.files.base_path` to your AWS provider:

```yaml
auth:
  providers:
    aws-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://mycompany.awsapps.com/start
      spec:
        files:
          base_path: ~/.custom/aws/credentials  # Custom path
```

#### Precedence

The file path is resolved using this precedence order:

1. **Provider configuration** (`spec.files.base_path` in `atmos.yaml`)
2. **Default** (XDG-compliant: `~/.config/atmos/aws/` on both Linux and macOS)

#### Path Expansion

Paths support tilde (`~`) expansion for user home directories:

```yaml
spec:
  files:
    base_path: ~/custom/path  # Expands to /Users/username/custom/path
```

#### Validation

The path is validated during `atmos auth validate`:

- Must not be empty or whitespace-only
- Must not contain null bytes, carriage returns, or newlines
- Tilde expansion must succeed

```shell
atmos auth validate
```

## Best Practices

### 1. Logout When Switching Contexts

When switching between different identities or environments, logout first to ensure clean state:

```shell
atmos auth logout dev-admin
atmos auth login --identity prod-admin
```

### 2. Logout at End of Work Session

Remove credentials when ending your work session for security:

```shell
# Logout from specific provider
atmos auth logout --provider aws-sso

# Or logout from all identities
atmos auth logout --all
```

### 3. Use Dry Run for Verification

Preview what will be removed before executing:

```shell
atmos auth logout dev-admin --dry-run
atmos auth logout dev-admin  # Proceed after verification
```

### 4. End Browser Sessions

Always sign out of browser sessions after local logout:

```shell
atmos auth logout
# Then visit your identity provider and sign out
```

### 5. Regular Credential Cleanup

Periodically clean up unused credentials:

```shell
atmos auth logout  # Interactive mode to review and remove
```

## See Also

- [Atmos Authentication Overview](/cli/commands/auth/usage)
- [AWS IAM Identity Center Configuration](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html)