Padua CLI

A unified CLI for AWS infrastructure management—authentication, tunneling, and container tools in one place.

Installation

npm install -g @padua/cli

Prerequisites

Required:

• Node.js v20+
• AWS CLI v2

Optional:

• npm (for CodeArtifact registry authentication)
• Docker (for ECR registry authentication)
• Session Manager Plugin (for padua tunnel command)

Note: padua init validates prerequisites and displays install URLs for any missing tools.

Quick Start

⚠️ WARNING: padua init will delete your existing ~/.aws/config file to ensure a clean configuration. A timestamped backup is automatically created at ~/.aws/config.backup.<timestamp>. Use the --keep-existing flag to preserve custom non-Padua profiles.

# 1. Initialize configuration (discovers SSO accounts automatically)
padua init

# 2. Login to all services
padua login

The init command will:

• Check for required prerequisites
• Detect AWS environment variables and warn if present
• Authenticate with AWS SSO
• Discover all accounts and roles you have access to
• Create a timestamped backup of ~/.aws/config
• Delete and regenerate ~/.aws/config with discovered profiles
• Generate ~/.padua/padua.config.json

Features

| Category | Feature | Description | |----------|---------|-------------| | Auth | SSO Login | AWS SSO authentication and session management | | | Profiles | Interactive AWS profile selection with shell integration | | | CodeArtifact | Automatic npm registry authentication | | | ECR | Docker registry authentication | | Config | Init | Automatic SSO discovery and profile generation with backup | | | Status | Health check for all authentication services | | | Doctor | Configuration validation and diagnostics with fuzzy profile matching | | Tunnel | RDS | Secure tunnels to RDS/Aurora databases via SSM | | Exec | ECS | Interactive shell in running ECS containers via SSM | | MCP | Server | Built-in MCP server with 49 GitLab and Atlassian tools | | | Daemon | Background process management via padua login | | | Diagnostics | MCP health checks via padua doctor | | | Migration | Token migration from legacy Go server |

MCP Server

@padua/cli v2 includes a built-in MCP (Model Context Protocol) server that exposes 49 tools and 6 resource templates for GitLab and Atlassian. Any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, etc. — can call these tools directly.

Setup

padua login          # authenticates everything and starts the daemon
padua doctor         # verify the server is healthy

padua login runs a 7-step flow:

| Step | What happens | |------|--------------| | 1. AWS SSO | Authenticate to AWS | | 2. S3 Config | Download MCP provider configuration to ~/.padua/mcp-providers.json | | 3. CodeArtifact | Configure npm registry | | 4. ECR | Configure Docker registry | | 5. GitLab | OAuth2 PKCE authentication | | 6. Atlassian | OAuth2 confidential client authentication | | 7. MCP Daemon | Start background HTTP server on port 8919 |

Steps 5-7 are non-blocking — if a provider fails, the rest of Padua still works.

Architecture

┌─────────────────┐    HTTP POST     ┌──────────────────────┐
│  Claude Code /  │ ──────────────→  │  Padua MCP Daemon    │
│  Claude Desktop │  Bearer token    │  127.0.0.1:8919/mcp  │
│  Cursor / etc.  │ ←────────────── │                      │
└─────────────────┘    JSON-RPC      │  ┌────────────────┐  │
                                     │  │ GitLab (OAuth)  │  │
                                     │  │ 30 tools        │  │
                                     │  └────────────────┘  │
                                     │  ┌────────────────┐  │
                                     │  │ Atlassian (OAuth│) │
                                     │  │ 19 tools        │  │
                                     │  └────────────────┘  │
                                     └──────────────────────┘

• Transport: HTTP with Streamable HTTP transport at POST /mcp
• Auth: Authorization: Bearer padua-mcp-local (fixed token — the server only binds to localhost)
• Tokens: OAuth tokens persisted to ~/.padua/tokens.db (AES-256-GCM encrypted), proactively refreshed before expiry and lazily refreshed on tool calls
• Sessions: Multi-session support — multiple Claude Code instances share the daemon concurrently, each with an independent session. Stale sessions are swept after 30 minutes, max 10 concurrent sessions with LRU eviction

IDE Configuration

Claude Code (~/.claude/settings.json)

Claude Code discovers MCP servers from its settings file. Add the padua server:

{
  "mcpServers": {
    "padua": {
      "type": "url",
      "url": "http://127.0.0.1:8919/mcp",
      "headers": {
        "Authorization": "Bearer padua-mcp-local"
      }
    }
  }
}

After adding the config, restart Claude Code or run /mcp to verify the server is connected.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "padua": {
      "url": "http://127.0.0.1:8919/mcp",
      "headers": {
        "Authorization": "Bearer padua-mcp-local"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "padua": {
      "url": "http://127.0.0.1:8919/mcp",
      "headers": {
        "Authorization": "Bearer padua-mcp-local"
      }
    }
  }
}

Windsurf (~/.windsurf/mcp.json)

{
  "mcpServers": {
    "padua": {
      "serverUrl": "http://127.0.0.1:8919/mcp",
      "headers": {
        "Authorization": "Bearer padua-mcp-local"
      }
    }
  }
}

Any MCP Client (manual HTTP)

curl -X POST http://127.0.0.1:8919/mcp \
  -H "Authorization: Bearer padua-mcp-local" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tool Reference

GitLab — Repository (10 tools)

| Tool | Description | |------|-------------| | gitlab_list_projects | List projects accessible to the authenticated user | | gitlab_get_project | Get project metadata by ID | | gitlab_get_file | Get file content from a repository | | gitlab_create_file | Create a new file in a repository | | gitlab_update_file | Update an existing file in a repository | | gitlab_list_branches | List branches in a project | | gitlab_get_branch | Get a single branch by name | | gitlab_search_code | Search for code across projects | | gitlab_get_repository_tree | List files and directories in a repository tree | | gitlab_get_clone_urls | Get clone URLs (SSH and HTTPS) for a project |

GitLab — Issues (4 tools)

| Tool | Description | |------|-------------| | gitlab_list_issues | List issues with filtering (project, state, labels, assignee) | | gitlab_get_issue | Get a single issue by IID | | gitlab_create_issue | Create a new issue | | gitlab_update_issue | Update an existing issue (title, description, labels, state) |

GitLab — Merge Requests (11 tools)

| Tool | Description | |------|-------------| | gitlab_list_merge_requests | List merge requests with filtering | | gitlab_get_merge_request | Get a single merge request by IID | | gitlab_create_merge_request | Create a new merge request | | gitlab_update_merge_request | Update MR title, description, labels, assignees | | gitlab_get_merge_request_diffs | Get the diff/changes in a merge request | | gitlab_list_merge_request_notes | List comments on a merge request | | gitlab_create_merge_request_note | Add a comment to a merge request | | gitlab_get_merge_request_approvals | Get approval status and required approvers | | gitlab_approve_merge_request | Approve a merge request | | gitlab_merge_merge_request | Merge a merge request | | gitlab_rebase_merge_request | Rebase a merge request onto its target branch |

GitLab — Pipelines (5 tools)

| Tool | Description | |------|-------------| | gitlab_list_pipelines | List CI/CD pipelines for a project | | gitlab_get_pipeline | Get pipeline details (status, duration, stages) | | gitlab_list_pipeline_jobs | List jobs within a pipeline | | gitlab_get_job_log | Get the log output of a CI/CD job | | gitlab_retry_pipeline | Retry a failed pipeline |

Atlassian — Jira (11 tools)

| Tool | Description | |------|-------------| | atlassian_jira_search | Search issues using JQL | | atlassian_jira_get_issue | Get a single issue by key (e.g., PROJ-123) | | atlassian_jira_create_issue | Create a new issue (Bug, Story, Task, Epic, etc.) | | atlassian_jira_update_issue | Update issue fields (summary, description, labels, etc.) | | atlassian_jira_link_issues | Create a link between two issues (Blocks, Relates, etc.) | | atlassian_jira_add_comment | Add a comment to an issue (supports Markdown) | | atlassian_jira_transition_issue | Move an issue to a new status | | atlassian_jira_list_projects | List accessible Jira projects | | atlassian_jira_add_worklog | Log time spent on an issue | | atlassian_jira_get_transitions | Get available transitions for an issue | | atlassian_jira_get_issue_types | Get available issue types for a project |

Atlassian — Confluence (8 tools)

| Tool | Description | |------|-------------| | atlassian_confluence_search | Search Confluence using CQL | | atlassian_confluence_get_page | Get page content by ID | | atlassian_confluence_create_page | Create a new page in a space | | atlassian_confluence_update_page | Update an existing page | | atlassian_confluence_delete_page | Delete a page | | atlassian_confluence_list_spaces | List accessible Confluence spaces | | atlassian_confluence_get_space | Get space details by key | | atlassian_confluence_search_content | Search page content |

Resource Templates

Resources provide direct read access to specific entities by URI:

| URI Template | Description | |--------------|-------------| | gitlab://project/{projectId} | GitLab project metadata | | gitlab://project/{projectId}/file/{filePath} | File content from a GitLab repository | | atlassian://jira/issue/{issueKey} | Jira issue details | | atlassian://jira/project/{projectKey} | Jira project details | | atlassian://confluence/page/{pageId} | Confluence page content | | atlassian://confluence/space/{spaceKey} | Confluence space details |

Server Endpoints

| Endpoint | Method | Auth | Description | |----------|--------|------|-------------| | /mcp | POST | Required | MCP protocol (JSON-RPC over Streamable HTTP) | | /health | GET | Not required | Health check and provider status |

Health check:

curl http://127.0.0.1:8919/health

Returns:

{
  "healthy": true,
  "status": "ok",
  "providers": {
    "gitlab": "ready",
    "atlassian": "ready"
  },
  "uptime": 3600,
  "version": "2.0.23"
}

Daemon Files

| File | Purpose | |------|---------| | ~/.padua/mcp-auth.json | Bearer token, port, PID, start time | | ~/.padua/mcp-server.pid | Daemon process ID | | ~/.padua/mcp-providers.json | Provider configuration (downloaded from S3) | | ~/.padua/tokens.db | Encrypted OAuth tokens (AES-256-GCM) | | ~/.padua/encryption.key | Auto-generated encryption key | | ~/Library/Logs/padua-mcp/server.log | Daemon log (macOS) — upstream API calls, tool errors, token refresh | | ~/.local/share/padua/logs/server.log | Daemon log (Linux) |

Diagnostics

padua doctor

MCP-specific checks:

• Node.js version (>= 20.0.0)
• MCP provider configuration
• Token store integrity
• Encryption key availability
• Port availability
• Daemon health
• GitLab and Atlassian API connectivity

Token Migration

If upgrading from the standalone padua-mcp Go server:

padua doctor --migrate-tokens

Troubleshooting

| Issue | Solution | |-------|----------| | Daemon not starting | Run padua doctor for diagnostics | | Port 8919 in use | padua login auto-kills orphaned processes; or set mcp.port in ~/.padua/padua.config.json | | Token issues | Delete ~/.padua/tokens.db and ~/.padua/encryption.key, then run padua login | | Legacy daemon running | pkill -f padua-mcp-daemon | | Tools not appearing | Verify padua login completed steps 5-7; check padua doctor for provider status | | 401 Unauthorized | Ensure your IDE config includes the Authorization: Bearer padua-mcp-local header; check daemon log for upstream API errors | | Debugging API errors | Check ~/Library/Logs/padua-mcp/server.log (macOS) or ~/.local/share/padua/logs/server.log (Linux). Set PADUA_MCP_LOG_LEVEL=debug for verbose output | | MCP reconnection fails | Upgrade to v2.0.15+ — the daemon now handles ungraceful disconnects automatically |

Downgrade to 1.x

npm install -g @padua/cli@1
pkill -f padua-mcp-daemon

Init Command

Interactive configuration wizard that discovers all AWS accounts and roles via SSO, then generates AWS CLI profiles.

Basic Usage

padua init                      # Standard initialization
padua init --keep-existing      # Preserve custom non-Padua profiles
padua init --force              # Skip confirmation prompts

Options

| Flag | Description | |------|-------------| | --force | Overwrite existing config without prompting | | --keep-existing | Preserve non-Padua profiles in ~/.aws/config | | --no-browser | Don't auto-open browser for SSO authentication | | -v, --verbose | Show detailed progress information | | --no-color | Disable colored output |

Note: --force and --keep-existing are mutually exclusive.

What It Does

1. Prerequisite Check - Validates required tools are installed (AWS CLI v2, npm, Docker, Session Manager Plugin)
2. Environment Variable Detection - Warns if AWS environment variables are set that may interfere with SSO
3. SSO Authentication - Authenticates with AWS SSO or reuses cached token
4. Account Discovery - Discovers all AWS accounts and roles available via SSO
5. Role Selection - Prompts user to select which role to use for profiles
6. Backup Creation - Creates timestamped backup of existing ~/.aws/config
7. Config Generation - Deletes old config and generates fresh profiles
8. Profile Preservation - Optionally merges back custom non-Padua profiles

Backup Behavior

• Location: ~/.aws/config.backup.YYYYMMDD-HHMMSS
• Auto-cleanup: Keeps last 5 backups, removes older ones automatically
• Restoration: cp ~/.aws/config.backup.* ~/.aws/config

Profile Preservation

By default, padua init deletes all existing profiles to ensure a clean state. Use --keep-existing to preserve custom profiles:

padua init --keep-existing

How it works:

• Identifies Padua-managed profiles by sso_session = padua reference
• Preserves all other profiles (custom configurations)
• Merges custom profiles back after generating Padua profiles

Environment Variable Warnings

If AWS environment variables are detected, you'll see:

WARNING: AWS environment variables detected
The following environment variables may interfere with SSO authentication:
  AWS_PROFILE=development
  AWS_DEFAULT_REGION=us-east-1

To unset (bash/zsh):
  unset AWS_PROFILE AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_DEFAULT_REGION

Continue anyway? (y/N)

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error or mutually exclusive flags | | 2 | Missing required prerequisites | | 4 | Config write failed |

Troubleshooting

"SSO session 'padua' already exists"

• Run with --force flag to overwrite

Environment variables interfering

• Unset AWS variables before running init:

  unset AWS_PROFILE AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_DEFAULT_REGION

Lost custom profiles

• Check backup: ls -la ~/.aws/config.backup.*
• Restore backup: cp ~/.aws/config.backup.20260128-143055 ~/.aws/config
• Or run padua init --keep-existing to preserve custom profiles

Login Command

Authenticate to AWS SSO, CodeArtifact (npm), and ECR (Docker) with a single command.

Automatically reads AWS_PROFILE environment variable when no --profile flag is provided (works with paws).

Basic Usage

padua login                    # Full login (SSO + CodeArtifact + ECR)
padua login --profile staging  # Use specific AWS profile
padua login --sso-only         # SSO only, skip CodeArtifact and ECR

Options

| Flag | Description | |------|-------------| | -p, --profile <name> | AWS SSO profile to use | | --sso-only | Only authenticate to SSO | | --local | Write CodeArtifact config to project .npmrc instead of global ~/.npmrc | | -v, --verbose | Show detailed output | | -q, --quiet | Suppress non-error output | | --no-color | Disable colored output |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success (SSO + at least one other service) | | 1 | SSO succeeded but CodeArtifact and ECR both failed | | 2 | SSO failed (other services not attempted) |

What padua login replaces

# Before: 3 separate commands
aws sso login --profile development
aws codeartifact login --tool npm --repository npm-repo --domain my-domain \
  --domain-owner 123456789012 --region ap-southeast-2 --profile development
aws ecr get-login-password --region ap-southeast-2 | \
  docker login --username AWS --password-stdin 123456789012.dkr.ecr.ap-southeast-2.amazonaws.com

# After: 1 command
padua login

Example Output

[1/7] AWS SSO ...
      ✓ authenticated (profile: paduafg-development)
[2/7] S3 Config ...
      ✓ downloaded
[3/7] CodeArtifact (npm) ...
      ✓ configured
[4/7] ECR (Docker) ...
      ✓ configured
[5/7] GitLab Auth ...
      ✓ authenticated
[6/7] Atlassian Auth ...
      ✓ authenticated
[7/7] MCP Daemon ...
      ✓ running (http://127.0.0.1:8919/mcp)

=== Login Results ===
SSO: ✓ OK
S3 Config: ✓ OK
CodeArtifact: ✓ OK
ECR: ✓ OK
GitLab: ✓ OK
Atlassian: ✓ OK
MCP Daemon: ✓ OK

Total: 7/7 services authenticated

Configuration

Configuration is stored in ~/.padua/padua.config.json (created by padua init):

{
  "defaultProfile": "development",
  "region": "ap-southeast-2",
  "codeartifact": {
    "domain": "my-domain",
    "domainOwner": "123456789012",
    "repository": "npm-repo"
  },
  "ecr": {
    "accountId": "123456789012",
    "region": "ap-southeast-2"
  }
}

Profile Resolution Priority

1. CLI flags (--profile)
2. PADUA_PROFILE environment variable
3. AWS_PROFILE environment variable
4. defaultProfile in config file
5. 'default'

This means padua status automatically uses the profile set by paws or export AWS_PROFILE=....

Status Command

Check authentication status for all configured services with detailed AWS identity information.

Automatically reads AWS_PROFILE environment variable when no --profile flag is provided (works with paws).

Basic Usage

padua status                     # Check all services
padua status -p staging          # Check with specific profile
padua status -q                  # Quiet mode (exit code only)

Options

| Flag | Description | |------|-------------| | -p, --profile <name> | AWS profile to check | | -q, --quiet | Only output if there are issues | | --no-color | Disable colored output |

Example Output

AWS SSO
  Status:  Authenticated
  Profile: paduafg-development
  Account: 361485743373 (development)
  Region:  ap-southeast-2
  Role:    Developers
  User:    [email protected]
  User ID: AROA123456789:[email protected]

CodeArtifact (npm)
  Status:   Authenticated
  Registry: https://paduafg-361485743373.d.codeartifact.ap-southeast-2.amazonaws.com/npm/paduafg/
  Expires:  12/4/2025, 7:30:00 PM (in 11 hours)

ECR (Docker)
  Status:   Authenticated
  Registry: 361485743373.dkr.ecr.ap-southeast-2.amazonaws.com

Exit Codes

| Code | Meaning | |------|---------| | 0 | All services healthy | | 1 | One or more services have issues | | 2 | Configuration not found |

Doctor Command

Validate Padua CLI configuration and diagnose common issues. Helps troubleshoot problems with profiles, authentication, and prerequisites.

Basic Usage

padua doctor                     # Run all diagnostic checks
padua doctor --verbose           # Show detailed diagnostic information

Options

| Flag | Description | |------|-------------| | --fix | Attempt to auto-fix common issues (not yet implemented) | | -v, --verbose | Show detailed diagnostic information | | --no-color | Disable colored output |

Diagnostic Checks

The doctor command performs comprehensive validation:

1. Config Validation - Verifies ~/.padua/padua.config.json exists and contains valid JSON
2. Config Schema - Validates field formats (account IDs, regions, domains, repositories)
3. Profile Validation - Checks if defaultProfile exists in ~/.aws/config, suggests corrections for typos
4. Prerequisites - Checks AWS CLI, npm, Docker, Session Manager Plugin installation status and versions
5. Authentication - Validates SSO, CodeArtifact, and ECR authentication status
6. Installation - Compares current CLI version with latest published version on npm
7. MCP Server - Node.js version (>= 20.0.0), MCP provider config, token store integrity, encryption key, port availability, daemon health, GitLab and Atlassian API connectivity

Use --migrate-tokens to migrate encrypted tokens from a legacy padua-mcp Go server database.

Example Output

🏥 Padua CLI Doctor

Config Validation
  [✓] Config file: Found at ~/.padua/padua.config.json
  [✓] Config schema: All fields valid
  [✗] Default profile 'development' not found in ~/.aws/config
      → Did you mean 'paduafg-development'?

Prerequisites
  [✓] AWS CLI: Installed (2.15.0)
  [✓] npm: Installed (10.9.2)
  [✓] Docker: Installed (29.1.3)
  [⚠] Session Manager Plugin: Not installed
      → Required for tunneling features. Install: https://docs.aws.amazon.com/...

Authentication
  [✓] SSO authentication: Authenticated as [email protected]
  [✓] CodeArtifact authentication: Authenticated (project .npmrc)
  [✓] ECR authentication: Authenticated

Installation
  [⚠] CLI version: Current: 1.10.0, Latest: 1.11.0
      → Update with: npm install -g @padua/cli@latest

Summary: 1 error, 2 warnings

Exit Codes

| Code | Meaning | |------|---------| | 0 | All checks passed | | 1 | Issues or warnings found | | 2 | Config not found or invalid |

Use Cases

Troubleshooting login issues:

# Check why "padua login" fails
padua doctor

Verifying setup after installation:

# Ensure all prerequisites are installed
padua doctor

Finding profile typos:

# Get suggestions for misspelled profile names
padua doctor
# Example: Suggests 'paduafg-development' if you typed 'development'

Profile Command

Interactive AWS profile selection with shell integration.

Basic Usage

padua profile                    # Interactive selection
padua profile --setup            # Output shell function for paws command
padua profile --list-only        # List profiles (for scripts)
padua profile --select-only      # Select and output name only

Options

| Flag | Description | |------|-------------| | --setup | Output shell function for your shell profile | | --list-only | Output profile names only (one per line) | | --select-only | Interactive select, output only the name | | --no-color | Disable colored output |

Shell Integration (paws)

paws is a shell function that switches AWS profiles by setting AWS_PROFILE in your current shell session. All Padua commands (padua login, padua status, padua tunnel) automatically pick up the active profile.

Installation

Run padua profile --setup and append the output to your shell profile:

# Bash
padua profile --setup >> ~/.bashrc && source ~/.bashrc

# Zsh
padua profile --setup >> ~/.zshrc && source ~/.zshrc

# PowerShell
padua profile --setup | Out-File -Append $PROFILE
. $PROFILE

This installs the paws function and tab completion for available profiles.

Usage

paws                        # Interactive profile selection (arrow keys)
paws <profile-name>         # Switch to a specific profile directly
paws clear                  # Unset all AWS environment variables

| Command | Description | |---------|-------------| | paws | Opens an interactive list of available SSO profiles | | paws <name> | Sets AWS_PROFILE to the given profile name | | paws clear | Unsets AWS_PROFILE, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_DEFAULT_REGION, AWS_REGION, and AWS_DEFAULT_PROFILE |

Tab Completion

Tab completion is included automatically with the shell function. Press Tab after typing paws to see available profiles and the clear subcommand.

Example Workflow

# Switch to development profile
paws paduafg-development
# AWS_PROFILE set to: paduafg-development

# Login using the active profile
padua login

# Check status
padua status

# Clear profile when done
paws clear
# AWS environment variables cleared

Tunnel Command

Create secure tunnels to RDS databases via SSM Session Manager.

Automatically reads AWS_PROFILE environment variable when no --profile flag is provided (works with paws).

Basic Usage

padua tunnel roma rds                    # Interactive (prompts for port/cluster)
padua tunnel roma rds -p paduafg-development  # Use specific profile

Options

| Flag | Description | |------|-------------| | -p, --profile <name> | AWS profile to use | | --local-port <port> | Local port for the tunnel | | --cluster <name> | RDS cluster or instance name | | -v, --verbose | Show detailed output | | --no-color | Disable colored output |

System Configuration

Different systems use different EC2 instances as tunnel endpoints:

| System | EC2 Tag | Default Port | Default Cluster | |--------|---------|--------------|-----------------| | roma | bastion-host | 3306 (MySQL) | roma-backend | | (others) | jumpbox | 5432 (PostgreSQL) | (none) |

Example Output

Checking port 3306 availability...
✓ Port 3306 is available
Looking up bastion-host instance...
✓ Found instance: i-0abc123def456
Looking up RDS endpoint for roma-backend...
✓ Found endpoint: roma-backend.cluster-xxx.ap-southeast-2.rds.amazonaws.com

Starting tunnel...
  System: roma
  Profile: paduafg-development
  Local port: 3306
  Remote: roma-backend.cluster-xxx.ap-southeast-2.rds.amazonaws.com:3306
  Via: i-0abc123def456 (bastion-host)

Press Ctrl+C to close the tunnel

Exec Command

Open an interactive shell in a running ECS container via SSM Execute Command.

Basic Usage

padua exec                                    # Interactive (prompts for cluster/service/task/container)
padua exec -c my-cluster -s my-service        # Specify cluster and service
padua exec -c my-cluster -s my-service -t abc123 --container app  # Fully non-interactive

Options

| Flag | Description | |------|-------------| | -p, --profile <name> | AWS profile to use | | -c, --cluster <name> | ECS cluster name | | -s, --service <name> | ECS service name | | -t, --task <id> | ECS task ID | | --container <name> | Container name | | --command <cmd> | Command to run (default: /bin/bash) | | -v, --verbose | Show detailed output | | --no-color | Disable colored output |

Auto-selects when only one option exists at each level (cluster, service, task, container).

Planned Features

The following commands are planned for future releases:

padua tunnel opensearch          # OpenSearch/Kibana dashboard
padua tunnel ec2 <name>          # SSM session to EC2 instance

Development

git clone <repository-url>
cd padua-cli
npm install
npm run build
npm link           # Makes 'padua' available globally
npm test           # Run tests
npm run test:coverage  # Run tests with coverage

License

MIT