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 |
예제
내 사용자 정보 조회
alpacon api /api/iam/users/-/상태 줄과 응답 헤더를 포함해 사용자 검색
alpacon api -X GET -i -f search=admin /api/iam/users/유형을 해석하는 필드로 리소스 만들기(POST로 요청)
alpacon api -F name=my-server /api/servers/servers/JSON 파일로 리소스 수정
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으로 로그인한 계정의 권한으로 실행됩니다. 그 계정이 할 수 없는 작업은 서버가 거부하며, 거부 응답의 본문도 다른 응답처럼 출력합니다. 엔드포인트와 오류 코드는 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: 엔드포인트, 메서드, 필드, 헤더, 입력 파일 중 하나가 잘못됨. 요청은 보내지 않음