AWS Profile Manager Documentation

Complete guide to installing, configuring, and using AWS Profile Manager — your all-in-one dashboard for managing AWS CLI profiles, terminal, AI commands, and cost analysis.

Installation

System Requirements

Install from Source

git clone https://github.com/ynikolarakis/aws-profile-manager.git
cd aws-profile-manager

make setup

make build

make start

Available Commands

Quick Start

After installation, open http://localhost:8099 in your browser. The app automatically reads your existing AWS profiles from ~/.aws/config and ~/.aws/credentials.

Interface Overview

The interface follows a terminal-first design: the command area takes center stage, while profile management lives in the sidebar.

Main interface — sidebar with profiles, terminal area, and header bar

Profile Types

AWS Profile Manager supports all three AWS CLI profile types:

SSO Profiles SSO

Use AWS IAM Identity Center (formerly AWS SSO) to authenticate. Session tokens are cached in ~/.aws/sso/cache/. The app automatically checks token validity and shows a status indicator.

Credential Profiles CREDENTIALS

Long-term access keys stored in ~/.aws/credentials. Secret keys are masked in the UI after saving.

Role Profiles ROLE

Assume a role from another profile. No credentials stored directly — uses the source profile to get temporary credentials.

Creating Profiles

Click + New Profile in the header or press Ctrl+N to open the creation dialog.

New Profile dialog — select type (SSO, Credentials, Role), fill in fields, assign category

1. Enter a profile name (letters, numbers, hyphens, underscores, dots only)
2. Optionally assign to a category
3. Select the profile type (SSO, Credentials, or Role)
4. Fill in the required fields for the selected type
5. Choose your default region and output format
6. Click Save

Managing Profiles

Click any profile in the sidebar to activate it. The app runs an identity check (STS GetCallerIdentity) and displays the account ID and ARN in the terminal header.

Active profile showing identity verification in the terminal header

• Activate — Click profile name, use command palette (Ctrl+K), or search
• Edit — Click the three-dot menu on a profile item
• Delete — Available in the context menu or profile editor
• Move to category — Drag or use the context menu to reassign

Categories

Organize profiles into collapsible groups with custom colors. Click Category in the sidebar to create and manage categories.

New Category dialog — name and color picker with 12+ color options

• Create — Click "Category" button or use command palette
• Edit — Click the gear icon on any category header to rename or change color
• Delete — Removes the category but keeps all profiles (moved to uncategorized)
• Collapse/Expand — Click the category header. State is persisted across sessions

Search & Filter

The search field at the top of the sidebar filters profiles in real-time as you type. It matches against profile name, type, region, and account ID.

Searching for "Prod" — instantly filters to matching profiles across all categories

Import & Export

Share profile configurations across machines or team members using JSON export/import.

• Export — Command palette (Ctrl+K) → "Export Profiles". Downloads a timestamped JSON file with all profiles and categories.
• Import — Command palette → "Import Profiles". Select a JSON file to restore profiles and category mappings.

Running Commands

The terminal is the core of the application. Type any AWS CLI command and press Enter. The active profile's credentials are injected automatically.

Running aws s3 ls — output streams in real-time with the active profile's credentials

• Profile context — credentials and region are set automatically based on the active profile
• History — use Arrow Up/Down to navigate previous commands
• Streaming output — results appear line-by-line as they're received
• Focus shortcut — press Ctrl+/ to jump to the terminal input from anywhere

Running aws sts get-caller-identity — verifies which account and role you're operating as

Bulk Run

Execute the same command across multiple profiles simultaneously. Click Bulk Run in the sidebar or use the command palette.

Bulk Run — select profiles, enter a command, use quick templates (Identity, S3 Buckets)

• Select individual profiles or click All to select everything
• Use quick templates: "Identity" runs aws sts get-caller-identity, "S3 Buckets" runs aws s3 ls
• Results are separated by profile name with individual exit codes
• Each command has a 30-second timeout

Terminal Encoding

If terminal output shows garbled characters, adjust the encoding in Settings → General → Terminal Output Encoding.

Settings → General — change terminal output encoding (UTF-8, CP437, CP850, etc.)

Common encoding options:

AI Integration Overview

AWS Profile Manager integrates with 6 LLM providers to generate AWS CLI commands from natural language descriptions. Toggle AI mode with the AI button in the terminal bar or press Ctrl+I.

AI mode enabled — the input changes to "Describe what you want to do..."

Configuring AI Providers

Open Settings (gear icon in header) → AI Providers tab. Select your default provider and configure API keys.

Settings → AI Providers — configure API keys, select models, test connectivity

1. Choose a Default Provider from the dropdown
2. Expand the provider you want to configure
3. Enter your API key (stored locally, never transmitted)
4. Select a model from the dropdown
5. Click Test to verify the connection
6. Click Save

Generating Commands with AI

With AI mode active, describe what you want in plain English. The AI generates the exact AWS CLI command, context-aware of your active profile and region.

AI generates aws ec2 describe-instances from "show all EC2 instances running in eu-central-1" — with Run and Copy buttons

After the command is generated:

• Run — execute the command immediately with your active profile
• Copy — copy the command to clipboard
• Dismiss — clear the suggestion (X button)

Example prompts:

Command Palette

Press Ctrl+K to open the command palette — a quick launcher for switching profiles, running actions, and accessing features.

Command palette — search and switch profiles instantly, with type badges

Available actions in the command palette:

• Switch Profile — type a profile name to filter and activate
• New Profile — create a new profile
• Reload Profiles — refresh from AWS config files
• Import / Export Profiles — bulk operations
• Discover SSO Accounts — scan for accounts
• Toggle AI Mode
• Switch Theme (Light / Dark)
• Add Favorite Command
• Open Settings

SSO Account Discovery

If you use AWS IAM Identity Center, the app can automatically discover all accounts and roles you have access to.

1. Open the command palette (Ctrl+K) and select Discover SSO Accounts
2. The app finds valid SSO tokens in ~/.aws/sso/cache/
3. It calls the SSO API to list all accounts and their available roles
4. Review the discovered accounts — duplicates are flagged
5. Select the accounts you want and click Import

Cost Explorer

View per-profile AWS spending with a monthly service breakdown. Cost badges appear next to each profile in the sidebar showing the last 30 days of spending.

• Cost badges — appear automatically in the sidebar if the profile has Cost Explorer access
• Detailed breakdown — click the cost badge or use the terminal header to open the Cost Explorer dialog
• Monthly navigation — browse previous months to track spending trends
• Service breakdown — see costs per AWS service with visual bars

Favorites

Save frequently used commands as favorites for one-click access from the header bar.

• Open command palette (Ctrl+K) → Add Favorite Command
• Enter a label (e.g., "Check STS") and the command
• Favorites appear as buttons in the header — click to execute immediately
• Remove favorites via the command palette

Themes

Toggle between dark and light mode using the theme button in the header or via the command palette.

Light mode — full application with white background

Keyboard Shortcuts

Configuration Files

AWS Profile Manager reads and writes the standard AWS CLI configuration files plus its own state file:

profile-manager.json Structure

{
  "categories": {
    "cat_id": { "name": "Production", "color": "#22c55e", "order": 0 }
  },
  "profile_cat": {
    "Prod_Monitoring": "cat_id"
  },
  "favorites": [
    { "label": "Check STS", "cmd": "aws sts get-caller-identity" }
  ],
  "theme": "dark",
  "collapsed": { "cat_id": false },
  "terminal_encoding": "cp437",
  "llm_config": {
    "default_provider": "openai",
    "providers": {
      "openai": { "api_key": "sk-...", "model": "gpt-4o" }
    }
  }
}

Troubleshooting

App won't start

• Ensure Python 3.10+ is installed: python --version
• Ensure Node.js 18+ is installed: node --version
• Run make setup to reinstall dependencies
• Check if port 8099 is already in use

SSO profiles show "expired"

• Run aws sso login --profile <profile-name> in an external terminal
• Check that your SSO start URL is correct in the profile config
• SSO sessions typically expire after 8-12 hours

Terminal output shows garbled characters

• Open Settings → General → Terminal Output Encoding
• Try UTF-8 first, then CP437 (Windows US), or CP1252 (Windows EU)

AI commands not generating

• Verify your API key in Settings → AI Providers
• Click Test next to the provider to check connectivity
• For Ollama, ensure the local server is running and the base URL is correct
• For Bedrock, ensure the active profile has bedrock:InvokeModel permissions

Cost badges not appearing

• The profile needs ce:GetCostAndUsage IAM permission
• New AWS accounts may not have Cost Explorer enabled — activate it in the AWS Console first
• Cost data can take up to 24 hours to appear for new accounts

Commands fail with "aws not found"

• Install the AWS CLI v2: AWS CLI Installation Guide
• Ensure aws is in your system PATH
• Restart the app after installing AWS CLI