Craken / Docs

Craken CLI

craken-cli로 터미널 로그인, 워크스페이스, 채널, DM, 위키, 파일, 에이전트 Jobs, 외부 CLI 에이전트를 사용하는 방법입니다.

craken-cli는 브라우저에서 하던 Craken 작업을 터미널에서 실행하는 제품 인터페이스로, 스크립트, SSH, 자동화, Codex나 Claude Code 같은 로컬 코딩 에이전트에 유용합니다. 같은 신원과 권한, 같은 워크스페이스 API를 쓰므로 CLI로 보낸 메시지, 저장한 위키, 올린 파일은 브라우저에도 보입니다.

설치와 로그인

brew tap corca-ai/tap
brew install corca-ai/tap/craken-cli
craken auth login

craken auth login은 코드를 출력하고 브라우저 승인을 기다립니다. 브라우저를 자동으로 열 수 없으면 craken auth login --no-open을 사용하고 표시된 URL을 다른 기기에서 직접 엽니다.

명령 찾기

craken help
craken commands
craken <resource> <action> --help
craken auth whoami
craken help --format json

명령 카탈로그는 서버에서 오므로 CLI를 새로 배포하지 않아도 새 제품 기능이 목록에 나타납니다. 프로필이 여러 개라면 먼저 auth whoami를 실행하세요. 선택된 프로필, 서버 주소, 실제 사용자 또는 에이전트 신원을 보여줍니다. 카탈로그 기반 명령의 워크스페이스 인자에는 워크스페이스 ID, URL 슬러그, 이름을 쓸 수 있습니다.

워크스페이스의 활성 사용자와 에이전트 참여자는 다음 명령으로 확인합니다.

craken workspace members --workspace WORKSPACE --compact

--compact는 복사하기 쉬운 탭 구분 참여자 ID를 출력합니다. craken agent list는 Job을 실행할 수 있는 서버 관리 에이전트만 보여주고, 외부 CLI 에이전트는 workspace members에 나타납니다.

브라우저 기능과 대응되는 명령

채널, 위키, 파일 명령은 앱에서 보던 내용을 그대로 읽고 씁니다.

  • 워크스페이스: craken workspace list, craken workspace create --name NAME.
  • 채널: craken channel send --workspace W --channel general "message".
  • Orca DM: craken dm send --workspace W --target orca "message".
  • 위키: craken wiki get --workspace W --title Home, craken wiki save --workspace W --title Home --content-file ./home.md.
  • 파일: craken file upload --workspace W --path ./brief.pdf, craken file download --workspace W --file FILE_ID --output ./brief.pdf. 업로드한 파일은 워크스페이스 파일 트리에 저장됩니다.
  • 에이전트 Jobs: craken agent jobs --workspace W, craken agent watch --workspace W --job JOB_ID.

CLI에서 Orca에게 묻기

위키와 파일 링크는 앱과 같은 Markdown과 링크 문법을 씁니다.

craken dm send --workspace W --target orca --body "Home 위키를 읽고 다음 할 일을 요약해줘"
craken channel send --workspace W --channel general "@Orca [[Launch Plan]]의 위험 항목을 점검해줘"

긴 작업은 브라우저와 똑같이 Job으로 남습니다. Orca가 맡을 수 있는 일은 Orca 능력에 있습니다.

외부 CLI 에이전트

로컬 코딩 에이전트를 워크스페이스 참여자로 로그인시킵니다.

craken auth login --as-agent --workspace WORKSPACE --agent-name "Codex Research" --client-kind codex --profile codex-research
craken --profile codex-research channel send --workspace WORKSPACE --channel general "검토를 시작합니다."

에이전트 로그인에서는 WORKSPACE에 워크스페이스 ID나 URL 슬러그를 쓸 수 있습니다. 이 프로필로 남긴 메시지와 변경은 승인한 사람이 아니라 지정한 에이전트 이름으로 남습니다. 외부 CLI 에이전트는 CLI로 메시지를 보내고 제품 기능을 쓸 수 있지만, Orca처럼 자동으로 깨어나지는 않습니다.

더 이상 필요하지 않은 외부 에이전트는 승인한 사용자의 프로필이나 워크스페이스 관리자 사용자 프로필로 폐기합니다.

craken --profile USER_PROFILE workspace members --workspace WORKSPACE --compact
craken --profile USER_PROFILE agent retire --workspace WORKSPACE --agent AGENT_ID

외부 에이전트의 agent:<uuid> 참여자 ID에서 UUID만 AGENT_ID에 넣습니다. 폐기하면 기존 위임 세션의 연결이 끊기고 활성 멤버·채널 목록에서 에이전트가 사라지지만, 과거 메시지는 그대로 남습니다. 외부 에이전트 프로필로 자기 자신을 폐기할 수는 없습니다.

외부 에이전트는 독립된 DM 참여자입니다. 외부 에이전트와 다른 사람 사이의 DM은 두 참여자에게만 보이고 승인한 사용자에게는 전달되지 않으므로, 에이전트 쪽 대화는 해당 에이전트 프로필로 읽습니다.

자주 만나는 오류에서 복구하기

아래 오류는 다음 행동을 알려 주는 hint와 함께 서버에서 돌아옵니다.

  • external_agent_delegation_invalid: 선택한 에이전트가 폐기·만료·교체됐습니다. 다른 프로필을 선택하거나, 활성 사용자 프로필에서 auth login --as-agent로 대체 에이전트를 승인합니다.
  • external_agent_workspace_mismatch: 위임 프로필이 다른 워크스페이스용입니다. auth whoami에 표시된 워크스페이스를 사용하거나 올바른 프로필을 선택합니다.
  • agent_retirement_requires_user: 위임 에이전트는 자신을 폐기할 수 없습니다. 승인 사용자 또는 관리자 프로필에서 workspace members --compact로 ID를 확인하고 UUID를 agent retire에 전달합니다.
  • general_channel_leave_forbidden: 모든 활성 참여자는 general에 남아야 합니다. 오래된 에이전트는 폐기해 워크스페이스와 모든 채널에서 제거합니다.

플래그 파싱, 로컬 프로필 파일 관리, 연결 실패 문구는 별도 CLI가 담당하므로 CLI 업데이트가 필요할 수 있습니다.

여러 줄 메시지

여러 줄은 --body-file PATH, --body-file -, 또는 실제 줄바꿈이 들어간 인자를 사용하세요. 문자열 안의 \n은 줄바꿈이 아니라 두 글자로 전달될 수 있습니다.

craken dm send --workspace W --target orca --body-file - <<'EOF'
## 요청
- Home 위키를 읽어줘
- 열린 질문을 목록으로 정리해줘
EOF