CLI 인증 옵션
CLI 인증 옵션
ant CLI를 대화형 로그인, API 키, 이름 붙은 프로파일, Workload Identity Federation으로 인증하는 방법을 알아보아요. 퀵스타트는 한 줄로 끝나는 행복한 경로(ant auth login)를 다루고, 이 페이지는 모든 옵션을 완전하게 설명해요.
출처: 문서
본문
대화형 로그인 (Interactive login)
ant auth login은 API 키를 만들거나 관리하지 않고도 API를 호출할 수 있게 해 줘요. Claude Console을 대상으로 브라우저 기반 OAuth 흐름을 열고, 결과로 나온 자격 증명을 $ANTHROPIC_CONFIG_DIR 아래에 저장해요(OS별 기본값은 설정 디렉터리 참고). 로컬 브라우저가 없는 원격 호스트나 환경에서는 --no-browser를 넘기면 인증 URL을 출력하고, 반환된 코드를 터미널에 다시 붙여넣으면 돼요.
ant auth login
# 브라우저가 없는 원격 호스트에서는:
ant auth login --no-browser
# 특정 워크스페이스에 바인딩하고 브라우저 선택기를 건너뛰려면:
ant auth login --workspace-id wrkspc_01...
# --profile로 넘기는 이름 붙은 프로파일이 없다면,
# 그 이름으로 새 프로파일이 만들어져요.
ant auth login --profile <profile-name>
브라우저 흐름 동안 조직을 고르고, 이어서 워크스페이스를 고르게 돼요. 발급된 토큰은 그 워크스페이스로 범위가 지정되므로, CLI는 그 워크스페이스에 속한 리소스만 볼 수 있어요. --workspace-id를 넘기면 바로 바인딩하고 선택기를 건너뛰어요. 두 개 이상의 워크스페이스에서 작업하려면 워크스페이스 전환하기를 참고하세요.
대화형 로그인은 여러분 머신에서의 로컬 개발과 스크립팅을 위한 것이에요. CI, 서버, 컨테이너 같은 비대화형 워크로드에는 Workload Identity Federation을 대신 사용하세요.
로그인은 credentials/<profile>.json에 자격 증명을 써요. 한 프로파일에 대한 첫 로그인은 configs/<profile>.json도 만들고 활성 프로파일로 설정해요. 저장된 자격 증명을 지우려면 ant auth logout을, 모든 프로파일을 지우려면 ant auth logout --all을 실행하세요.
관리자 액세스 (Admin access)
기본적으로 ant auth login은 워크스페이스 범위의 토큰을 요청해요. Admin API 페이지에 문서화된 리소스를 관리하려면 별도 프로파일에서 org:admin 범위를 요청하세요:
ant auth login --profile admin --scope "org:admin"
# Authorization 헤더용 bearer 토큰을 출력하려면:
ant auth print-credentials --profile admin --access-token
org:admin 범위는 admin, owner, primary owner 역할을 가진 조직 구성원에게만 부여돼요. 발급된 토큰은 조직 전역 액세스를 가지며, 프로파일의 워크스페이스 바인딩으로 제약되지 않아요. 관리자 프로파일은 일상 프로파일과 분리해 두어서, 일상 명령이 높은 권한으로 실행되지 않게 하세요.
API 키
CLI는 ANTHROPIC_API_KEY 환경 변수에서도 API 키를 읽어요. 키는 Claude Console에서 받을 수 있어요.
변경 사항을 적용하려면 새 터미널을 여세요.
단일 호출에만 키를 덮어쓰려면 --api-key를 넘기세요. 다른 API 호스트를 가리키려면 ANTHROPIC_BASE_URL을 설정하거나 --base-url을 넘기세요.
개인 또는 서비스 계정 키처럼 여러 워크스페이스로 범위가 지정된 API 키를 쓴다면, 명령을 실행할 워크스페이스를 지정해야 해요. CLI가 자동으로 읽는 ANTHROPIC_WORKSPACE_ID 환경 변수를 설정하거나, --workspace-id 플래그를 쓰면 돼요. 값은 반드시 wrkspc_... ID여야 해요. SDK가 페더레이션 토큰 교환에서 ANTHROPIC_WORKSPACE_ID에 받아들이는 default라는 글자 그대로의 값은 여기서 유효하지 않아요.
ant messages create \
--workspace-id wrkspc_01... \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello, Claude"}'
인증 상태 확인하기
ant auth status는 CLI가 선택한 자격 증명 소스(API 키 환경 변수, OAuth 로그인, 페더레이션, 프로파일), 활성 프로파일, 활성 토큰이 바인딩된 워크스페이스, 설정 디렉터리 경로를 출력해요. 워크로드가 잘못된 자격 증명이나 워크스페이스를 선택했을 때 원인을 진단하는 데 써요.
ant auth status
Active profile: default
Config dir: ~/.config/anthropic
Profile config: ~/.config/anthropic/configs/default.json
Credentials: ~/.config/anthropic/credentials/default.json
Credentials
(active) * Profile (user_oauth) [via active_config] «redacted:sk-…»...
...
Workspace
(active) * Workspace wrkspc_01... (Engineering)
(active) 행을 읽어 어떤 자격 증명 소스와 워크스페이스가 승리했는지 알 수 있어요. 이 명령은 상태를 보고하지 건강 검사를 수행하지 않으므로, 종료 상태로 스크립팅하지 마세요. 자격 증명 소스의 전체 순서는 자격 증명 우선순위를 참고하세요.
워크스페이스 전환하기
대화형 로그인 토큰은 단일 워크스페이스에 바인딩돼요. 두 개 이상의 워크스페이스에서 CLI를 쓰려면 각각을 자기 이름 붙은 프로파일로 로그인한 뒤 전환하세요:
# 1. 프로파일 만들기 (대화형; 브라우저에서 다른 워크스페이스를 고르거나
# --workspace-id로 선택기를 건너뜀):
# ant auth login --profile other-ws
# 2. 이후 명령의 기본값으로 만들기:
ant profile activate other-ws
# 3. 또는 기본값을 바꾸지 않고 단일 명령에 선택하기:
ant --profile other-ws models list
ANTHROPIC_PROFILE=other-ws ant models list
어느 프로파일과 워크스페이스가 활성인지 확인하려면 ant auth status를 실행하세요.
프로파일 관리하기
ant profile 하위 명령들은 프로파일 상태를 직접 조회하고 편집해요:
ant profile list
ant profile get --profile other-ws
ant profile set workspace_id wrkspc_01... --profile other-ws
ant profile set이 쓸 수 있는 키는 workspace_id, base_url, organization_id, scope, client_id, console_url이에요. workspace_id를 설정하면 대상 워크스페이스가 프로파일 설정에 기록되지만 이미 발급된 자격 증명을 다시 바인딩하지는 않아요. 새 워크스페이스용 토큰을 만들려면 그 프로파일 아래에서 ant auth login을 다시 실행하세요.
프로파일 파일 스키마와 페더레이션 블록은 프로파일 설정 파일을 참고하세요. Workload Identity Federation은 인증 개요와 WIF 레퍼런스를 참고하세요.