CLI 인증 옵션

ant CLI는 여러 자격 증명 소스를 지원합니다. 빠른 시작에서는 명령 하나로 끝나는 기본 경로(ant auth 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을 실행하세요.

관리자 액세스

기본적으로 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에서 키를 발급받으세요.

echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.zshrc
source ~/.zshrc

단일 호출에 대해 키를 재정의하려면 --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 \
  --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]       sk-ant-oat01-EXA...
...

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 참조를 참조하세요.

다음 단계