@ait-co/console-cli 0.1.36 → 0.1.38

package/README.en.md

@@ -45,7 +45,7 @@ aitcc --version          # print the embedded version
 aitcc login              # interactive: prompts email/password/save target, then signs in
 aitcc login --interactive   # force the visible-browser flow (skip headless)
 aitcc logout             # delete the local session file
-aitcc logout --purge     # also delete saved keychain credentials (replaces `auth clear`)
+aitcc logout --purge     # also delete saved credentials (replaces `auth clear`)
 aitcc whoami             # show the currently logged-in user + credential source
 aitcc whoami --offline   # use the cached identity without hitting the API
 aitcc whoami --json      # machine-readable output for scripts and agents
@@ -62,7 +62,7 @@ printf '%s' "$AITCC_PASSWORD" | aitcc login --email you@example.com --password-s
 AITCC_EMAIL=you@example.com AITCC_PASSWORD=… aitcc login --json
 ```
 
-Add `--save keychain` to persist the credentials so the next `aitcc login` runs without prompting.
+Add `--save file` to persist the credentials to `~/.config/aitcc/credentials.json` so the next `aitcc login` runs without prompting.
 
 `aitcc upgrade` respects `GITHUB_TOKEN` to avoid anonymous GitHub API rate limits.
 
@@ -105,12 +105,36 @@ aitcc app status         # works with no flags — context comes from aitcc.yaml
 
 ### Login details
 
-`aitcc login` resolves credentials from (in order) explicit `--email` + `--password` / `--password-stdin` flags, the `AITCC_EMAIL` + `AITCC_PASSWORD` environment, the OS keychain (saved by a prior `--save keychain`), or — on a TTY — an interactive prompt that asks for both fields plus where to save them. It then launches a Chrome-family browser via the Chrome DevTools Protocol, drives the sign-in headlessly when credentials are available, and waits for the main frame to reach the post-login workspace page. Once it does, the CLI dumps all cookies over CDP (including `HttpOnly` auth cookies that JavaScript can't see) and persists them to the local session file. The browser runs against a temporary, isolated `--user-data-dir` that is wiped on exit, so your everyday browser profile is never touched.
+`aitcc login` resolves credentials from (in order) explicit `--email` + `--password` / `--password-stdin` flags, the `AITCC_EMAIL` + `AITCC_PASSWORD` environment, the file backend (`~/.config/aitcc/credentials.json`, perm 0600), or — on a TTY — an interactive prompt that asks for both fields plus where to save them. It then launches a Chrome-family browser via the Chrome DevTools Protocol, drives the sign-in headlessly when credentials are available, and waits for the main frame to reach the post-login workspace page. Once it does, the CLI dumps all cookies over CDP (including `HttpOnly` auth cookies that JavaScript can't see) and persists them to the local session file. The browser runs against a temporary, isolated `--user-data-dir` that is wiped on exit, so your everyday browser profile is never touched.
 
 Pass `--interactive` to force the visible-browser flow even when credentials are configured (useful for switching accounts or working around step-up auth). The legacy `aitcc auth set` / `auth clear` / `auth status` commands still work but emit a deprecation warning — prefer `aitcc login` (interactive prompt offers a save option), `aitcc logout --purge`, and `aitcc whoami` instead. They will be removed in 1.0.
 
 The CLI looks for Chrome in the standard OS install locations (Google Chrome, Chromium, Microsoft Edge). Override the executable with `AITCC_BROWSER=/path/to/chrome` if your install is elsewhere; override the sign-in URL with `AITCC_OAUTH_URL` if you need to point at a staging environment. `--timeout <seconds>` controls how long the CLI will wait for sign-in to finish (default 300s).
 
+## Using aitcc in SSH / headless environments
+
+Credentials are stored in `~/.config/aitcc/credentials.json` (perm 0600) and work the same way in SSH and GUI-less server environments. Plain-text storage is the same trade-off made by `gh`, `aws-cli`, and `gcloud`; disk encryption (FileVault, LUKS) is recommended.
+
+```sh
+aitcc login --save=file --email you@example.com --password-stdin
+# → stored in ~/.config/aitcc/credentials.json (perm 0600)
+# subsequent aitcc login runs in SSH will read this file and sign in headlessly
+```
+
+Override the path with the `AITCC_CREDENTIAL_FILE` environment variable.
+
+**Session export / import (requires a KR IP)**
+
+You can also export a session from a desktop machine and inject it into the SSH environment:
+
+```sh
+# On a desktop that is already logged in:
+aitcc auth export --format env   # outputs: AITCC_SESSION=...
+
+# In the SSH environment:
+AITCC_SESSION='...' aitcc app deploy ./bundle.ait --json
+```
+
 ## Session storage
 
 The local session lives at an XDG-compliant path with file mode `0600`:
@@ -120,7 +144,7 @@ The local session lives at an XDG-compliant path with file mode `0600`:
 
 The containing directory is created with mode `0700`. Cookies captured during login are **never** printed, logged, or attached to `--verbose` output — only `user.email`, `name`, and workspace summary surface through `whoami`.
 
-See [CLAUDE.md](./CLAUDE.md) for the rationale behind using a plain `0600` file instead of an OS keychain.
+See [CLAUDE.md](./CLAUDE.md) for the design rationale behind using a plain `0600` file.
 
 ## Continuous integration
 

package/README.md

@@ -45,7 +45,7 @@ aitcc --version          # 임베드된 버전 출력
 aitcc login              # 인터랙티브: 이메일/비밀번호/저장 위치를 묻고 로그인
 aitcc login --interactive   # headless 대신 visible-browser 강제
 aitcc logout             # 로컬 세션 파일 삭제
-aitcc logout --purge     # 저장된 키체인 자격증명도 함께 삭제 (`auth clear` 대체)
+aitcc logout --purge     # 저장된 자격증명도 함께 삭제 (`auth clear` 대체)
 aitcc whoami             # 현재 로그인된 사용자 + 자격증명 출처 표시
 aitcc whoami --offline   # API 호출 없이 캐시된 identity 사용
 aitcc whoami --json      # 스크립트·에이전트용 machine-readable 출력
@@ -62,7 +62,7 @@ printf '%s' "$AITCC_PASSWORD" | aitcc login --email you@example.com --password-s
 AITCC_EMAIL=you@example.com AITCC_PASSWORD=… aitcc login --json
 ```
 
-`--save keychain`을 붙이면 자격증명이 저장돼 다음 `aitcc login`이 prompt 없이 실행됩니다.
+`--save file`을 붙이면 자격증명이 `~/.config/aitcc/credentials.json`에 저장돼 다음 `aitcc login`이 prompt 없이 실행됩니다.
 
 `aitcc upgrade`는 GitHub API anonymous rate limit을 피하려고 `GITHUB_TOKEN`을 존중합니다.
 
@@ -105,12 +105,36 @@ aitcc app status         # 플래그 없이 동작 — aitcc.yaml에서 컨텍
 
 ### 로그인 동작
 
-`aitcc login`은 자격증명을 다음 순서로 찾습니다: `--email` + `--password` / `--password-stdin` 플래그 → `AITCC_EMAIL` + `AITCC_PASSWORD` 환경 변수 → OS 키체인(이전 `--save keychain`으로 저장) → (TTY 환경에서만) 인터랙티브 prompt. 자격증명을 확보하면 Chrome DevTools Protocol로 Chrome 계열 브라우저를 띄워 가능하면 headless로 로그인을 진행하고, main frame이 로그인 후 workspace 페이지에 도달할 때까지 기다립니다. 도달하면 CDP로 모든 쿠키(JS로는 못 보는 `HttpOnly` 인증 쿠키 포함)를 덤프해 로컬 세션 파일에 저장합니다. 브라우저는 종료 시 삭제되는 임시 `--user-data-dir`에서 실행되므로 일상 브라우저 프로필은 절대 건드리지 않습니다.
+`aitcc login`은 자격증명을 다음 순서로 찾습니다: `--email` + `--password` / `--password-stdin` 플래그 → `AITCC_EMAIL` + `AITCC_PASSWORD` 환경 변수 → 파일 backend(`~/.config/aitcc/credentials.json`) → (TTY 환경에서만) 인터랙티브 prompt. 자격증명을 확보하면 Chrome DevTools Protocol로 Chrome 계열 브라우저를 띄워 가능하면 headless로 로그인을 진행하고, main frame이 로그인 후 workspace 페이지에 도달할 때까지 기다립니다. 도달하면 CDP로 모든 쿠키(JS로는 못 보는 `HttpOnly` 인증 쿠키 포함)를 덤프해 로컬 세션 파일에 저장합니다. 브라우저는 종료 시 삭제되는 임시 `--user-data-dir`에서 실행되므로 일상 브라우저 프로필은 절대 건드리지 않습니다.
 
 자격증명이 설정돼 있어도 visible-browser flow를 강제하려면 `--interactive`를 사용합니다 (계정 전환, step-up 인증 우회). 레거시 `aitcc auth set` / `auth clear` / `auth status`는 여전히 동작하지만 deprecation 경고를 emit합니다 — `aitcc login`(인터랙티브 prompt가 저장 옵션 제공), `aitcc logout --purge`, `aitcc whoami`를 사용하세요. 1.0에서 제거됩니다.
 
 CLI는 OS 표준 위치(Google Chrome, Chromium, Microsoft Edge)에서 Chrome을 찾습니다. 다른 곳에 설치돼 있으면 `AITCC_BROWSER=/path/to/chrome`으로 실행 파일을 지정하고, 스테이징 환경을 가리키려면 `AITCC_OAUTH_URL`로 로그인 URL을 override합니다. `--timeout <초>`로 로그인 대기 시간을 조절합니다 (기본 300초).
 
+## SSH / headless 환경에서 로그인
+
+SSH 원격 세션이나 GUI가 없는 서버에서도 자격증명 저장이 동작합니다. 자격증명은 `~/.config/aitcc/credentials.json` (perm 0600)에 저장되며 SSH/CI 환경에서도 동일하게 작동합니다. 평문 저장이므로 디스크 암호화(FileVault, LUKS) 사용을 권장합니다.
+
+```sh
+aitcc login --save=file --email you@example.com --password-stdin
+# → ~/.config/aitcc/credentials.json (perm 0600)에 저장
+# 이후 SSH 환경에서 aitcc login이 이 파일을 읽어 headless 로그인을 진행합니다.
+```
+
+경로를 바꾸려면 `AITCC_CREDENTIAL_FILE` env var를 지정합니다.
+
+**세션 export/import (KR IP 필요)**
+
+Desktop에서 세션을 export해 SSH 환경에 주입하는 방법도 있습니다:
+
+```sh
+# Desktop (이미 로그인된 상태):
+aitcc auth export --format env   # → AITCC_SESSION=... 출력
+
+# SSH 환경에서:
+AITCC_SESSION='...' aitcc app deploy ./bundle.ait --json
+```
+
 ## 세션 저장
 
 로컬 세션은 XDG 규약 경로에 mode `0600`으로 저장됩니다:
@@ -120,7 +144,7 @@ CLI는 OS 표준 위치(Google Chrome, Chromium, Microsoft Edge)에서 Chrome을
 
 상위 디렉토리는 mode `0700`으로 생성됩니다. 로그인 중 캡처된 쿠키는 **절대** 출력·로깅되지 않으며 `--verbose`에도 노출되지 않습니다 — `whoami`로 노출되는 건 `user.email`, `name`, workspace 요약뿐입니다.
 
-OS 키체인 대신 plain `0600` 파일을 쓰는 이유는 [CLAUDE.md](./CLAUDE.md) 참조.
+plain `0600` 파일을 쓰는 설계 이유는 [CLAUDE.md](./CLAUDE.md) 참조.
 
 ## CI/CD 통합