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.

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

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.

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/

Delete Keychain Credentials (Destructive)

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

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

# 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

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

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.

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:

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

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

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:

# 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