명령줄 인터페이스 핸드북

일관되고 사용하기 좋으며 개발자 친화적인 CLI(Command-line Interface)를 디자인하기 위한 모범 사례를 담고 있어요. CLI 도구를 만드는 개발자와 기술 제품에 협력하는 디자이너를 지원하며, 특히 CLI 도구가 사용자 경험의 주요하거나 중요한 부분인 환경에서 명령 구문·도움말 문서·오류 메시지·대화형 동작 전반에 걸쳐 명확성·구조·사용자 중심 디자인을 강조해요.

출처: Command-Line Interface Handbook

본문

CLI에는 시각적 UI 요소가 없지만, 많은 접근성 원칙이 여전히 적용돼요.

접근성은 그래픽 인터페이스에서 못지않게 CLI 디자인에서도 중요해요. 명확하고 포용적인 출력은 스크린 리더나 대체 입력 장치를 사용하는 사용자를 포함해 모든 사용자가 도구와 성공적으로 상호작용할 수 있도록 보장해요.

CLI의 접근성을 보장하려면 다음과 같은 추가 색상·콘텐츠·테스트 관행을 준수하세요.

색상 (Color)

Don't	Do
색상만으로 의미를 전달하지 마세요.	색상 기반 단서와 함께 텍스트를 사용하세요. 예를 들어 "Success"와 "Error" 라벨.
	텍스트를 빨강/초록 표시와 함께 사용해 색맹 사용자에게도 정보가 접근 가능하도록 하세요.

콘텐츠 (Content)

Don't	Do
"it failed" 같은 모호한 용어를 사용하지 마세요.	서술적이고 구체적인 언어로 직접적이고 투명하게 행동하세요.
사용자가 맥락만으로 의미를 추론할 수 있다고 가정하지 마세요.	프롬프트와 피드백에 서술적 텍스트를 사용하세요.
명확한 텍스트 안내 없이 시각적 스캔이 필요한 프롬프트 흐름을 사용하지 마세요.	모든 명령과 프롬프트가 키보드로 접근 가능하고 비대화형에도 안전하도록 보장하세요. 스크립팅이나 보조 기술 사용자를 위해 `--non-interactive` 같은 플래그를 사용하세요.
지나치게 꾸민 ASCII 테이블, 긴 텍스트 벽, 동적 애니메이션을 사용하지 마세요.	스크린 리더가 파싱할 수 있는 평이하고 구조화된 출력을 사용하세요. 제목·불릿 포인트·명확한 구분자가 있는 깔끔하고 라벨이 붙은 출력을 사용하세요.

테스트 (Testing)

Don't	Do
디자인이 접근 가능하다고 가정하지 마세요.	스크린 리더와 색맹 시뮬레이터로 테스트해 대비·명확성·장황함의 미묘한 문제를 드러내세요.

예시 (Example)

접근 가능한 예:

✅ Deployment successful.
Run `tool status` to check environment health.

접근성이 덜한 예:

✅ You did it!

CLI 입력 (CLI inputs)

CLI를 위해 효과적으로 쓰려면 CLI 입력의 다양한 요소를 이해하는 것이 중요해요:

명령 이름(Command name): 명령이 수행할 동작과 그 동작이 적용되는 대상을 식별해요.
인자(Arguments): 명령 이름과 함께 사용되는 추가 세부 정보로, 사용자가 명령이 적용되는 방식을 지정하기 위해 선택해요.
플래그(Flags): 명령의 동작을 수정하는 명명된 매개변수.

명령 (Commands)

명령은 CLI가 트리거하는 동작을 설명해요.

명령 이름은 일관되게 동사-명사 구조를 사용해야 해요:

동사(Verb): 수행되는 동작.
명사(Noun): 영향을 받는 리소스 또는 객체.

이 구조는 사람들이 작업에 대해 생각하는 방식을 반영해 명령을 더 직관적이고 발견 가능하게 만들어요. 동사-명사 형식은 또한 git, kubectl, docker 같은 널리 쓰이는 CLI와 일치해요. 반대로 명사-동사 구조는 파싱하기 더 어렵고 잘 확장되지 않아요.

예시

다음 코드 블록에서 create project, delete environment, scale deployment는 모두 명령이에요.

tool create project
tool delete environment
tool scale deployment

인자 (Arguments)

인자는 명령 뒤에 오는 비플래그 값으로, 보통 파일 경로나 프로젝트 이름 같은 고유 식별자예요.

명령은 실행되기 위해 인자가 필요해요. 여러 인자를 사용할 수 있지만 순서가 중요해요. 더 적은 인자가 기억하기 쉽고 혼란을 피하는 데 선호돼요.

예시

다음 코드 블록에서 delete project와 deploy environment는 명령이고, my-app과 production은 동작 대상인 객체를 나타내는 인자예요.

tool delete project my-app
tool deploy environment production

플래그 (Flags)

플래그는 2개의 하이픈(--)으로 접두사가 붙은 명명된 매개변수로, 명령의 동작을 수정해요. 사용자가 명령 수정자·옵션·기타 비필수 구성을 지정할 수 있게 해줘요. 플래그는 어떤 순서로든 추가할 수 있어요.

예시

다음 코드 블록에서 --env, --force, --role, --email은 플래그예요.

tool deploy --env staging --force
tool create user --role admin --email user@Examples:.com

긴 형식과 짧은 형식

플래그에는 2가지 형식이 있어요:

긴 형식(Long-form) 플래그: 더 서술적이고 명확해요.

tool deploy app --enable-autoscaling
tool configure user --assign-admin-privileges
tool update cluster --set-min-replicas 3

짧은 형식(Short-form) 플래그: 1-2글자로 더 간결해요.
- 자주 사용되는 옵션으로 한정하세요. 속도를 선호하는 경험 많은 사용자와 공간이 제한된 상황에 혜택을 줘요.
- 가능하면 더 나은 명확성과 발견 가능성을 위해 긴 형식과 짝을 이루세요.

tool --help # Long-form
tool -h # Short-form (Help)

tool --verbose # Long-form
tool -v # Short-form (Verbose)

tool --config path/to/file
tool -c path/to/file # Short-form (Config file path)

플래그 유형

불리언 플래그(Boolean flags): 켜짐/꺼짐 또는 참/거짓 옵션을 나타내요.
- 합리적인 기본값을 설정하세요.
- 필요하지 않으면 명시적 값을 요구하지 마세요. 예를 들어 --force=true 대신 --force를 허용하세요.

tool deploy --dry-run # Runs without executing
tool delete --force # Skips confirmation prompt

도움말 플래그(Help flags): 명령의 목적·인자/플래그·사용 예시를 설명하는 도움말 문서를 제공해요.
- 긴 --help와 짧은 -h 옵션을 모두 제공하세요.

명령줄 인터페이스 핸드북