@ait-co/console-cli 0.1.37 → 0.1.39

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,7 +105,7 @@ 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.
 
@@ -113,40 +113,27 @@ The CLI looks for Chrome in the standard OS install locations (Google Chrome, Ch
 
 ## Using aitcc in SSH / headless environments
 
-macOS Keychain access is blocked in SSH remote sessions and GUI-less servers, so `--save keychain` will fail there. Three workarounds are available:
-
-**Option 1 — Export / import the session (recommended, requires a KR IP)**
-
-Export the session on a desktop GUI Mac and inject it into the SSH environment:
+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
-# On a desktop Mac 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
+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
 ```
 
-**Option 2 — Unlock the keychain**
+Override the path with the `AITCC_CREDENTIAL_FILE` environment variable.
 
-Unlock the keychain in the same SSH session, then retry:
+**Session export / import (requires a KR IP)**
 
-```sh
-security unlock-keychain ~/Library/Keychains/login.keychain-db
-# (enter login password when prompted)
-aitcc login --save keychain --email you@example.com --password-stdin
-```
-
-**Option 3 — File backend**
-
-Store credentials in a plain file instead of the keychain. Assumes a single-user machine; FileVault (full-disk encryption) is strongly recommended:
+You can also export a session from a desktop machine and inject it into the SSH environment:
 
 ```sh
-aitcc login --save=file --email you@example.com --password-stdin
-# → stored in ~/.config/aitcc/credentials.json (perm 0600)
-```
+# On a desktop that is already logged in:
+aitcc auth export --format env   # outputs: AITCC_SESSION=...
 
-After saving, subsequent `aitcc login` runs in the SSH environment will read this file and sign in headlessly. Override the path with the `AITCC_CREDENTIAL_FILE` environment variable. See [issue #176](https://github.com/apps-in-toss-community/console-cli/issues/176) for background.
+# In the SSH environment:
+AITCC_SESSION='...' aitcc app deploy ./bundle.ait --json
+```
 
 ## Session storage
 
@@ -157,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
 
@@ -236,6 +223,28 @@ The following command groups are implemented end-to-end:
 
 `app logs` is deferred until the backend endpoint is available. See the [organization landing page](https://aitc.dev/) for the full roadmap.
 
+## Issuing a Deploy Key
+
+Issue a workspace-scoped credential (Deploy Key) for deploy automation:
+
+```sh
+aitcc keys create --name ci-deploy
+```
+
+The key is automatically saved to `~/.ait/credentials` under the `ci-deploy` profile as soon as it is issued — no separate `ait token add` step required:
+
+```sh
+ait deploy --profile ci-deploy ./bundle.ait
+```
+
+Only the plaintext key is written to stdout (pipe-friendly). stderr confirms which profile was saved. If you are piping the key into an external secret manager and do not need a local profile, pass `--no-save-profile`:
+
+```sh
+aitcc keys create --name ci-deploy --no-save-profile | secret-tool store --label=… key password
+```
+
+To save the profile under a different name than `--name`, pass `--save-profile <other-name>`. The plaintext key is exposed once at issuance and cannot be retrieved later — if you lose it, revoke it with `aitcc keys revoke <id>` and issue a new one.
+
 ## Pre-commit hook
 
 Optional but recommended. After cloning, activate the standard pre-commit hook (runs `biome check` on staged files):

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,7 +105,7 @@ 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에서 제거됩니다.
 
@@ -113,40 +113,27 @@ CLI는 OS 표준 위치(Google Chrome, Chromium, Microsoft Edge)에서 Chrome을
 
 ## SSH / headless 환경에서 로그인
 
-SSH 원격 세션이나 GUI가 없는 서버에서는 macOS Keychain 접근이 막혀 `--save keychain`이 실패할 수 있습니다. 세 가지 우회 방법이 있습니다:
-
-**방법 1 — 세션 export/import (권장, KR IP 필요)**
-
-Desktop GUI Mac에서 세션을 export해 SSH 환경에 주입합니다:
+SSH 원격 세션이나 GUI가 없는 서버에서도 자격증명 저장이 동작합니다. 자격증명은 `~/.config/aitcc/credentials.json` (perm 0600)에 저장되며 SSH/CI 환경에서도 동일하게 작동합니다. 평문 저장이므로 디스크 암호화(FileVault, LUKS) 사용을 권장합니다.
 
 ```sh
-# Desktop (GUI Mac, 이미 로그인된 상태):
-aitcc auth export --format env   # → AITCC_SESSION=... 출력
-
-# SSH 환경에서:
-AITCC_SESSION='...' aitcc app deploy ./bundle.ait --json
+aitcc login --save=file --email you@example.com --password-stdin
+# → ~/.config/aitcc/credentials.json (perm 0600)에 저장
+# 이후 SSH 환경에서 aitcc login이 이 파일을 읽어 headless 로그인을 진행합니다.
 ```
 
-**방법 2 — keychain unlock**
+경로를 바꾸려면 `AITCC_CREDENTIAL_FILE` env var를 지정합니다.
 
-같은 SSH 세션에서 keychain을 잠금 해제한 뒤 재시도합니다:
+**세션 export/import (KR IP 필요)**
 
-```sh
-security unlock-keychain ~/Library/Keychains/login.keychain-db
-# (login 비밀번호 입력)
-aitcc login --save keychain --email you@example.com --password-stdin
-```
-
-**방법 3 — 파일 backend**
-
-Keychain 대신 평문 파일에 자격증명을 저장합니다. 단일 사용자 머신 전제이며 FileVault(디스크 암호화) 사용을 권장합니다:
+Desktop에서 세션을 export해 SSH 환경에 주입하는 방법도 있습니다:
 
 ```sh
-aitcc login --save=file --email you@example.com --password-stdin
-# → ~/.config/aitcc/credentials.json (perm 0600)에 저장
-```
+# Desktop (이미 로그인된 상태):
+aitcc auth export --format env   # → AITCC_SESSION=... 출력
 
-저장 후 SSH 환경에서 `aitcc login`이 자동으로 이 파일을 읽어 headless 로그인을 진행합니다. 경로를 바꾸려면 `AITCC_CREDENTIAL_FILE` env var를 지정합니다. 자세한 내용은 [issue #176](https://github.com/apps-in-toss-community/console-cli/issues/176) 참조.
+# SSH 환경에서:
+AITCC_SESSION='...' aitcc app deploy ./bundle.ait --json
+```
 
 ## 세션 저장
 
@@ -157,7 +144,7 @@ aitcc login --save=file --email you@example.com --password-stdin
 
 상위 디렉토리는 mode `0700`으로 생성됩니다. 로그인 중 캡처된 쿠키는 **절대** 출력·로깅되지 않으며 `--verbose`에도 노출되지 않습니다 — `whoami`로 노출되는 건 `user.email`, `name`, workspace 요약뿐입니다.
 
-OS 키체인 대신 plain `0600` 파일을 쓰는 이유는 [CLAUDE.md](./CLAUDE.md) 참조.
+plain `0600` 파일을 쓰는 설계 이유는 [CLAUDE.md](./CLAUDE.md) 참조.
 
 ## CI/CD 통합
 
@@ -236,6 +223,28 @@ aitcc telemetry tier0-on        # Tier 0 다시 활성화
 
 `app logs`는 백엔드 endpoint 확보 후 구현 예정입니다. 전체 로드맵은 [organization landing page](https://aitc.dev/) 참조.
 
+## Deploy Key 발급
+
+배포 자동화를 위한 워크스페이스-scope 자격증명(Deploy Key)을 발급합니다.
+
+```sh
+aitcc keys create --name ci-deploy
+```
+
+키 발급 즉시 `~/.ait/credentials`에 `ci-deploy` 프로파일로 저장되므로, 별도 `ait token add` 단계 없이 바로 사용할 수 있습니다:
+
+```sh
+ait deploy --profile ci-deploy ./bundle.ait
+```
+
+stdout에는 plaintext 키 한 줄만 나옵니다 (파이프 친화적). stderr는 저장된 프로파일 이름을 확인해줍니다. CI 파이프에서 키를 외부 secret manager에 직접 주입할 때처럼 로컬 저장이 필요 없다면 `--no-save-profile`로 저장을 건너뜁니다:
+
+```sh
+aitcc keys create --name ci-deploy --no-save-profile | secret-tool store --label=… key password
+```
+
+프로파일 이름을 `--name`과 다르게 지정하려면 `--save-profile <other-name>`을 사용합니다. plaintext 키는 발급 시 한 번만 노출되며 목록 endpoint에서 다시 확인할 수 없습니다 — 분실 시 `aitcc keys revoke <id>`로 무효화하고 재발급합니다.
+
 ## Pre-commit hook
 
 선택 사항이지만 권장합니다. clone 후 표준 pre-commit hook을 활성화하면 staged 파일에 `biome check`가 자동으로 돕니다 (push 전 빠른 피드백):