# keenauth login으로 로그인하기

`keenauth login`은 대시보드 계정으로 로그인하므로 API 키를 만들지 않고도 터미널에서 환경을 관리할 수 있습니다. CI 작업이나 스크립트에서는 `KEENAUTH_API_KEY`에 API 키를 계속 사용하십시오([명령줄 인터페이스](/docs/cli) 참조).

## 명령

| 명령 | 기능 |
|---|---|
| `keenauth login` | 기기 흐름으로 로그인합니다. CLI가 주소와 코드를 출력하면, 어떤 기기에서든 해당 주소를 열고 대시보드에 로그인한 뒤 코드를 입력하십시오. |
| `keenauth login --web` | 이 컴퓨터의 브라우저에서 로그인합니다. CLI가 로그인 페이지를 열고 `http://127.0.0.1:<port>/callback`(또는 `http://[::1]:<port>/callback`)에서 결과를 받습니다. 요청은 PKCE(S256), `state`, `iss` 매개변수로 보호됩니다. |
| `keenauth whoami` | 로그인한 사용자, 조직, 선택된 환경을 표시합니다. |
| `keenauth env use <environment_id>` | 이후 명령이 관리할 환경을 선택합니다. 컨트롤 플레인이 해당 환경에 대한 대시보드 역할이 있는지 확인합니다. |
| `keenauth env list` | 컨트롤 플레인에서 작업할 수 있는 환경 목록을 표시합니다. `env use`로 선택한 환경에는 `*` 표시가 붙습니다. |
| `keenauth logout` | 서버에서 세션을 취소하고 이 컴퓨터에서 세션을 삭제합니다. |

```sh
keenauth login
keenauth env use env_01j9z3c0000000000000000000
keenauth users list
```

`KEENAUTH_API_KEY`가 설정되어 있으면 항상 우선 적용됩니다. 저장된 세션은 API 키가 설정되지 않은 경우에만 사용됩니다.

## 환경 목록 조회

`keenauth env list`는 로그인한 계정 중 대시보드 역할이 있는 환경의 목록을 컨트롤 플레인에 요청합니다(`GET /v1/environments`, [CLI용 환경 목록 조회](/docs/api/control/environments/list) 참조). 이 명령에는 세션이 필요하며, 세션이 없으면 `keenauth login`을 실행하라는 메시지가 표시됩니다.

| 플래그 | 설명 |
|---|---|
| `--limit` | 페이지 크기입니다. 1에서 100 사이이며 기본값은 20입니다. |
| `--after` | 이전 페이지에서 출력된 커서입니다(`more results: --after <cursor>`). |
| `--all` | 모든 페이지를 순서대로 가져와 모든 환경을 표시합니다. |
| `-o table\|json\|yaml` | 출력 형식입니다. 표에서는 선택된 환경에 `*`가 표시되며, JSON과 YAML에서는 해당 행에 `current: true`가 포함됩니다. |

잘못되었거나 다른 곳에서 발급된 `--after` 커서는 거부됩니다(`invalid_cursor`). 이 경우 커서를 빼고 명령을 다시 실행하십시오.

## 세션 작동 방식

- 로그인하면 수명이 짧은 액세스 토큰(5분)과 리프레시 토큰(12시간)이 발급됩니다. 두 토큰은 이 컴퓨터에서 생성된 DPoP 키(RFC 9449)에 바인딩되므로, 복사된 토큰은 다른 기기에서 사용할 수 없습니다. 리프레시 토큰은 사용할 때마다 교체됩니다.
- 명령을 실행할 때마다 CLI는 선택된 환경의 관리 토큰을 컨트롤 플레인에 요청합니다. 이 토큰의 수명은 10분이며 같은 DPoP 키에 바인딩됩니다. 관리 토큰은 **메모리에만** 보관되고 디스크에 기록되지 않습니다.
- 환경에 대한 요청에는 관리 토큰, 새로 생성된 DPoP 증명, 대시보드 신원이 함께 전송됩니다. 환경은 사용자가 여전히 역할을 가지고 있는지 확인하므로, 대시보드 역할을 제거하면 몇 분 안에 CLI 접근도 중단됩니다.

## 세션 저장 위치

| 항목 | 위치 |
|---|---|
| 발급자, 사용자 ID, 조직, DPoP 키 지문, 선택된 환경 | `KEENAUTH_CONFIG_DIR`의 `config.json`, 또는 사용자 설정 디렉터리의 `keenauth`(권한 0600) |
| 리프레시 토큰과 DPoP 개인 키 | OS 키체인: macOS 키체인(`security`) 또는 Linux의 Secret Service(`secret-tool`) |

비밀 값은 명령 인수가 아니라 표준 입력을 통해 키체인 도구에 전달됩니다. 키체인을 사용할 수 없으면(예: Windows 또는 Secret Service가 없는 Linux 서버), `keenauth login`은 오류와 함께 중단됩니다. 이 경우 `--insecure-storage`를 전달하면 리프레시 토큰과 DPoP 개인 키를 `config.json` 옆의 `credentials.json`(권한 0600)에 암호화하지 않고 저장할 수 있습니다. CLI는 경고를 출력합니다. 이 파일을 읽을 수 있는 사람은 세션이 만료될 때까지 사용자를 대신해 행동할 수 있습니다. 공유 기기에서는 API 키를 사용하는 것이 좋습니다.

## 설정

| 변수 | 기본값 | 설명 |
|---|---|---|
| `KEENAUTH_LOGIN_ISSUER` | `https://login.keenauth.com` | 로그인 서버입니다. `https` 주소여야 합니다. |
| `KEENAUTH_CONTROL_URL` | `https://api.keenauth.com/v1` | 관리 토큰을 발급하는 컨트롤 플레인입니다. `https` 주소여야 합니다. |
| `KEENAUTH_CONFIG_DIR` | 사용자 설정 디렉터리 + `keenauth` | `config.json`(및 `--insecure-storage` 사용 시 `credentials.json`)을 보관하는 위치입니다. |

## 오류

| 메시지 | 조치 방법 |
|---|---|
| `you are not signed in` / `your session has expired or was revoked` | `keenauth login`을 다시 실행하십시오. 종료 코드 3. |
| `no environment is selected` | `keenauth env use <environment_id>`를 실행하십시오. |
| `environment … does not exist or you have no dashboard role in it` | 대시보드에서 ID를 확인하거나 소유자에게 역할을 요청하십시오. |
| `no OS keychain is available` | 키체인을 설치하거나, `--insecure-storage`를 사용하거나, API 키를 사용하십시오. |