Commands

union-cli는 빌드 시 자동 생성되는 Built-in 커맨드와 프레임워크 관리용 커맨드를 제공합니다.

npm run build 시 manifest에서 정의한 커맨드와 함께 다음 Built-in 커맨드가 자동 생성됩니다:

파일	커맨드	설명
`auth/login.js`	`auth login`	인증 로그인
`auth/status.js`	`auth status`	인증 상태 조회
`auth/logout.js`	`auth logout`	인증 로그아웃
`doctor.js`	`doctor`	시스템 진단

이 커맨드들은 manifest 정보(namespace, auth 설정, baseUrl 등)가 코드에 임베딩되어 생성됩니다.

Auth - 인증 관리

인증 방식별 YAML 설정 및 동작 원리는 인증 가이드를 참조하세요. 이 섹션에서는 CLI 커맨드 사용법을 설명합니다.

Provider별 인증 로그인을 수행합니다.

my-cli auth login [namespace]

Arguments

인자	필수	설명
`namespace`	N	로그인할 Provider의 namespace. 생략 시 모든 provider

Flags

플래그	설명
`--json`	결과를 JSON으로 출력
`--no-color`	색상 비활성화

Auth type별 동작

Auth Type	동작
`none`	건너뜀 ("인증 불필요")
`cookie`	브라우저 OAuth 로그인 -> Chrome 쿠키 추출 -> `.union-cli/tokens.json` 저장
`bearer` / `api-key`	토큰 직접 입력 프롬프트 -> `tokens.json` 저장
기타	"미지원" 경고

Examples

# 모든 provider에 대해 순차 로그인
my-cli auth login

# 특정 namespace만 로그인
my-cli auth login api

예상 출력:

🔐 api (cookie) 로그인...
  브라우저에서 로그인하세요...
  로그인 완료 후 Enter를 누르세요:
  ✅ api: 2개 쿠키 저장 완료

🔐 public (none) 로그인...
  ℹ public: 인증 불필요

auth logout

인증 정보를 삭제합니다.

my-cli auth logout [namespace]

Arguments

인자	필수	설명
`namespace`	N	로그아웃할 namespace. 생략 시 전체 로그아웃

Flags

플래그	설명
`--json`	결과를 JSON으로 출력
`--no-color`	색상 비활성화

Examples

# 전체 로그아웃 (tokens.json 파일 삭제)
my-cli auth logout

# 특정 namespace만 로그아웃
my-cli auth logout api

auth status

현재 인증 상태를 테이블로 표시합니다.

my-cli auth status [--verify] [--json]

Flags

플래그	설명
`--json`	결과를 JSON으로 출력
`--verify`	실제 API 호출(`/api/v1/auth/me`)로 토큰 유효성 확인
`--no-color`	색상 비활성화

Examples

Table 출력
JSON 출력

my-cli auth status

NAMESPACE   AUTH TYPE  STATUS      EXPIRES
---------   ---------  ----------  -------------------
api         cookie     ✓ valid     2026-04-07 09:18:50
k8s-proxy   cookie     ✗ expired   2026-04-07 08:32:50
public      none       ✓ (no auth)

my-cli auth status --json

[
  {
    "namespace": "api",
    "auth_type": "cookie",
    "status": "✓ valid",
    "expires": "2026-04-07 09:18:50"
  }
]

auth token

특정 namespace의 토큰을 stdout으로 출력합니다. 파이프나 다른 도구와 연동할 때 유용합니다.

my-cli auth token <namespace>

Arguments

인자	필수	설명
`namespace`	Y	토큰을 출력할 Provider namespace

Examples

# 토큰 출력
my-cli auth token api

# 다른 도구에 토큰 전달
curl -H "Authorization: Bearer $(my-cli auth token api)" https://api.example.com/v1/me

스크립트 연동

auth token은 stdout으로만 토큰을 출력하므로 shell substitution과 파이프에 안전하게 사용할 수 있습니다.

Config - 설정 관리

CLI 설정을 관리합니다. 설정은 ~/.my-cli/config.yaml에 YAML 형식으로 저장됩니다.

config get

설정값을 조회합니다.

my-cli config get <key>

Arguments

인자	필수	설명
`key`	Y	조회할 설정 키

Examples

$ my-cli config get default_format
json

$ my-cli config get nonexistent_key
(nonexistent_key 설정되지 않음)

config set

설정값을 저장합니다.

my-cli config set <key> <value>

Arguments

인자	필수	설명
`key`	Y	설정 키
`value`	Y	설정 값

Flags

플래그	설명
`--global`	글로벌 설정에 저장

Examples

$ my-cli config set default_format json
✓ default_format = json

config list

전체 설정을 출력합니다.

my-cli config list [--json] [--global]

Flags

플래그	설명
`--json`	JSON 형식으로 출력
`--global`	글로벌 설정 조회

Examples

기본 출력
JSON 출력

$ my-cli config list
default_format = json
timeout = 30000

$ my-cli config list --json
{
  "default_format": "json",
  "timeout": "30000"
}

config reset

설정을 초기화합니다.

my-cli config reset [key]

Arguments

인자	필수	설명
`key`	N	초기화할 설정 키. 생략 시 전체 초기화

전체 초기화

key를 생략하면 모든 설정이 초기화됩니다. 이 작업은 되돌릴 수 없습니다.

Plugin - 플러그인 관리

외부 플러그인을 관리합니다.

plugin add

플러그인을 추가합니다.

my-cli plugin add <source>

Arguments

인자	필수	설명
`source`	Y	플러그인 경로 또는 npm 패키지 이름

Examples

# 로컬 YAML 파일 추가
my-cli plugin add ./plugins/custom-api.yaml

# npm 패키지 추가
my-cli plugin add @my-org/cli-plugin-monitoring

plugin remove

플러그인을 제거합니다.

my-cli plugin remove <name>

Arguments

인자	필수	설명
`name`	Y	제거할 플러그인 이름

plugin list

등록된 플러그인 목록을 출력합니다.

my-cli plugin list [--json]

Flags

플래그	설명
`--json`	JSON 형식으로 출력

System - 시스템 커맨드

init

union-cli 프로젝트를 초기화합니다. .union-cli/ 및 plugins/ 디렉토리를 생성합니다.

my-cli init [--force]

Flags

플래그	단축키	설명
`--force`	`-f`	기존 설정이 있어도 덮어쓰기

Examples

$ my-cli init
✓ 프로젝트 초기화 완료
다음 단계:
  1. plugins/ 디렉토리에 YAML manifest를 작성하세요
  2. my-cli build

build

YAML manifest를 파싱하고 oclif 커맨드 파일을 생성합니다.

my-cli build [--codegen] [--watch]

Flags

플래그	설명
`--codegen`	TypeScript 코드 생성 모드
`--watch`	파일 변경 감지 모드

빌드 과정

manifest 파일 탐색 (plugins/*.yaml, .union-cli/plugins/*.yaml)
YAML 파싱 + 스키마 검증 + 의미 검증
.union-cli/manifest.json에 캐시 저장
--codegen 시 dist/commands/에 JS 파일 생성

Examples

$ my-cli build
Building...
3개 manifest에서 빌드 완료
  캐시: .union-cli/manifest.json
  명령: 24개

codegen

특정 플러그인의 TypeScript 코드를 생성합니다.

my-cli codegen <plugin>

Arguments

인자	필수	설명
`plugin`	Y	플러그인 이름

doctor

Node.js, manifest, Provider 상태를 종합적으로 확인합니다.

my-cli doctor [--json]

Flags

플래그	설명
`--json`	JSON 형식으로 출력
`--no-color`	색상 비활성화

점검 항목

항목	설명
Node.js	Node.js 버전 확인
작업 디렉토리	현재 작업 디렉토리
매니페스트	`.union-cli/manifest.json` 존재 여부 + manifest 개수
토큰	`.union-cli/tokens.json` 존재 여부
Provider 상태	각 Provider의 health endpoint(`/health`)에 GET 요청 (5초 타임아웃)

Examples

기본 출력
JSON 출력

$ my-cli doctor
시스템 상태:
  Node.js: v20.10.0 ✓
  작업 디렉토리: /path/to/my-cli ✓
  매니페스트: 3개 ✓
  토큰: ✓

Provider 상태:
  api: ✓ ok
  k8s: ✗ unreachable
  public: ✓ ok

$ my-cli doctor --json

{
  "node": { "status": "ok", "version": "v20.10.0" },
  "cwd": { "status": "ok", "path": "/path/to/my-cli" },
  "manifests": { "status": "ok", "count": 3 },
  "tokens": { "status": "ok" },
  "providers": [
    { "namespace": "api", "status": "ok", "code": 200 },
    { "namespace": "k8s", "status": "unreachable", "error": "fetch failed" }
  ]
}

문제 해결

doctor에서 Provider 상태가 unreachable로 표시되면, 해당 서비스의 네트워크 접근성과 baseUrl 설정을 확인하세요.

completion install

셸 자동완성을 설치합니다.

my-cli completion install [shell]

Arguments

인자	필수	기본값	설명
`shell`	N	`zsh`	셸 종류: `bash`, `zsh`, `fish`

Examples

my-cli completion install zsh
my-cli completion install bash

출력 형식

모든 커맨드에 자동으로 적용되는 표준 플래그입니다.

--json

JSON 형식으로 출력합니다. --format json의 단축 형태입니다.

my-cli api users list --json

--format

출력 형식을 지정합니다.

값	설명
`table`	테이블 형식 (기본)
`json`	JSON (`--json`과 동일)
`yaml`	YAML 형식 출력
`csv`	콤마 구분, 첫 줄 헤더

Table (기본)
JSON
YAML
CSV

my-cli api users list

NAME    EMAIL             STATUS
------  ----------------  ------
John    john@example.com  active
Jane    jane@example.com  active

my-cli api users list --json

{
  "data": [
    { "id": 1, "name": "John", "email": "john@example.com" }
  ]
}

my-cli api users list --format yaml

data:
  - id: 1
    name: John
    email: john@example.com

my-cli api users list --format csv > users.csv

id,name,email,status
1,John,john@example.com,active

--quiet / -q

출력을 억제합니다. exit code만으로 성공/실패를 판단할 때 사용합니다.

my-cli api users create --name "John" --email "john@example.com" --quiet
echo $?  # 0 = 성공, 1 = 실패

--debug

디버그 정보를 출력합니다. 에러 발생 시 상세 정보(details, stack trace)를 포함합니다.

my-cli api users list --debug

--no-color

색상과 이모지를 비활성화합니다. CI/CD 환경이나 로그 파일 기록에 적합합니다.

my-cli auth status --no-color
# [OK] valid  (✓ 대신 [OK])
# [X] expired (✗ 대신 [X])

환경변수로도 제어할 수 있습니다:

환경변수	효과
`NO_COLOR=1`	색상 비활성화
`TERM=dumb`	색상 비활성화
`FORCE_COLOR=1`	색상 강제 활성화 (다른 설정보다 우선)

CI/CD 환경

대부분의 CI/CD 환경에서는 NO_COLOR가 자동으로 설정되거나 TERM=dumb이 기본값입니다. 별도 설정 없이 색상이 비활성화됩니다.

Output 동작 상세

출력 세부 동작

테이블: API 응답에서 배열 데이터를 자동 추출(data, items 필드 또는 직접 배열)하며, 한글/CJK 문자의 터미널 display width를 올바르게 처리합니다.
상태 변경 알림: GET 이외의 HTTP method 요청 성공 시 TTY 환경에서 stderr로 POST 요청 완료 (234ms) 형태의 알림을 출력합니다. stdout 파이프를 오염시키지 않으며, --quiet로 억제할 수 있습니다.
Spinner: TTY 환경에서 --quiet가 아닌 경우, 요청 중 spinner 애니메이션이 stderr에 표시됩니다.

Auth - 인증 관리​

auth login​

Arguments​

Flags​

Auth type별 동작​

Examples​

auth logout​

Arguments​

Flags​

Examples​

auth status​

Flags​

Examples​

auth token​

Arguments​

Examples​

Config - 설정 관리​

config get​

Arguments​

Examples​

config set​

Arguments​

Flags​

Examples​

config list​

Flags​

Examples​

config reset​

Arguments​

Plugin - 플러그인 관리​

plugin add​

Arguments​

Examples​

plugin remove​

Arguments​

plugin list​

Flags​

System - 시스템 커맨드​

init​

Flags​

Examples​

build​

Flags​

빌드 과정​

Examples​

codegen​

Arguments​

doctor​

Flags​

점검 항목​

Examples​

completion install​

Arguments​

Examples​

출력 형식​

--json​

--format​

--quiet / -q​

--debug​

--no-color​

Output 동작 상세​

Auth - 인증 관리

auth login

Arguments

Flags

Auth type별 동작

Examples

auth logout

Arguments

Flags

Examples

auth status

Flags

Examples

auth token

Arguments

Examples

Config - 설정 관리

config get

Arguments

Examples

config set

Arguments

Flags

Examples

config list

Flags

Examples

config reset

Arguments

Plugin - 플러그인 관리

plugin add

Arguments

Examples

plugin remove

Arguments

plugin list

Flags

System - 시스템 커맨드

init

Flags

Examples

build

Flags

빌드 과정

Examples

codegen

Arguments

doctor

Flags

점검 항목

Examples

completion install

Arguments

Examples

출력 형식

--json

--format

--quiet / -q

--debug

--no-color

Output 동작 상세