# CLI

CLI authentication endpoints for device authorization flow

Source: https://keyenv.dev/docs/api/cli/

CLI authentication endpoints for device authorization flow

## Initiate CLI login

```http
POST /api/v1/cli/login
```

Initiates the CLI login flow, returns a URL to open in the browser

**Operation ID:** `cliLogin` · **Authentication:** none (public endpoint)

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `redirect_uri` | `string (uri)` | yes |  |
| `device_name` | `string` | no |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Login URL generated | `CLILoginResponse` |
| `400` | Invalid request | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `auth_url` | `string (uri)` |  |
| `state` | `string` |  |
| `expires_in` | `integer` | Seconds until state expires |
| `user_code` | `string` | Verification code derived from the state (first 8 uppercase hex chars of SHA-256(state), formatted XXXX-XXXX). The CLI displays it and the browser consent screen shows the same code so the user can confirm they match. |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/cli/login" \
  -H "Content-Type: application/json" \
  -d '{"redirect_uri":"string","device_name":"string"}'
```

## Complete CLI login

```http
POST /api/v1/cli/callback
```

Called by the web app after browser authentication completes

**Operation ID:** `cliCallback` &middot; **Authentication:** `Authorization: Bearer <token>`

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | `string` | yes |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Login completed | `CLICallbackResponse` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `access_token` | `string` |  |
| `refresh_token` | `string` |  |
| `expires_at` | `string (date-time)` |  |
| `user` | `object` |  |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/cli/callback" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state":"string"}'
```

## Poll CLI login status

```http
GET /api/v1/cli/status
```

Polls the status of a CLI login flow

**Operation ID:** `cliStatus` &middot; **Authentication:** none (public endpoint)

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | `string` | yes |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Login status | `CLIStatusResponse` |
| `400` | Invalid request | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `status` | `enum (pending, completed, expired)` |  |
| `refresh_token` | `string` |  |
| `user` | `object` |  |
| `expires_at` | `string (date-time)` |  |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/cli/status"
```

## Refresh CLI token

```http
POST /api/v1/cli/refresh
```

Refreshes an expired access token using a refresh token

**Operation ID:** `cliRefresh` &middot; **Authentication:** none (public endpoint)

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refresh_token` | `string` | yes |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | New access token | `CLIRefreshResponse` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `access_token` | `string` |  |
| `expires_at` | `string (date-time)` |  |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/cli/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"string"}'
```

## CLI logout

```http
POST /api/v1/cli/logout
```

Revokes the CLI session

**Operation ID:** `cliLogout` &middot; **Authentication:** none (public endpoint)

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refresh_token` | `string` | yes |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Logged out |  |
| `400` | Invalid request | `Error` |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/cli/logout" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"string"}'
```

## CLI whoami

```http
GET /api/v1/cli/whoami
```

Returns the current user and session info

**Operation ID:** `cliWhoami` &middot; **Authentication:** `Authorization: Bearer <token>`

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | User and session info | `CLIWhoamiResponse` |
| `401` | Authentication required | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `user` | `object` |  |
| `teams` | `object[]` |  |
| `session_created_at` | `string (date-time)` |  |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/cli/whoami" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```