docs: Enhance atmos auth env documentation by osterman · Pull Request #1778 · cloudposse/atmos

osterman · 2025-11-10T17:26:19Z

Summary

Comprehensive documentation improvements for atmos auth env command addressing real-world usage patterns discovered in community feedback. Adds missing --login flag documentation, shell integration guidance, and practical examples including a provider-agnostic identity switching helper function.

Changes

Documents --login flag for explicit authentication triggering
Clarifies that command outputs environment variables (doesn't modify parent shell)
Adds "How It Works" section with typical workflow
Adds "Shell Integration" section with profile setup and Warp terminal integration
Includes provider-agnostic use-identity helper function
Documents provider-specific environment variables (AWS, GitHub OIDC)
Adds clear guidance on when to use auth env vs auth shell
Improves accuracy of all technical explanations

Context

Addresses questions raised by users about using atmos auth env in shell profiles without triggering login prompts, and documents the --login flag that was previously undocumented.

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features
- Added --login flag to atmos auth env command for explicit authentication control. By default, cached credentials are used unless the flag is specified.
Documentation
- Updated command documentation with comprehensive usage examples, shell integration guidance, and detailed authentication flow information for AWS and GitHub OIDC providers.

… --login flag Add comprehensive documentation covering: - How `atmos auth env` works (outputs environment variables, doesn't perform auth) - When to use `atmos auth env` vs `atmos auth shell` - Shell profile integration and safety (no login prompts on startup) - Warp terminal integration - Helper function for identity switching (`use-identity`) - Provider-specific environment variables (AWS, GitHub OIDC) - Complete --login flag documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

coderabbitai · 2025-11-10T17:26:32Z

Warning

Rate limit exceeded

@osterman has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 8 minutes and 18 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between aed22e5 and 4209755.

📒 Files selected for processing (1)

website/docs/cli/commands/auth/auth-env.mdx (3 hunks)

📝 Walkthrough

Walkthrough

Documentation update to the auth-env command guide, adding content for a new --login flag that triggers authentication when credentials are missing or expired, with sections on behavior, shell integration, and environment variable output.

Changes

Cohort / File(s)	Change Summary
Auth environment documentation `website/docs/cli/commands/auth/auth-env.mdx`	Adds `--login` flag documentation with "How It Works" section, shell integration guidance, environment variable details for AWS and GitHub OIDC providers, Warp Terminal integration notes, and "See Also" cross-references.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Verify examples are accurate and executable
Confirm environment variable documentation aligns with actual provider behavior
Check shell integration code snippets for correctness

Possibly related PRs

#1633: Updates frontmatter in the same documentation file; coordinate changes to avoid conflicts.

Suggested labels

no-release

Suggested reviewers

aknysh
milldr

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: Enhance atmos auth env documentation' directly and accurately reflects the main change—documentation updates for the atmos auth env command with new sections and clarifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions · 2025-11-10T17:27:14Z

Dependency Review

✅ No vulnerabilities or license issues found.

Scanned Files

None

…ogin flag The previous wording incorrectly stated the command does not perform authentication. It does when the --login flag is specified. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

codecov · 2025-11-10T17:43:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.65%. Comparing base (ed571f9) to head (4209755).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1778      +/-   ##
==========================================
- Coverage   70.66%   70.65%   -0.02%     
==========================================
  Files         430      430              
  Lines       39707    39707              
==========================================
- Hits        28059    28055       -4     
- Misses       9261     9263       +2     
- Partials     2387     2389       +2

Flag	Coverage Δ
unittests	`70.65% <ø> (-0.02%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 4 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

oycyc

Looks great! New helpful in the Examples section.

Also, I don't know if it's adding too much references in Warp 😅, can probably mention generically "UI terminal emulators such as Warp".. not sure the specific categorization of them.

website/docs/cli/commands/auth/auth-env.mdx

… shell Removed incorrect claim about Warp environment variables persisting across panes and updated the Warp Terminal section to explain why users should use `atmos auth env` instead of `atmos auth shell` with feature-rich terminals. The `atmos auth shell` command launches a subshell that loses terminal emulator features like command palette, AI assistant, and blocks. Using `atmos auth env` with a helper function like `use-identity()` maintains the terminal's UI while providing credential management. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Corrected internal documentation links to use proper URL pattern without 'auth-' prefix: - /cli/commands/auth/auth-shell → /cli/commands/auth/shell - /cli/commands/auth/auth-login → /cli/commands/auth/login - /cli/commands/auth/auth-whoami → /cli/commands/auth/whoami The correct URL pattern matches the 'id' field in frontmatter and is consistent with how other auth command documentation files reference these commands. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

osterman · 2025-11-10T20:02:13Z

Also, I don't know if it's adding too much references in Warp 😅, can probably mention generically "UI terminal emulators such as Warp".. not sure the specific categorization of them.

We use Warp too. More and more of our customers do as well. =)

Improved documentation structure: - Moved format descriptions from standalone "Formats" section to --format flag documentation - Relocated "Helper Function for Identity Switching" to appear immediately after basic shell profile example - Updated Warp Terminal info box reference from "shown below" to "shown above" This reorganization makes it clearer that formats are controlled by the --format flag and provides better flow by showing the helper function right after the basic usage example. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

github-actions · 2025-11-11T07:52:58Z

These changes were released in v1.198.0-test.12.

osterman requested a review from a team as a code owner November 10, 2025 17:26

github-actions bot added the size/m Medium size PR label Nov 10, 2025

Claude (via Conductor) and others added 3 commits November 10, 2025 11:27

docs: Move helper function to collapsible details block

27695c0

docs: Convert Warp Terminal section to info admonition

ee5b3dd

oycyc reviewed Nov 10, 2025

View reviewed changes

website/docs/cli/commands/auth/auth-env.mdx Outdated Show resolved Hide resolved

website/docs/cli/commands/auth/auth-env.mdx Show resolved Hide resolved

oycyc reviewed Nov 10, 2025

View reviewed changes

website/docs/cli/commands/auth/auth-env.mdx Outdated Show resolved Hide resolved

coderabbitai bot previously approved these changes Nov 10, 2025

View reviewed changes

Merge branch 'main' into osterman/auth-env-login-flag

f135944

osterman added the no-release Do not create a new release (wait for additional code changes) label Nov 10, 2025

osterman dismissed coderabbitai[bot]’s stale review via 68b602c November 10, 2025 19:48

github-actions bot deployed to preview November 10, 2025 19:51 View deployment

github-actions bot deployed to preview November 10, 2025 20:09 View deployment

aknysh approved these changes Nov 10, 2025

View reviewed changes

aknysh merged commit ff26f86 into main Nov 10, 2025
54 checks passed

aknysh deleted the osterman/auth-env-login-flag branch November 10, 2025 20:59

coderabbitai bot mentioned this pull request Jan 23, 2026

fix: Windows toolchain installation issues #2012

Merged

coderabbitai bot mentioned this pull request Feb 28, 2026

Add AI Agent Skills for LLM-Powered Infrastructure Development #2121

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: Enhance atmos auth env documentation#1778

docs: Enhance atmos auth env documentation#1778
aknysh merged 8 commits intomainfrom
osterman/auth-env-login-flag

osterman commented Nov 10, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Nov 10, 2025 •

edited

Loading

Rate limit exceeded

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Uh oh!

github-actions bot commented Nov 10, 2025 •

edited

Loading

Uh oh!

codecov bot commented Nov 10, 2025 •

edited

Loading

Uh oh!

oycyc left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

osterman commented Nov 10, 2025

Uh oh!

Uh oh!

github-actions bot commented Nov 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

osterman commented Nov 10, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Context

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rate limit exceeded

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Pre-merge checks and finishing touches

Uh oh!

github-actions bot commented Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Review

Scanned Files

Uh oh!

codecov bot commented Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

oycyc left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

osterman commented Nov 10, 2025

Uh oh!

Uh oh!

github-actions bot commented Nov 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

osterman commented Nov 10, 2025 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Nov 10, 2025 •

edited

Loading

github-actions bot commented Nov 10, 2025 •

edited

Loading

codecov bot commented Nov 10, 2025 •

edited

Loading

oycyc left a comment •

edited

Loading