switch-profile 0.2.3 → 1.0.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.0.0](https://github.com/nicolasdao/switch-profile/compare/v0.2.3...v1.0.0) (2026-03-21)
+
+
+### Features
+
+* Display export AWS_PROFILE hint after profile switch for per-terminal isolation ([7dd09c8](https://github.com/nicolasdao/switch-profile/commit/7dd09c882708fcafd66fefc6139cd97a13d9b2fb))
+
 ### [0.2.3](https://github.com/nicolasdao/switch-profile/compare/v0.2.2...v0.2.3) (2026-02-11)
 
 

package/README.md

@@ -52,6 +52,7 @@ This will:
 1. Show your current default profile with its expiry status.
 2. List all available profiles.
 3. Let you pick one to set as the new `default`.
+4. Display an `export AWS_PROFILE=<name>` command you can run to lock that profile to your current terminal session.
 
 For SSO profiles, if the session has expired, it automatically opens your browser for re-authentication.
 
@@ -97,6 +98,11 @@ When you select a profile, `switch-profile`:
 1. Retrieves the credentials for that profile (from cache or via SSO login).
 2. Writes them into the `[default]` section of both files.
 3. Records the profile name and expiry date for status display.
+4. Shows an `export AWS_PROFILE=<name>` command to optionally lock the profile to your terminal session.
+
+### Per-terminal profile isolation
+
+By default, switching profiles updates the global `[default]` section, which affects all terminals. If you need different AWS profiles in different terminals simultaneously, copy and run the `export AWS_PROFILE=<name>` command shown after each switch. This sets an environment variable scoped to that terminal only, so other terminals remain unaffected.
 
 For SSO profiles specifically, it leverages two additional AWS CLI cache directories:
 - `~/.aws/sso/cache/` - SSO session tokens (long-lived, ~24 hours)
@@ -113,6 +119,7 @@ For deeper technical details, see the docs below:
 | [CLI Interface](docs/cli-interface.md) | Detailed walkthrough of every menu, prompt, and user flow |
 | [Configuration Files](docs/configuration-files.md) | Exact formats of all AWS and internal configuration files |
 | [Development Guide](docs/development-guide.md) | How to set up, develop, test, lint, and release |
+| [Gotchas](docs/gotchas.md) | Critical pitfalls — global profile switching, per-terminal isolation limits, and LLM agent constraints |
 
 ## Troubleshooting
 

package/docs/architecture.md

@@ -37,7 +37,8 @@ The main executable file (with `#!/usr/bin/env node` shebang). Registered as the
 | Function | Purpose |
 |----------|---------|
 | `switchCmd()` | Main command handler. Checks AWS CLI, shows current profile status, lists profiles, renders the selection menu. |
-| `setProfileToDefault(name, list, msg)` | Gets credentials for a profile, writes them as the `[default]` profile. Shows a clear error if the profile is not found in the list. |
+| `setProfileToDefault(name, list, msg)` | Gets credentials for a profile, writes them as the `[default]` profile. Shows a clear error if the profile is not found in the list. Displays the `export AWS_PROFILE` hint on success. |
+| `printExportHint(profileName)` | Displays a cyan box with the `export AWS_PROFILE=<name>` command for per-terminal profile isolation. Box width adjusts dynamically to the profile name length. |
 | `createNewProfile(profiles, makeItDefault)` | Walks the user through creating a standard or SSO profile. Displays an SSO Setup Guide before SSO creation and checks for errors before reporting success. |
 | `chooseProfileName(denyList)` | Validates profile name input (lowercase alphanumeric, dashes, underscores, min 2 chars, no duplicates). |
 | `chooseRegions()` | Autocomplete region picker from the 24 supported AWS regions. |
@@ -181,5 +182,16 @@ User runs: npx switch-profile
     │  section to:         │
     │  - ~/.aws/credentials│
     │  - ~/.aws/config     │
+    └──────────────────────┘
+               │
+               ▼
+    ┌──────────────────────┐
+    │  printExportHint     │
+    │                      │
+    │  Shows:              │
+    │  export AWS_PROFILE= │
+    │  <name>              │
+    │  for per-terminal    │
+    │  isolation           │
     └──────────────────────┘
 ```

package/docs/cli-interface.md

@@ -84,8 +84,18 @@ On success:
 
 ```
 AWS profile sso-dev successfully set up as default.   # Green
+
+┌─────────────────────────────────────────────────────────┐
+│  To lock this profile to this terminal session, run:    │  # Cyan
+│                                                         │
+│    export AWS_PROFILE=sso-dev                           │  # Cyan + Bold
+│                                                         │
+│  This prevents other terminals from affecting this one. │
+└─────────────────────────────────────────────────────────┘
 ```
 
+This hint appears after every successful profile switch, refresh, or new profile set as default. Running the displayed `export` command sets the `AWS_PROFILE` environment variable in the current terminal only, enabling per-terminal profile isolation.
+
 ### Step 4b: More Options
 
 Selecting "More options" opens a submenu:
@@ -236,6 +246,14 @@ Selecting it:
 
 ```
 AWS profile sso-dev successfully refreshed.    # Green
+
+┌─────────────────────────────────────────────────────────┐
+│  To lock this profile to this terminal session, run:    │  # Cyan
+│                                                         │
+│    export AWS_PROFILE=sso-dev                           │  # Cyan + Bold
+│                                                         │
+│  This prevents other terminals from affecting this one. │
+└─────────────────────────────────────────────────────────┘
 ```
 
 ## Visual Indicators
@@ -247,6 +265,7 @@ AWS profile sso-dev successfully refreshed.    # Green
 | **Cyan** | Informational (current profile, time remaining) |
 | **Yellow** | Warnings (expired, expiring soon) |
 | **Bold** | Profile names in messages |
+| **Cyan + Bold** | Export command hint (the `export AWS_PROFILE=...` line) |
 
 ## Error Display
 

package/docs/gotchas.md

@@ -0,0 +1,78 @@
+# Gotchas
+
+Critical pitfalls and edge cases that are not immediately obvious when using `switch-profile`.
+
+## Table of Contents
+
+- [Profile switching is global by default](#profile-switching-is-global-by-default)
+    - [The problem](#the-problem)
+    - [The solution: `export AWS_PROFILE`](#the-solution-export-aws_profile)
+    - [The limitation: you must copy-paste it yourself](#the-limitation-you-must-copy-paste-it-yourself)
+    - [LLM agents and automation](#llm-agents-and-automation)
+
+## Profile switching is global by default
+
+### The problem
+
+When you run `npx switch-profile` and select a profile, the tool writes credentials into the `[default]` section of `~/.aws/credentials` and `~/.aws/config`. These are **global files** shared by every terminal, every tool, and every process on the machine.
+
+This means:
+- If Terminal A switches to `dev`, Terminal B is now also on `dev`.
+- If Terminal B then switches to `prod`, Terminal A is silently moved to `prod` too.
+- Any concurrent process relying on `[default]` (Terraform, CDK, scripts) is affected immediately.
+
+### The solution: `export AWS_PROFILE`
+
+After every successful switch, `switch-profile` displays a box like:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  To lock this profile to this terminal session, run:    │
+│                                                         │
+│    export AWS_PROFILE=dev                               │
+│                                                         │
+│  This prevents other terminals from affecting this one. │
+└─────────────────────────────────────────────────────────┘
+```
+
+Running `export AWS_PROFILE=dev` sets an environment variable **scoped to that terminal session only**. The AWS CLI and all AWS SDKs honor `AWS_PROFILE` and will use the named profile directly — bypassing `[default]` entirely. Other terminals remain unaffected.
+
+### The limitation: you must copy-paste it yourself
+
+`switch-profile` **cannot** set the environment variable for you. This is a fundamental operating system constraint: a child process (the `npx` command) cannot modify the environment of its parent process (your terminal shell). The `export` command must be run directly in the terminal by the user.
+
+There is no workaround for this within the tool itself. The user must manually copy-paste and run the `export AWS_PROFILE=<name>` command shown after each switch.
+
+### LLM agents and automation
+
+When an LLM agent (e.g., a Claude Code skill) uses `switch-profile` via a shell tool, the same constraint applies — but with an additional twist.
+
+**Environment variables do not persist between shell tool invocations.** Each time an LLM agent runs a Bash command, it spawns a **new shell subprocess**. So even if the agent runs `export AWS_PROFILE=dev` in one command, that variable is gone in the next command.
+
+**Workaround:** The agent must prefix every AWS command with the profile inline:
+
+```shell
+AWS_PROFILE=dev aws s3 ls
+AWS_PROFILE=dev terraform plan
+AWS_PROFILE=prod aws sts get-caller-identity
+```
+
+This works reliably and supports concurrent agents using different profiles, since each command carries its own profile context with no shared global state.
+
+**What does NOT work for agents:**
+
+```shell
+# Command 1 — sets the variable, but only in this subprocess
+export AWS_PROFILE=dev
+
+# Command 2 — this is a NEW subprocess, AWS_PROFILE is not set here
+aws s3 ls   # Uses [default], NOT dev
+```
+
+**Chaining commands in a single invocation** also works but is less practical for multi-step workflows:
+
+```shell
+export AWS_PROFILE=dev && aws s3 ls && aws sts get-caller-identity
+```
+
+**Summary for skill/agent authors:** After running `npx switch-profile` to authenticate and ensure the SSO session is valid, extract the profile name and use `AWS_PROFILE=<name>` as an inline prefix on every subsequent AWS command.

package/index.js

@@ -330,6 +330,26 @@ const switchCmd = async () => {
 	}
 }
 
+const printExportHint = (profileName) => {
+	const lines = [
+		'  To lock this profile to this terminal session, run:  ',
+		'',
+		`    export AWS_PROFILE=${profileName}`,
+		'',
+		'  This prevents other terminals from affecting this one.  '
+	]
+	const width = Math.max(...lines.map(l => l.length))
+	const pad = s => s + ' '.repeat(width - s.length)
+	console.log('')
+	console.log(('┌' + '─'.repeat(width) + '┐').cyan)
+	for (let i = 0; i < lines.length; i++) {
+		const content = '│' + pad(lines[i]) + '│'
+		console.log(i === 2 ? content.cyan.bold : content.cyan)
+	}
+	console.log(('└' + '─'.repeat(width) + '┘').cyan)
+	console.log('')
+}
+
 const setProfileToDefault = async (profileName, profileList, successMsg) => {
 	const profile = profileList.find(p => p.friendlyName == profileName || p.name == profileName)
 
@@ -357,6 +377,7 @@ const setProfileToDefault = async (profileName, profileList, successMsg) => {
 		return printAWSerrors([new Error('Fail to update the default profile'), ...errors])
 
 	console.log((successMsg || `AWS profile ${profile.name.bold} successfully set up as default.`).green)
+	printExportHint(profile.name)
 }
 
 // 1. Creates your first command. This example shows an 'order' command with a required argument

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switch-profile",
-  "version": "0.2.3",
+  "version": "1.0.0",
   "main": "index.js",
   "bin": "index.js",
   "description": "NPX script that exposes terminal shortcut to easily switch between cloud configuration (aws, gcp).",

package/skills-lock.json

@@ -0,0 +1,73 @@
+{
+	"lockVersion": 1,
+	"generatedAt": "2026-03-21T07:51:15.981Z",
+	"skills": {
+		"happyskillsai/happyskills": {
+			"version": "1.17.0",
+			"ref": "refs/tags/v1.17.0",
+			"commit": "8024d2ee1efd9f17391ebd701a6e6131eafec14777d550e23d3d3a50b5d11439",
+			"integrity": "sha256-24e69e779a31ade191ae2fb9dec5a90d28fd9d4afcda2851fc048dd03093c6fb",
+			"requested_by": [
+				"__root__"
+			],
+			"dependencies": {}
+		},
+		"nicolasdao/_kit-dev-essentials": {
+			"version": "1.0.0",
+			"ref": "refs/tags/v1.0.0",
+			"commit": "7c793754d999f50dc44e289b6d190e5f9dc2959e132f62c84625897ced7f95f7",
+			"integrity": "sha256-f4fe6b211aa96bbc291c880a4a61682bf5d438a52db0b82e73f42e7126c39e45",
+			"requested_by": [
+				"__root__"
+			],
+			"dependencies": {
+				"nicolasdao/git-commit": "*",
+				"nicolasdao/update-doc": "*",
+				"nicolasdao/init-doc": "*",
+				"nicolasdao/init-context": "*"
+			},
+			"type": "kit"
+		},
+		"nicolasdao/git-commit": {
+			"version": "1.0.1",
+			"ref": "refs/tags/v1.0.1",
+			"commit": "315daee8d9d3ad5e88c42ed35b8e89ccc7ff57bfc28ef0d72ad5122c8e834e19",
+			"integrity": "sha256-d7e5a0e9afe9f2633e4e9ad64d8248fca0ee8e20a44f54586474bbfecc79d7e7",
+			"requested_by": [
+				"nicolasdao/_kit-dev-essentials"
+			],
+			"dependencies": {}
+		},
+		"nicolasdao/update-doc": {
+			"version": "1.0.4",
+			"ref": "refs/tags/v1.0.4",
+			"commit": "6394de7f8b487c16700f84d5235a3dca5746205d2abafbdfad02e59bbd924a60",
+			"integrity": "sha256-e60d3df49530031a5f663aed8a6999fda6b4caab4deba249ec7cfd5ec65f085c",
+			"requested_by": [
+				"nicolasdao/_kit-dev-essentials"
+			],
+			"dependencies": {}
+		},
+		"nicolasdao/init-doc": {
+			"version": "0.1.1",
+			"ref": "refs/tags/v0.1.1",
+			"commit": "9603e12aa7dba8c2d6903f249a60b418f3913c94dddfde266e065d1b9bbd0171",
+			"integrity": "sha256-567e6e55d27b9873bf1664bd7992cc8d3b7045e4d371de136245e5193e04b680",
+			"requested_by": [
+				"nicolasdao/_kit-dev-essentials"
+			],
+			"dependencies": {},
+			"type": "skill"
+		},
+		"nicolasdao/init-context": {
+			"version": "1.0.1",
+			"ref": "refs/tags/v1.0.1",
+			"commit": "a52d089f1c6a102feac17b99e7df72e29899952f393013bd479e3f97cc614f32",
+			"integrity": "sha256-417c5dc3e0b59f785fd8af166bbaa757f4bfac8343d7365708342e84d386bd01",
+			"requested_by": [
+				"nicolasdao/_kit-dev-essentials"
+			],
+			"dependencies": {}
+		}
+	}
+}