Metadata-Version: 2.5
Name: awscx
Version: 0.3.0
Summary: AWS ECS exec / EC2 SSM 접속용 k9s 스타일 터미널 TUI
Project-URL: Homepage, https://github.com/HonamSong/awscx
Project-URL: Repository, https://github.com/HonamSong/awscx
Author-email: louky0714 <louky0714@gmail.com>
License: MIT
Keywords: aws,devops,ec2,ecs,exec,ssm,textual,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: boto3>=1.28
Requires-Dist: pyte>=0.8
Requires-Dist: textual>=0.60
Description-Content-Type: text/markdown

# awscx

![version](https://img.shields.io/badge/version-0.3.0-blue.svg)
![python](https://img.shields.io/badge/python-3.11%2B-blue.svg)
![go](https://img.shields.io/badge/go-1.24%2B-blue.svg)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg)

AWS **ECS exec** / **EC2 SSM** 접속을 위한 k9s 스타일 터미널 TUI.

프로파일을 고르고 → ECS(cluster/service) 또는 EC2(SSM) 를 골라 → 목록에서 바로
셸 접속, 로그(tail·검색·레벨색상), 실시간 모니터(CPU/Mem/Net/Disk), 상태(LB·오토스케일·taskdef)
를 한 화면에서 확인합니다.

## 주요 기능

- Profile 선택(번호 입력 지원) → ECS / EC2 선택
- ECS
  - cluster/service 목록: STATUS / EXEC(on·off) / TASKS / LB(healthy) / SCALE(min~max)
  - `Enter` 상태(서비스 상태·CloudWatch CPU/Mem·TaskDef cpu/mem/port·LB 헬스·오토스케일·이벤트, 색상)
  - `s` 컨테이너 shell 접속(임베드 터미널, 컬러 렌더)
  - `l` 로그 보기 → `/` 검색, `f` tail(follow), 로그레벨 색상
  - `t` task definition(JSON)
  - 목록에서 index 번호 키를 누르면 해당 행으로 커서 이동
  - 서비스에 커서를 두면 우측에 실시간 모니터 자동 표시
- EC2
  - running 인스턴스 목록(SSM online 여부 표시) → `Enter` SSM 세션 접속
- 임베드 터미널(창 안에서 실행): `F10` 나가기, 붙여넣기 지원
  - 셸 출력 스크롤백: `PageUp` / `PageDown` (강제: `Shift`/`Ctrl`+`PageUp`/`PageDown`)
  - 마우스 휠 스크롤은 설정에서 `mouse` 를 켜면 사용 가능(끄면 터미널 네이티브
    드래그 선택/복사가 그대로 동작)
- `g` 설정 화면(config 파일 편집), `c` 결과 클립보드 복사

## 저장소 구조

이 저장소는 모노레포입니다. 두 구현체는 동일한 설정 파일(`~/.config/awscx/config.json`)을
공유합니다.

- python/ — Python (Textual) 구현
  - 설치: pip install awscx
  - 실행: awscxpy
- go/ — Go (bubbletea) 구현, 폐쇄망용 단일 정적 바이너리
  - 빌드: cd go && make build → dist/awscx
  - 실행: awscx

> 두 구현체가 한 호스트에 공존해도 실행 파일 이름이 다르므로 충돌하지 않습니다.
> (Python 판은 pip 패키지명은 `awscx` 그대로지만, CLI 는 `awscxpy` 로 노출)

## 요구사항 (공통 시스템 도구)

- [aws-cli v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
- [session-manager-plugin](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
- macOS / Linux (Windows 미지원 — PTY/termios 사용)
- Python 판: Python >= 3.11
- Go 판: Go >= 1.24 (빌드 시)

## 설치 · 사용

### Python (`awscxpy`)

```bash
pip install awscx
```

```bash
awscxpy                 # 프로파일 목록에서 선택
awscxpy -p my-profile   # 프로파일 지정
awscxpy -p my-profile -r us-east-1
# 또는
python -m awscx
```

### Go (`awscx`)

```bash
cd go
make build          # → dist/awscx
make release        # → dist/awscx-{linux,darwin}-{amd64,arm64}
```

```bash
awscx                         # 프로파일 목록에서 선택 (TUI)
awscx -p my-profile           # 프로파일 지정
awscx -p my-profile -r us-east-1
awscx --no-tui                # bubbletea 대신 stdin 프롬프트 폴백

# 스크립트 용도 서브커맨드 (TUI 없이)
awscx -p my-profile clusters
awscx -p my-profile services <cluster>
awscx -p my-profile ec2
```

주요 키: `Enter` 상태 · `s` 접속 · `l` 로그 · `f` tail · `t` taskdef · 모니터(자동
표시) · `p` 프로파일 · `g` 설정 · `c` 복사 · `/` 필터 · `Ctrl+U/D` 결과 스크롤 ·
`q` 종료

셸 세션 안에서(Python 판 임베드 터미널): `PageUp`/`PageDown` 스크롤 · `F10` 세션 나가기

## 설정 파일

`~/.config/awscx/config.json` 에 자동 생성됩니다(region, command, 로그, 갱신주기 등).
Python / Go 판이 같은 파일을 공유하므로 한쪽에서 편집한 값이 다른 쪽에도 반영됩니다.
앱 안에서 `g` 로 편집할 수 있습니다.

## 권한 (IAM)

기능에 따라 다음 권한이 필요합니다: `ecs:*`(조회/execute-command), `ec2:DescribeInstances`,
`ssm:DescribeInstanceInformation`, `ssm:StartSession`, `cloudwatch:GetMetricStatistics`,
`logs:FilterLogEvents`, `elasticloadbalancing:Describe*`,
`application-autoscaling:Describe*`.

Go 판은 추가로 VPC / Secrets Manager / Route 53 조회 기능을 제공하며, 해당 화면에서만
`ec2:DescribeVpcs`·`DescribeSubnets`·`DescribeNatGateways`, `secretsmanager:*`,
`route53:List*` 권한을 사용합니다.

## License

MIT