---
title: "alpacon api"
description: "로그인한 CLI 세션으로 Alpacon API에 요청을 보냅니다. 필드로 쿼리 문자열과 JSON 본문을 만드는 방법, 응답 본문과 헤더를 읽는 방법, MFA 확인이 필요할 때의 절차, 스크립트에서 분기할 종료 코드를 안내합니다. 직접 API를 호출할 때 참고하세요."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# alpacon api

로그인한 계정으로 현재 워크스페이스의 Alpacon API에 요청 하나를 보냅니다.

## 사용법

`alpacon api ENDPOINT [flags]`

## 핵심 사항

- `ENDPOINT`에는 `/api/iam/users/`처럼 현재 워크스페이스의 경로를 지정. 절대 URL이나 다른 호스트는 거부
- `-X`를 생략하면 `GET`으로 요청하고, 필드나 `--input`을 지정하면 `POST`로 요청
- `GET`과 `HEAD`는 필드를 쿼리 문자열로 보내고, 그 밖의 메서드는 JSON 본문으로 보냄. `--input`을 지정하면 메서드와 관계없이 쿼리 문자열로 보냄
- 오류 응답도 본문은 stdout에 출력. 오류일 때는 stderr에 `HTTP <code>`를 함께 출력하고 종료 코드 `1`로 종료
- MFA를 새로 확인해야 하는 작업이면 MFA 링크를 표시하고, 확인을 마치면 요청을 다시 보냄

## 플래그

| 플래그 | 유형 | 설명 | 기본값 |
| --- | --- | --- | --- |
| `-F, --field` | `field` | 유형을 해석하는 필드(`key=value`) | — |
| `-H, --header` | `stringArray` | 요청 헤더(`key:value`). `Host`, `Transfer-Encoding`, `Trailer`, `Content-Length`는 지정 불가 | — |
| `-h, --help` | `bool` | 명령 도움말 표시 | `false` |
| `-i, --include` | `bool` | 응답 헤더 포함 | `false` |
| `--input` | `string` | 요청 본문 파일(`-`는 표준 입력) | — |
| `-X, --method` | `string` | HTTP 메서드 | `GET` |
| `-f, --raw-field` | `field` | 문자열 필드(`key=value`) | — |
| `--silent` | `bool` | 응답 본문 출력 안 함 | `false` |
| `--verbose` | `bool` | 요청과 응답 헤더를 stderr에 출력 | `false` |
| `--output` | `string` | 출력 형식: `table` 또는 `json` | `table` |

## 예제

내 사용자 정보 조회

```bash
alpacon api /api/iam/users/-/
```

상태 줄과 응답 헤더를 포함해 사용자 검색

```bash
alpacon api -X GET -i -f search=admin /api/iam/users/
```

유형을 해석하는 필드로 리소스 만들기(`POST`로 요청)

```bash
alpacon api -F name=my-server /api/servers/servers/
```

JSON 파일로 리소스 수정

```bash
alpacon api -X PATCH --input update.json /api/servers/servers/123/
```

## 요청 필드

`-f key=value`는 값을 항상 문자열로 보냅니다. `-F key=value`는 값을 다음과 같이 해석합니다.

| 값 | 보내는 형태 |
| --- | --- |
| `true`, `false` | 불리언 |
| `null` | `null` |
| 정수 | 정수 |
| `@file` | 파일 내용(문자열) |
| `@-` | 표준 입력(문자열) |
| 그 밖의 값 | 문자열 |

키에 대괄호를 쓰면 중첩된 값을 만듭니다. `-f 'tags[]=one' -f 'tags[]=two'`는 배열을, `-f 'filter[name]=demo'`는 객체를 보냅니다. 쿼리 문자열에서는 대괄호가 매개변수 이름에 그대로 남습니다.

`--input`을 지정하면 파일(`--input -`이면 표준 입력)이 요청 본문이 되고, `-f`와 `-F` 필드는 쿼리 문자열로 갑니다. `POST`, `PUT`, `PATCH` 요청은 `Content-Type: application/json`으로 보냅니다. 다른 형식의 본문을 보내려면 `-H 'Content-Type: ...'`을 지정하세요. 표준 입력은 필드 하나나 `--input` 하나만 읽을 수 있습니다.

## 응답 출력

응답 본문은 stdout에 출력합니다. 터미널에 출력할 때는 본문에서 제어 문자를 지우고, JSON 본문은 들여씁니다. 파이프로 넘기거나 파일로 저장하면 서버가 보낸 본문을 그대로 출력하므로 `jq` 같은 도구가 원본을 읽을 수 있습니다.

`-i`는 본문 앞에 상태 줄과 응답 헤더를 붙이고, `--verbose`는 요청과 응답 헤더를 stderr에 출력합니다. 두 경우 모두 `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie` 값은 `[REDACTED]`로 가립니다. `--silent`를 쓰면 본문은 출력하지 않지만 결과는 종료 코드로 알 수 있습니다.

워크스페이스 안의 리다이렉트는 따라갑니다. 다른 호스트로 가는 리다이렉트는 따라가지 않고 stderr에 `HTTP <code>`와 `redirect to <location> not followed`를 출력하고 종료 코드 `1`로 끝납니다.

## 권한과 MFA

요청은 [`alpacon login`](/reference/cli/login/)으로 로그인한 계정의 권한으로 실행됩니다. 그 계정이 할 수 없는 작업은 서버가 거부하며, 거부 응답의 본문도 다른 응답처럼 출력합니다. 엔드포인트와 오류 코드는 [API 참조](/reference/api/)를 확인하세요.

역할 부여처럼 MFA를 새로 확인해야 하는 작업이 있습니다. 서버가 MFA 확인을 요구하면 CLI는 워크스페이스의 MFA 링크를 출력하고, 브라우저를 쓸 수 있으면 링크를 엽니다. 그리고 MFA를 마칠 때까지 3분 정도 기다립니다. 확인이 끝나면 요청을 다시 보내고 마지막 응답만 출력합니다. 대기 시간이 지나면 서버 응답을 출력하고, stderr에 응답의 `HTTP <code>`와 `MFA authentication timed out`을 남긴 뒤 종료 코드 `1`로 끝납니다.

`-H 'Authorization: ...'`으로 인증 헤더를 직접 지정하면 CLI는 그 헤더를 그대로 보내고 MFA 확인 안내를 띄우지 않습니다. 토큰으로는 MFA를 확인할 수 없으므로, MFA를 새로 확인해야 하는 작업은 본인 계정으로 로그인해서 실행하세요.

## 종료 코드 (Exit codes)

- 0: 서버가 `2xx` 상태로 응답함
- 1: 서버가 그 밖의 상태로 응답했거나, 요청을 보내지 못했거나, 알 수 없는 플래그를 지정함
- 2: 엔드포인트, 메서드, 필드, 헤더, 입력 파일 중 하나가 잘못됨. 요청은 보내지 않음

## 관련 문서

- [API 참조](/reference/api/)
- [API 토큰](/reference/api/tokens/)
- [alpacon login](/reference/cli/login/)
- [alpacon whoami](/reference/cli/whoami/)

Source: https://docs.alpacax.com/ko/reference/cli/api/