feastalytics/cli

Feast CLI

터미널에서 Feastalytics 플랫폼을 구동합니다. feast CLI는 인앱 AI 에이전트가 사용하는 것과 동일한 도구 표면(캠페인, 자동화, 오퍼, 퍼널, 멤버 프로그램)을 일반 명령어로 노출하며, 로그인한 사용자로 프로덕션 API를 호출합니다.

CLI는 어떤 도구가 존재하는지와 무엇을 받아들이는지에 대한 진실 공급원입니다. 도구 세트는 새 엔드포인트가 태그될 때마다 증가하므로, 가정하지 말고 항상 런타임에 탐색하세요. 당신의 역할은 올바른 도구를 선택하고, 올바른 조직에 범위를 지정하며, 유효한 입력을 전달하는 것입니다.

필수 조건

feast CLI가 설치되어 있고 PATH에 있어야 합니다:

npm install -g @feastalytics/cli    # 또는 임시로: npx @feastalytics/cli <command>

한 번 인증하세요 — 토큰은 ~/.config/feast-cli/credentials.json에 캐시되고 자동으로 갱신됩니다:

feast login                        # 브라우저를 열어 인증 (기본값)
feast login --password [username]  # 헤드리스 / CI: 사용자 이름 + 비밀번호 프롬프트, 브라우저 없음

명령어가 로그인되지 않았거나 세션이 만료되었다고 보고하면 feast login을 다시 실행하세요.

최신 상태 유지

CLI나 이 스킬 모두 자체 업데이트되지 않습니다. 명령어가 stderr에 업데이트 알림을 출력하면:

Update available: feast 0.1.1 → 0.2.0

둘 다 업데이트한 후, 사용자에게 한 줄로 수행했음을 알리세요:

npm install -g @feastalytics/cli@latest      # `feast`가 전역 설치로 PATH에 있는 경우에만
npx skills add feastalytics/cli -g -a '*' -y # 저장소에서 이 스킬을 새로고침

전역 설치 대신 npx를 통해 CLI를 호출해 왔다면 npm install -g를 건너뛰고 나머지 세션 동안 npx @feastalytics/cli@latest <command>를 대신 사용하세요 — npx는 그렇지 않으면 캐시된 복사본을 재사용합니다.

CLI를 업데이트할 때마다 스킬도 업데이트하세요. 둘은 같은 저장소에서 제공되지만 다른 트리거로 제공되므로, 새 CLI 버전은 일반적으로 이 스킬의 지침도 변경되었음을 의미합니다. 전역 설치가 권한 문제로 실패하면 sudo로 재시도하지 말고 사용자에게 알리고 npx @feastalytics/cli@latest로 대체하세요.

핵심 루프: 발견 → 설명 → 호출

도구 이름이나 입력 형태를 추측하지 마세요. 라이브 CLI를 내부 검사하세요:

feast tools                 # 사용 가능한 모든 도구, 해당 도메인, 변경 여부를 나열
feast describe <tool>       # 하나의 도구에 대한 전체 설명 + 입력 JSON 스키마
feast call <tool> --org <organizationId> --input '<json>'

익숙하지 않은 도구를 호출하기 전에 항상 describe하세요 — 스키마는 정확한 필수 필드를 알려주며, CLI는 전송 전에 --input을 로컬에서 검증하므로 잘못된 페이로드는 혼란스러운 서버 오류 대신 명확한 메시지와 함께 빠르게 실패합니다.

조직: API가 추측하지 못하게 하세요

대부분의 도구는 하나의 조직에 대해 작동합니다. 사용자는 종종 여러 조직에 속하므로, 어떤 대상을 지정할지가 중요하며 명시적이어야 합니다.

feast whoami                # 로그인한 사용자와 그들이 작업할 수 있는 모든 조직(이름 포함)을 표시

대상 조직을 --org <organizationId>로 전달하세요:

• 사용자가 조직을 명명하면 feast whoami로 ID를 확인하고 그 ID를 전달하세요.
• 사용자가 정확히 하나의 조직에 속하면 CLI가 자동으로 사용합니다 — 플래그가 필요 없습니다.
• 둘 이상의 조직에 속하고 --org를 생략하면 CLI는 거부하고 조직을 나열합니다(조용히 선택하는 대신). 이는 의도적입니다: 잘못된 조직에 대해 행동하는 것은 멈추고 묻는 것보다 더 나쁩니다. 이런 일이 발생하면 목록을 사용자에게 제시하고 어떤 것을 의미하는지 확인하세요.

읽기 vs. 쓰기

쿼리 도구(나열, 설명, 읽기)는 안전하고 읽기 전용입니다. 변경 도구(생성, 업데이트, 복제, 삭제, 적용)는 프로덕션 데이터를 변경합니다.

• 변경 사항은 명시적으로 --org가 필요합니다.
• 실행 전에 CLI는 서버 측에서 조직을 확인하고 이름을 출력하므로, 잘못된 --org는 불투명한 ID 대신 잘못된 레스토랑으로 나타납니다. 해당 줄을 읽으세요.
• 확인 프롬프트가 없습니다. 호출하는 순간 변경 사항이 실행됩니다. 두 번 묻지 않으며, 취소할 수도 없습니다.

마지막 사항은 데이터베이스가 아닌 실제 세계에 도달하는 도구에 가장 중요합니다. 전화번호 구매는 계정에 청구됩니다. 크리에이터 방문 승인이나 제출 결정은 즉시 해당 사람에게 문자를 보내며 철회할 수 없습니다. 캠페인 게시는 실시간으로 적용되며, 반복 프로모션 가격 책정은 실제 Stripe 상품을 생성합니다. 자동화 편집 저장은 게스트가 받는 내용을 변경합니다. 이러한 것들을 되돌릴 수 없는 것으로 간주하고, 호출 전에 사용자의 의도를 정확히 파악하세요. 호출 후에는 게이트가 없기 때문입니다.

쓰기 전에 읽기를 선호하세요: 예를 들어 updateCampaign 전에 올바른 campaignId를 찾기 위해 listCampaigns를 사용하거나, 플로우 생성 전에 describe/listAutomationFlows를 사용하세요.

좋은 입력 구축하기

--input은 JSON 문자열(또는 더 큰 페이로드의 경우 --input-file <path>)을 사용합니다. describe를 통해 얻은 스키마에서 구축하세요. 도구가 다른 엔터티를 ID(캠페인 ID, 위치 ID, 플로우 ID)로 참조할 때는 관련 목록/읽기 도구로 먼저 해당 ID를 조회하고 임의로 생성하지 마세요.

필드의 도메인별 의미(자동화 체인 방식, 퍼널 화면 내용, 오퍼 구조)에 대해서는 스키마만으로 충분하지 않을 때 references/domains.md의 지침을 참조하세요.

워크플로우

많은 작업은 여러 단계로 이루어져 있으며 앱이 일반적으로 강제하는 순서가 있습니다. 가장 중요한 규칙: 자동화는 플로우 안에 존재합니다 — 자동화를 추가하기 전에 항상 플로우(listAutomationFlows)를 찾거나 생성(createAutomationFlow)하세요. 고아 자동화를 만들지 마세요. 동일한 "부모/ID를 먼저 확인하고, 그 다음에 행동" 패턴은 캠페인, 퍼널, 오퍼에서 반복됩니다.

다단계 작업을 수행하기 전에 해당 워크플로우 파일을 읽으세요. 각 파일에는 필요한 호출 순서와 결과를 단순히 유효한 것이 아니라 좋게 만드는 도메인 규칙이 포함되어 있습니다. 이는 도구 스키마에는 없습니다. 먼저 읽고, 도구 설명에서 순서를 재구성하지 마세요.

이 작업을 할 때	읽을 파일
캠페인 생성, 복제 또는 구성; 전략 백로그의 오퍼	references/workflows/campaigns.md
자동화와 관련된 모든 것 — 생성, 편집, 시뮬레이션, 드래프트 승격	references/workflows/automations.md
퍼널 화면 편집, 퍼널 템플릿 적용, 새 화면 스테이징	references/workflows/funnels.md
Meta 광고 카피 작성 — 게스트 대상 또는 크리에이터 모집	references/workflows/facebook.md
크리에이터 소싱 — 신청자 승인, 콘텐츠 검토, 대화	references/workflows/creators.md
멤버 프로그램 보상; 지갑 패스 구성 읽기 또는 저장	references/workflows/members-program.md
온보딩 작업 보드 작업; 브랜드 아이덴티티	references/workflows/onboarding.md
게스트/멤버 및 활동 검색	references/workflows/guests.md

작업이 여러 영역에 걸쳐 있으면 둘 이상을 읽으세요 — 새 캠페인은 일반적으로 campaigns.md와 automations.md, funnels.md를 의미합니다.

일부 작업은 의도적으로 노출되지 않습니다: 게스트나 크리에이터에게 SMS로 답장, 라이브 멤버에게 자동화 실행, 보상 업데이트/삭제, 패스 이미지 생성, 두 가지 승인 결정을 넘어서는 크리에이터 파이프라인의 대부분. 워크플로우 파일에 어떤 것이 있는지 나와 있습니다. feast tools에 나열되지 않은 도구에 대한 워크플로우 호출을 조작하지 말고 — 해당 부분을 아직 사용할 수 없다고 사용자에게 알리세요.

작업한 내용에 링크하기

CLI를 통해 수행한 작업은 제품 어딘가에 반영되며, 링크를 제공하는 것은 저렴한 제안입니다 — 자유롭게 제공하세요. 생성, 변경 또는 게시한 후에는 짧은 마크다운 목록으로 마무리하세요: 어디서 볼 수 있는지, 어디서 편집할 수 있는지, 어디서 미리 볼 수 있는지. 누군가 당신의 작업을 확인해야 하기 때문이 아니라, 보통 그 대상을 여는 것이 다음 단계이기 때문입니다. 누군가 무언가가 어디에 있는지 또는 어떻게 설정하는지 물을 때는 클릭별 안내보다는 링크로 먼저 안내하세요.

이 URL을 알지 못합니다 — 작성 전에 references/links.md를 읽으세요. 대시보드의 형태는 이 스킬의 다른 곳에 있는 게스트 대상 링크에서 추정할 수 있는 형태가 아니므로, 명백히 올바른 것처럼 보이는 URL이 바로 확인해야 할 경우입니다. 잘못된 링크는 링크가 없는 것보다 더 나쁩니다: 권위적으로 보이지만 404가 발생합니다.

해당 파일에는 패널 및 탭 이름이 있는 대시보드 라우트, 조직의 자체 하위 도메인에 있는 게스트 대상 페이지, 퍼널 드래프트 루프를 완료하는 미리보기 라우트, 그리고 실제로 분석을 억제하는 쿼리 매개변수와 방문을 단순히 미리보기로 태그하는 것의 차이가 있습니다.

작업 예시

사용자: "내 Plum Vietnamese 조직의 Plum 위치에 $5 할인 오퍼를 추가해 줘."

feast whoami                                    # Plum Vietnamese 조직 ID 찾기
feast describe dfyCreateOffer                    # 오퍼 입력 형태 배우기
feast call dfyGetMenuHierarchy --org <orgId> --input '{"locationId":"<id>"}'   # 위치/메뉴 ID 찾기
feast call dfyCreateOffer --org <orgId> --input '{ ... }'                       # 생성 (먼저 확인)

패턴은 일반화됩니다: 조직 식별, 도구 배우기, 참조된 ID 확인, 그 다음에 행동.

문제 발생 시

• "로그인되지 않음 / 세션 만료" → feast login (또는 헤드리스/CI 컨텍스트에서 feast login --password [username]).
• "여러 조직에 속해 있습니다" → feast whoami로 ID를 얻고 --org로 하나를 선택하세요.
• "입력이 도구 스키마와 일치하지 않습니다" → feast describe <tool>을 다시 읽고 명명된 필드를 수정하세요.
• 예상한 도구가 feast tools에 나열되지 않음 → 아직 노출되지 않았을 수 있습니다. 호출을 조작하지 말고 사용자에게 알리세요.