# 명령줄 인터페이스

`keenauth` 명령줄 인터페이스(CLI)는 터미널이나 스크립트에서 관리 API를 호출합니다. 모든 명령은 Go SDK의 타입이 지정된 메서드 하나를 감싸므로, CLI와 API는 동일하게 동작합니다. 아직 설치 패키지는 제공되지 않습니다.

## 인증과 대상

CLI는 자격 증명을 환경 변수에서만 읽습니다. API 키는 플래그로 받지 않으므로 셸 기록에 남지 않습니다.

| 변수 | 필수 여부 | 설명 |
|---|---|---|
| `KEENAUTH_API_KEY` | 예 | 관리 API 키. 없으면 명령이 코드 3으로 종료됩니다. |
| `KEENAUTH_BASE_URL` | 예, `--base-url`를 지정하지 않은 경우 | 환경의 관리 API 기본 URL입니다. |

API 키 대신 대시보드 계정으로 로그인할 수도 있습니다: `keenauth login`, 그다음 `keenauth env use <environment_id>`. 세션은 `KEENAUTH_API_KEY`가 설정되지 않은 경우에만 사용되며, 이때 환경 주소는 컨트롤 플레인에서 가져옵니다([keenauth login으로 로그인](/docs/cli/login) 참조).

`--base-url` 플래그는 한 명령에 대해 `KEENAUTH_BASE_URL`를 재정의합니다. CLI는 API 키를 출력하지 않습니다. 서버 응답에 키가 포함되어 있으면 `[redacted]`로 대체됩니다.

## 명령

명령은 `keenauth <group> <action> [arguments] [flags]` 형식을 따릅니다. 전체 목록은 `keenauth --help` 또는 `keenauth <group> --help`을 실행하여 확인하십시오.

| 그룹 | 작업 |
|---|---|
| `users` | `list`, `search`, `get`, `create`, `update`, `delete`, `block`, `unblock`, `cancel-deletion`, `authenticators list`, `authenticators delete`, `authenticators reset`, `authenticators reactivate`, `send-password-reset`, `send-verification-email`, `emails send-verification`, `start-recovery`, `logs list` |
| `applications` | `list`, `create`, `get`, `update`, `delete`, `get-api-grant`, `put-api-grant`, `delete-api-grant`, `credentials list`, `credentials create`, `credentials delete` |
| `apis` | `list`, `create`, `get`, `update`, `delete` |
| `connections` | `list`, `create`, `get`, `update`, `delete`, `activate`, `deactivate` |
| `identity-settings` | `get`, `update` |
| `environment-settings` | `get`, `update` |
| `config` | `export`(`-o`가 없으면 YAML을 출력), `plan -f <file>`(터미널에서는 읽기 쉬운 diff를 출력), `plans get`, `apply <plan_id>`(확인을 요청하며, `--secrets-from-env`는 환경 변수에서 비밀 값을 읽음, `--confirm-deletion <kind>/<key>`), `promote --from <env> --to <env>`(내보내기, 계획, diff 표시 후 확인을 거쳐 적용합니다. [keenauth config promote로 설정 승격](/docs/cli/config-promote) 참조) |
| `api-keys` | `list`, `get`, `create`, `rotate`, `revoke` |
| `logs` | `list`, `get`, `tail`(새 레코드를 따라갑니다. `--type`, `--user`, `--org`. [keenauth logs tail로 로그 따라가기](/docs/cli/tail) 참조) |
| `support-access-grants` | `list`, `get`, `create`, `delete`([keenauth support-access-grants로 지원 액세스 권한 부여](/docs/cli/support-access-grants) 참조) |
| `directories` | `simulate <directory_id> --scenario <name>`(개발 및 스테이징 환경에서 SCIM 시뮬레이터 시나리오를 실행합니다. [keenauth directories simulate로 SCIM 프로비저닝 테스트](/docs/cli/directories-simulate) 참조) |
| `audit` | `verify`(다운로드한 감사 내보내기를 오프라인으로 검사합니다. [keenauth audit verify로 감사 내보내기 검증](/docs/cli/audit-verify) 참조) |
| `branding` | `get`, `update`, `applications get`, `applications put`, `organizations get`, `organizations put`, `css put`, `page-template put`, `publish`, `rollback`, `versions list`, `texts get`, `texts put`, `texts delete` |
| `signing-keys` | `list`, `rotate`, `policy get`, `policy update` |
| `events` | `tail`(이벤트 API를 통해 고객 이벤트를 따라갑니다. [keenauth events tail로 이벤트 따라가기](/docs/cli/events-tail) 참조), `get <event ID>`(이벤트 하나를 서버가 보낸 그대로 출력) |
| `mock` | `serve`은 오프라인 테스트용 로컬 OIDC 모의 서버를 실행합니다. API 키는 필요하지 않습니다([로컬 모의 서버](/docs/cli/mock-server) 참조). |
| `test` | `login --user <+test address>`은 고정 코드로 `development` 환경에 테스트 사용자를 로그인시키고 토큰을 출력합니다. API 키는 필요하지 않습니다([keenauth test login으로 테스트 사용자 로그인](/docs/cli/test-login) 참조). |
| `webhooks` | `listen --forward-to <local URL>`은 `development` 또는 `staging` 환경의 이벤트를 임시 비밀 값으로 서명하여 사용자의 기기로 전달합니다([keenauth webhooks listen으로 웹훅 로컬 테스트](/docs/cli/webhooks-listen) 참조). |
| `login`, `logout`, `whoami`, `env` | `login`(`--web`, `--insecure-storage`), `logout`, `whoami`, `env use <environment_id>`, `env list`: API 키 대신 대시보드 계정으로 로그인합니다([keenauth login으로 로그인](/docs/cli/login) 참조). |

목록 명령은 `--limit`, `--after`, `--before`, `--order`를 받습니다. 결과가 더 있으면 다음 커서가 `more results: --after <cursor>` 형식으로 표준 오류(stderr)에 출력됩니다.

## 출력 형식

`--output`(`-o`)는 `table`, `json` 또는 `yaml`를 선택합니다. 플래그가 없으면 터미널에서는 표를, 그 외에는 JSON을 출력합니다. JSON과 YAML에는 API 응답이 그대로 포함되며 번역되지 않으므로 스크립트에서 안정적으로 사용할 수 있습니다. 결과는 표준 출력(stdout)으로, 오류, 힌트, `etag` 줄은 표준 오류(stderr)로 전달됩니다.

## 요청 본문

본문을 보내는 명령은 평면 필드마다 플래그를 하나씩 받으며, 이름은 JSON 키를 대시로 구분한 형태입니다(`phone_number`는 `--phone-number`가 됩니다). 중첩 객체는 `--data`로 지정합니다.

- `--data @file.json`는 파일에서 본문을 읽습니다.
- `--data -`는 표준 입력에서 본문을 읽습니다.

플래그는 파일의 필드보다 우선합니다. 본문은 4 MiB로 제한됩니다.

```sh
keenauth users create --email ada@example.com
keenauth apis create --data @api.json
echo '{"name":"Orders"}' | keenauth apis update api_123 --data - --if-match '"v3"'
```

## 낙관적 동시성: `--if-match` 및 etag

애플리케이션, API, 연결의 수정 및 삭제 명령에는 `--if-match`가 필요합니다. `users update`도 이를 받습니다. 이 값은 변경하려는 버전의 `ETag`입니다. 그사이 리소스가 변경되었으면 서버는 요청을 거부합니다. `identity-settings update`에도 이 값이 필요합니다. `environment-settings update`에도 이 값이 필요합니다. 브랜딩 초안 쓰기 명령(`branding update`, `branding applications put`, `branding organizations put`, `branding css put`, `branding page-template put`)에도 이 값이 필요합니다.

각 `get` 명령(`users`, `applications`, `apis`, `connections`, `identity-settings`, `environment-settings`)은 응답 `ETag`를 표준 오류(stderr)에 출력하므로 표준 출력(stdout)은 깨끗하게 유지됩니다.

```sh
$ keenauth apis get api_123
{ ... }
etag: "v3"
$ keenauth apis update api_123 --name Orders --if-match '"v3"'
```

`etag` 줄은 JSON 또는 YAML 출력에 추가되지 않습니다.

## 파괴적 명령과 `--yes`

삭제하거나 차단하는 명령은 터미널에서 확인을 요청합니다(`[y/N]`). 거부하면 코드 1로 종료되고 `aborted`가 출력됩니다. 표준 입력이 터미널이 아닌 경우, `--yes`(`-y`)를 전달하지 않으면 명령은 실행되지 않고, 요청을 보내기 전에 코드 2로 종료됩니다.

## 종료 코드

| 코드 | 의미 |
|---|---|
| `0` | 성공. |
| `1` | 서버 또는 운영 오류, 거부된 확인, 또는 네트워크 실패. |
| `2` | 사용법 오류: 알 수 없는 명령이나 플래그, 누락된 인수, 잘못된 본문, 또는 대화형이 아닌 터미널에서 `--yes` 누락. |
| `3` | 인증 오류: 키가 없거나 서버가 401 또는 403으로 응답함. |
| `4` | 요금제에 해당 기능이 포함되지 않음(`403` 사용 시 `plan_feature_unavailable`). |

서버 오류의 경우 CLI는 `error`, `code`, `status`, `detail`, `request_id`와 검증 오류마다 `field` 줄을 표준 오류(stderr)에 출력합니다. 지원팀에 문의할 때는 `request_id`를 함께 알려주십시오.

## 언어

사람이 읽는 텍스트(도움말, 프롬프트, 오류, 표 머리글)는 터키어(`tr`), 영어(`en`), 프랑스어(`fr`), 독일어(`de`), 한국어(`ko`), 일본어(`ja`), 이탈리아어(`it`), 스페인어(`es`)로 제공됩니다. 언어는 다음 변수 중 첫 번째로 설정된 값에서 선택됩니다: `KEENAUTH_LANG`, `LC_ALL`, `LC_MESSAGES`, `LANG`(예: `tr_TR.UTF-8`는 `tr`를 선택). 값이 비어 있거나 지원되지 않으면 영어가 선택되며, 특정 언어에 없는 메시지는 영어로 대체됩니다.

기계가 읽는 출력은 번역되지 않습니다. JSON과 YAML의 필드 이름과 값, 문제 `code` 및 `code`, `status`, `request_id` 레이블은 모든 언어에서 동일하게 유지됩니다. 서버에서 온 메시지는 서버가 보낸 그대로 표시됩니다.

```sh
KEENAUTH_LANG=de keenauth users list --help
```

## 애플리케이션 자격 증명

`keenauth applications credentials list|create|delete`은 애플리케이션의 클라이언트 비밀 값과 등록된 공개 키를 관리합니다. 이 명령들은 `--if-match`를 사용하지 않습니다.

```sh
keenauth applications credentials create app_123 --type client-secret --expires-at 2027-01-01T00:00:00Z
keenauth applications credentials create app_123 --type public-key --jwk-file key.pub.jwk
keenauth applications credentials delete app_123 cred_456 --yes
```

클라이언트 비밀 값은 표준 출력(stdout)에 한 번만 출력되며, 표준 오류(stderr)에 일회성 경고가 함께 표시됩니다. `--jwk-file`는 공개 JWK 하나(최대 16 KiB)만 받습니다. 비공개 멤버가 포함된 파일은 요청을 보내기 전에 거부됩니다.

## API 키

`keenauth api-keys list|get|create|rotate|revoke`은 환경의 관리 API 키를 관리합니다. 이 명령들은 `--if-match`를 사용하지 않습니다.

```sh
keenauth api-keys create --name ci --type restricted --permissions users:read,users:write --expires-at 2027-10-01T00:00:00Z
keenauth api-keys rotate key_123 --overlap-hours 24
keenauth api-keys revoke key_123 --reason leaked --yes
```

`create`와 `rotate`의 원본 키는 표준 출력(stdout)에 한 번만 출력되며, 표준 오류(stderr)에 일회성 경고가 함께 표시됩니다. 이후에는 다시 조회할 수 없습니다. `list`와 `get`는 메타데이터만 출력합니다.