명령줄 인터페이스 핸드북

명령줄 인터페이스 핸드북 (Command-line interface handbook)

CLI(명령줄 인터페이스)는 텍스트만으로 소통하기 때문에, 성공·경고·오류 메시지와 도움말 문구 하나하나가 사용자 신뢰를 만드는 요소예요. 이 문서에서는 CLI 출력과 도움말을 어떻게 쓰고 구조화해야 하는지 차근차근 알려드릴게요.

출처: 문서

본문

CLI 출력 (CLI outputs)

CLI 출력 메시지는 보통 다음 3가지 범주 중 하나에 속해요.

범주	용도	예시
성공 (Success)	완료된 동작	✅ Dataset uploaded successfully.
경고 (Warning)	검토가 필요한 완료 동작	⚠️ Model trained, but validation accuracy is low.
오류 (Error)	실패한 동작	❌ Error: Cannot connect to remote service. Check your network connection or try again with --offline mode.

성공 메시지 (Success messages)

신뢰를 쌓고, 명령이 의도대로 동작했음을 강조하며, 사용자를 다음 단계로 안내하려면 성공적인 동작을 분명하게 알려 줘야 해요.

예시 (Example)

✅ Project "my-app" deployed successfully.

Next steps:
- Run `tool status my-app` to check deployment health
- Run `tool logs my-app` to view runtime output

오류 메시지 (Error messages)

오류가 발생하면 무엇이, 왜 일어났고 어떻게 고치는지 설명해야 해요.

UI 오류 작성 지침을 확장해서, CLI 오류는 다음을 따라야 해요:

내부 전문 용어를 피하고 쉬운 일상 언어(plain language)를 사용해요.
해결책과 실행 가능한 다음 단계를 제안해요.
가장 중요한 정보로 마무리해요. 이는 GUI가 있는 제품의 콘텐츠 디자인과 반대되는 방식이에요.
기본적으로 깔끔한 메시지를 제공해요. 전체 스택 트레이스(내부 로그)는 --debug나 --trace 같은 디버그 플래그를 통해서만 노출해야 해요.

예시 (Examples)

일반적인 실패와 해결 방법:

❌ Error: Cannot connect to remote service.
Check your network connection or try again with `--offline` mode.

파일 권한 문제:

❌ Error: Unable to write to file.txt
You may need to change the file’s permissions or run the command with elevated privileges.

명령 구문 오류:

❌ Error: Unrecognized flag --versoin
Did you mean: --version ?

출력 패턴 (Output patterns)

포맷 (Formatting)

출력을 읽기 좋게 만들려면 다음을 지켜요:

큰 출력을 구조화해요:
공백, 구분선, 들여쓰기, 표/열 형식을 사용해서 큰 블록을 나누고 구조 없는 텍스트를 피해요.
반복되는 정보(결과나 요약 등)에는 일관된 헤더 또는 라벨을 사용해요.
목록을 효과적으로 관리해요:
소프트웨어 버전, 리소스, 배포 옵션처럼 스캔하기 쉽도록 목록을 구조화해요.
가장 관련성 높거나 기본값인 항목(예: 현재 버전)을 맨 앞에 표시하고, "Yes"나 "*"로 명확히 표시해요.
5~7개가 넘는 목록은 페이지네이션해요.

버전 나열 (Version listing)

버전 정보를 나열할 때는:

버전을 최신에서 가장 오래된 순으로 위에서 아래로 배열해요.
현재 기본값을 명확히 표시해요.
각 항목 옆에 업그레이드 경로(upgrade path)를 표시해요.

예시 (Example)

Available Versions
-
VERSION DEFAULT AVAILABLE UPGRADES
1.4.3 Yes 1.4.4, 1.4.5, 1.5.0
1.3.9 1.4.0, 1.4.1
1.3.8 1.3.9

페이지네이션 (Pagination)

긴 목록을 5~7개 항목 단위로 나눠서, 사용자가 --more, --page 또는 Enter 키를 눌러 계속 볼 수 있게 해요.

예시 (Example)

tool versions list --limit 5
tool resources list --page 2

정렬과 필터링 (Sorting and filtering)

사용자가 큰 CLI 출력을 이해할 수 있도록 정렬과 필터링 옵션을 제공해요:

기본적으로 관련성(relevance) 또는 최신순(recency)으로 정렬해요.
유연하게 제어할 수 있도록 --sort, --filter, --status 같은 플래그를 제공해요.
기본 보기가 플래그 없이도 기본적인 사용성을 충족하도록 해요.

도움말 문서 (Help documentation)

CLI는 접근 가능한 앱 내 도움말(in-application help)을 반드시 제공해야 해요. 그 관련성을 보장하려면 새 사용자의 관점에서 작성해요. 즉 새 사용자가 바로 무엇을 해야 할지 알 수 있게요.

효과적인 도움말 문서는:

간결하면서도 의미가 있어요.
설명되지 않은 전문 용어나 약어 없이 명확해요.
모든 명령에서 일관적이에요.
지원된다면 대화형 프롬프트에서 --help를 통해 참조되어요.

도움말 출력 작성 (Writing help output)

도움말 출력은 다음 요소로 일관되게 구조화해요:

설명 (Description): 명령의 기능에 대한 일상 언어 설명.
사용법 (Usage): 필수 인자와 플래그를 포함한 명령 구문.
예시 (Examples): 명확한 실제 사용 시나리오 1개 이상.
플래그 (Flags): 간결하고 실행 가능한 설명과 함께 제공되는 옵션 목록.
문서 링크 (선택): 추가 세부 사항용.

예시 (Example)

Usage:
 tool deploy 
 [flags]

Description:
 Deploys the specified project to your active environment.

Examples:
 tool deploy my-app --env staging

Flags:
 -e, --env string Environment to deploy to
 -f, --force Force deployment even if conflicts exist
 -h, --help Show help for the deploy command

For more information, visit: https://Examples:.com/docs/deploy

플래그 문서화 (Documenting flags)

잘 문서화된 플래그는 발견성을 높이고 사용자 오류를 줄이며, 기여자와 사용자가 CLI의 기능을 더 쉽게 이해하게 해요.

플래그를 다음에 명확히 문서화해요:

명령의 --help 출력.
공식 CLI 문서 또는 참조 가이드.
대화형 프롬프트 힌트(해당하는 경우).

모범 사례 (Best practices)

플래그의 용도를 분명히 나타내는 설명적인 이름을 사용해요. --flag1 같은 모호한 이름은 피해요.
입력 타입(예: string, boolean, int)을 문서화해요.
기본값(default value)을 표시해요.
플래그가 선택적(optional)인지 필수(required)인지 언급해요.

플래그 문서는 일반적으로 다음 형식을 따라야 해요:

--flag-name Description of what this flag does (default: value)

예시 (Example)

Flags:
 -n, --name string Name of the project to create
 -e, --env string Target environment (e.g., staging, prod)
 -f, --force Skip confirmation prompts (default: false)
 -o, --output string Output format: json, yaml, or table (default: table)
 -h, --help Show help for this command

스위치(참/거짓)로 동작하는 boolean 플래그의 경우:

보통 기본값이 false예요.
명시적인 값을 요구하지 않아요(예: --force=true가 아니라 --force를 사용).
플래그를 켰을 때 무엇을 하는지 명확히 설명해요.
가능하면 플래그의 효과 또는 일반적인 사용 사례를 설명해요:

--dry-run Simulate the command without making changes. Useful for validation or preview.
--watch Continuously stream status updates until completion.

대화형 모드 (Interactive mode)

대화형 모드는 프롬프트로 사용자를 단계별로 안내하며, 주로 설정 마법사, 구성 흐름, 또는 단일 명령에 적합하지 않은 복잡한 입력에서 사용해요.

대화형 모드를 사용할 때 (When to use interactive mode)

대화형 모드를 사용해요:

설정 또는 초기화 마법사.
선택적 구성 흐름.
프로필 또는 환경 선택.

대화형 모드를 사용하지 말아야 할 때 (When not to use interactive mode)

대화형 모드를 사용하지 마세요:

간단한 일회성 작업.
run, delete, status 같은 반복 작업.
CI/CD 파이프라인 같은 자동화 명령.
플래그로 전달될 수 있는 필수 입력.

대화형 프롬프트 작성 (Writing interactive prompts)

대화형 프롬프트를 설계할 때는 필수 입력에는 플래그를 우선하고, 프롬프트는 주로 선택적 선택지나 안내형 다단계 프로세스에 사용해요.

핵심 고려 사항:

기본값 (Default values)

일반적인 사용 사례나 합리적인 대안을 바탕으로 기본값을 선택해요.

기본값을 명확히 하고, 도움말 텍스트에 숨기거나 사용자가 안다고 가정하지 않아요.
기본값을 시각적으로 명확히 표시해요(예: [default], (default) 또는 (Y/n)/(y/N)).
목록을 사용한다면 첫 번째 항목 기본값이 정말 가장 일반적인 선택인지 확인해요.
입력을 비워 두면 Enter가 기본값을 수락한다는 점을 설명해요.
프롬프트 뒤에 기본값이었더라도 선택된 값을 로그/에코로 확인해요.

명확성 (Clarity)

프롬프트를 최대한 명확하게 해요.

프롬프트를 질문 형태로 작성해요.
예: "Enable autoscaling? (Y/n)"
프롬프트에 응답하는 것이 선택적인지 명확히 밝혀요.
유용한 곳에는 인라인 도움말을 제공해요.
예: "Output directory [? for help]"
지나치게 많은 프롬프트를 연쇄적으로 이어 붙이는 것을 피해요.
적절할 때 선택적 다음 단계를 포함해요(예: 상태 보기, 로그 열기).
명시적으로 요청하지 않는 한(--quiet 모드처럼) 조용한 성공을 피해요.

사용자 제어 (User control)

사용자가 자신의 CLI 경험을 제어할 수 있게 해요.

사용자가 다단계 대화형 흐름을 의도적으로 실행하게 하려면 --guided 플래그 사용을 고려해요.
사용자가 --non-interactive나 --yes 플래그로 프롬프트를 건너뛸 수 있게 해요.
사용자가 Ctrl+C 같은 명령으로 흐름을 일찍 취소하거나 종료할 수 있게 해요.

예시 (Example)

Welcome! Let's configure your project.

Project name: my-app
Language (js, py, go) [py]: 
Use Docker? (y/N): y

✅ Project "my-app" configured successfully.

Choose deployment region:
[1] US East (N. Virginia)
[2] US West (Oregon) (default)
[3] Europe (Frankfurt)

Enable telemetry? (y/N)

Select output format (default = 'json') [Use arrows to move, type to filter, ? for help]:

명령줄 인터페이스 핸드북