atmos auth logout

Use this command to securely remove locally cached authentication credentials from the system keyring and credential files. This is useful when switching identities, ending work sessions, or troubleshooting authentication issues.

Local Credentials Only

This command only removes credentials stored on your local filesystem and system keychain. It does not log you out of any web-based sessions with your identity provider (AWS SSO, Okta, etc.). Your browser sessions will 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.

atmos auth logout --help

Usage

atmos auth logout [identity] [options]

Examples

Logout from Specific Identity

# 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

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

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

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

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:

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/

Quick Reference

Understanding what gets removed:

Command	Keyring Entries	AWS Config Files	atmos.yaml Configuration	Use When
atmos auth logout <identity>	Identity only	Identity profile removed	Not affected	Done with specific identity
atmos auth logout --provider <name>	Provider + all identities	Entire provider directory	Not affected	Switching providers or AWS organizations
atmos auth logout --all	All identities	All identity profiles	Not affected	Complete cleanup or troubleshooting

Selective Cleanup

atmos auth logout <identity> only removes that specific identity. Other identities using the same provider remain authenticated and usable. Use --provider for complete provider cleanup.

Re-authentication

All logout commands preserve your atmos.yaml configuration. Simply run atmos auth login to authenticate again 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. Removes all cached credentials from the system keyring and credential files. Useful when switching AWS organizations or troubleshooting authentication issues.

--provider

Logout from a specific provider instead of an identity. Removes all identities that authenticate through this provider.

--dry-run

Preview what would be removed without actually deleting credentials. Useful for understanding the scope of logout.

How It Works

Selective Identity Logout

When you log out of a specific identity, Atmos performs selective cleanup to preserve other identities:

Example: For atmos auth logout dev-admin with chain aws-sso → dev-org-admin → dev-admin:

1. Removes keyring entry for only dev-admin
2. Removes dev-admin profile from ~/.config/atmos/aws/aws-sso/credentials
3. Removes dev-admin profile from ~/.config/atmos/aws/aws-sso/config
4. Keyring entries for aws-sso and dev-org-admin are preserved
5. Other identity profiles in the config files are preserved

Other identities using aws-sso (like prod-admin, staging-admin) remain fully functional.

Provider Logout (Complete Cleanup)

When you log out of a provider using --provider, Atmos performs complete cleanup:

Example: For atmos auth logout --provider aws-sso:

1. Logs out each identity using the provider (removes keyring + profiles)
2. Removes provider keyring entry: aws-sso
3. Deletes entire provider directory: ~/.config/atmos/aws/aws-sso/

This is the nuclear option - all identities using that provider will need to re-authenticate.

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

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:

$ 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

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

Logout removes:

• ✅ Credentials stored in system keyring
• ✅ AWS credential files (XDG-compliant: ~/.config/atmos/aws/<provider>/credentials on Linux)
• ✅ AWS config files (XDG-compliant: ~/.config/atmos/aws/<provider>/config on Linux)
• ✅ Empty provider directories

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:

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

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

Related Commands

• atmos auth login - Authenticate with an identity
• atmos auth whoami - Show current authentication status
• atmos auth validate - Validate authentication configuration
• atmos auth env - Export authentication environment variables

Configuration

Logout works with identities and providers defined in your atmos.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:

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:

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

atmos auth validate

Best Practices

1. Logout When Switching Contexts

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

atmos auth logout dev-admin
atmos auth login prod-admin

2. Logout at End of Work Session

Remove credentials when ending your work session for security:

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

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:

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

5. Regular Credential Cleanup

Periodically clean up unused credentials:

atmos auth logout  # Interactive mode to review and remove

See Also

• Atmos Authentication Overview
• AWS IAM Identity Center Configuration