Servosity/afi

Afi - Claude Code 스킬

필수 조건: CLI 설치

이 스킬은 afi-cli 바이너리를 사용합니다. 이 스킬의 명령어를 호출하기 전에 반드시 CLI가 설치되어 있는지 확인해야 합니다. 설치되어 있지 않다면 먼저 설치하세요:

1. macOS / Linux:

   bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/afi/install.sh)
   

2. Windows (PowerShell):

   iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/afi/install.ps1 | iex
   

3. 확인: afi-cli --version
4. ~/.local/bin (macOS / Linux) 또는 %LOCALAPPDATA%\Programs\msp-skills (Windows)이 $PATH에 있는지 확인하세요.

설치 프로그램은 afi-cli 및 afi-mcp 바이너리를 ~/.local/bin (macOS / Linux) 또는 %LOCALAPPDATA%\Programs\msp-skills (Windows)에 다운로드합니다. 에이전트에 스킬을 등록하지 않으며 MCP 클라이언트 설정을 작성하지 않습니다. 해당 설정은 mcp-install.md를 참조하세요.

--version이 설치 후 "command not found"를 보고하면 런타임이 $PATH에서 바이너리 디렉토리를 찾을 수 없는 것입니다. 확인에 성공할 때까지 스킬 명령어를 진행하지 마세요.

Afi를 위한 오픈 소스 CLI 및 MCP 서버로, 공급업체가 명시적으로 API 폴링을 권장하지 않습니다. 이 CLI는 전체 계층 구조를 한 번에 로컬 SQLite로 동기화(fleet-sync)한 후, 팟 전체 질문(커버리지 갭, 팟 상태, 백업 오래됨, 라이선스 조정)을 오프라인으로 답변합니다. 보호된 offboard 명령어는 공급업체의 자체 아카이브 후 해제 시퀀스를 포털에는 없는 검증 게이트와 함께 실행합니다.

이 CLI를 사용해야 하는 경우

Afi SaaS 백업 팟에 대한 모든 프로그래밍 방식 질문(백업 커버리지, 야간 작업 상태, 할당량 위반, 아카이브 오래됨, 라이선스 조정, 퇴사자를 위한 보호된 아카이브 및 오프보드 시퀀스)에 이 CLI를 사용하세요. 포털이 테넌트별로 하나씩 확인해야 하고 요율 제한이 있는 API가 폴링을 처벌하는 MSP 규모의 여러 테넌트 질문에 적합합니다. 한 번 동기화한 후 로컬 저장소를 쿼리하면 됩니다.

사용하지 말아야 할 경우

이 CLI를 다음 용도로 사용하지 마세요:

• 복원, 내보내기 또는 실제 백업 데이터 검색 - Afi 공개 API는 복원/내보내기 시작 또는 데이터 다운로드를 노출하지 않습니다. Afi 웹 포털을 사용하세요.
• 백업 정책 생성 또는 편집 - 공개 API에서 정책은 읽기 전용입니다. 포털에서 구성하세요.
• 작업 상태의 실시간 모니터링 또는 지속적 폴링 - Afi는 명시적으로 폴링 애플리케이션을 제한하고 일시 중단할 수 있습니다. 예약된 동기화를 대신 사용하세요.
• Afi 포털 사용자 계정, SSO 또는 알림 설정 관리 - 공개 API 표면의 일부가 아닙니다.

고유 기능

이러한 기능은 이 API를 위한 다른 도구에서는 사용할 수 없습니다.

누적되는 로컬 상태

• fleet-sync - 전체 Afi 계층 구조(설치, 조직, 테넌트, 각 테넌트의 리소스, 보호, 정책, 아카이브, 할당량, 작업 통계)를 한 번의 적절한 패스로 로컬 SQLite에 저장합니다.

  이것을 먼저 실행하고 (스케줄에 따라) 정기적으로 실행하세요: 이후의 모든 팟 질문(커버리지, 오래됨, 라이선스, 성과표)은 Afi의 요율 제한에 걸리지 않고 오프라인으로 답변합니다.

  afi-cli fleet-sync
  

• coverage-gaps - 테넌트에서 백업 보호가 적용되지 않은 리소스를 찾습니다. - 백업 사각지대입니다.

  모든 사서함, 사이트 또는 드라이브가 실제로 백업되고 있는지 물을 때 사용하세요. API가 제공할 수 없는 팟 커버리지 질문에 답변합니다.

  afi-cli coverage-gaps --tenant 01F000000000000411Z1101G1Y --agent
  

• fleet-health - 모든 동기화된 테넌트에 대한 단일 테이블: 작업 성공/실패 횟수, 실패한 작업 목록, 할당량 위반.

  포털 탭을 하나씩 확인하는 대신 '월요일 아침 전체 팟이 정상인가' 확인에 사용하세요.

  afi-cli fleet-health --since 24h --agent
  

• resolve - Microsoft 365 / Google Workspace ID, 이메일 또는 이름을 정식 Afi 리소스 또는 테넌트에 매핑합니다. Multi-Geo 팬아웃을 포함합니다.

  오프보드 또는 감사 전에 어떤 Afi 객체가 외부 시스템 ID에 해당하는지 확실히 하기 위해 실행하세요.

  afi-cli resolve [email protected] --agent
  

• reconcile-licenses - 구매한 구독 수량을 테넌트별로 실제 보호된 리소스 수와 비교하여 과잉 및 부족 프로비저닝을 플래그합니다.

  현재 두 개의 포털 화면에서 수동 스프레드시트를 결합해야 하는 주간 라이선스 드리프트 검사에 사용하세요.

  afi-cli reconcile-licenses --org 01F0ORG0000000000000000000 --json
  

• backup-stale - 가장 최근 백업 아카이브가 임계값보다 오래된 보호된 리소스를 플래그합니다. - 보호되어 있지만 조용히 실패하는 리소스입니다.

  조용한 실패 클래스를 포착하는 데 사용하세요: 정책이 연결되어 있지만 백업이 조용히 중단된 리소스.

  afi-cli backup-stale --max-age 48h --agent
  

• tenant-scorecard - 단일 테넌트의 전체 백업 상태: 커버리지 비율, 마지막 작업 상태, 최신/가장 오래된 아카이브 기간, 할당량 상태.

  고객 티켓이나 QBR을 준비할 때 이 카드를 생성하세요. fleet-health를 보완하는 테넌트별 심층 분석입니다.

  afi-cli tenant-scorecard 01F000000000000411Z1101G1Y --agent --select tenant_id,coverage_pct,quotas_exceeded
  

보호된 워크플로우

• offboard - 퇴사하는 사용자의 리소스를 안전하게 백업하고, 아카이브가 도착했는지 확인한 다음, 보호를 해제합니다. 백업이 확인될 때까지 되돌릴 수 없는 단계를 거부합니다.

  직원을 오프보딩할 때 M365/GWS 시트가 해제되기 전에 최종 백업이 확인되도록 사용하세요. 퇴사자의 데이터를 절대 잃지 마십시오.

  afi-cli offboard 01F0RESOURCE0000000000000A --tenant 01F0TENANT00000000000000B --policy 01F0POLICY000000000000000C --reason "employee departure"
  

명령어 참조

applications - 애플리케이션 관리

• afi-cli applications - 인증 키로 식별된 애플리케이션의 설치 목록을 표시합니다.

orgs - 조직 관리

• afi-cli orgs create - 새 하위 조직을 생성합니다.
• afi-cli orgs get - ID로 조직을 검색합니다.

tenants - 테넌트 관리

• afi-cli tenants <id> - ID로 테넌트를 검색합니다.

올바른 명령어 찾기

수행하려는 작업은 알지만 어떤 명령어가 수행하는지 모를 때는 CLI에 직접 물어보세요:

ari-cli which "<자신의 언어로 된 기능>"

which는 자연어 기능 쿼리를 이 CLI의 선별된 기능 인덱스에서 가장 일치하는 명령어로 해석합니다. 종료 코드 0은 하나 이상 일치함을 의미하고, 종료 코드 2는 자신 있는 일치 항목이 없음을 의미합니다. --help로 대체하거나 더 좁은 쿼리를 사용하세요.

레시피

월요일 팟 점검

ari-cli fleet-sync --skip-archives && afi-cli fleet-health --failed-only --agent

팟 저장소를 새로 고친 다음(무거운 아카이브 워크는 건너뜀), 실패한 작업이나 할당량 위반이 있는 테넌트만 나열합니다.

한 테넌트의 백업 사각지대 찾기

ari-cli coverage-gaps --tenant 01F000000000000411Z1101G1Y --agent --select items.name,items.kind,items.external_id

리소스와 보호 간의 LEFT JOIN을 에이전트가 티켓을 열기 위해 필요한 세 가지 필드로 좁힙니다.

퇴사 직원 안전하게 오프보드

ari-cli resolve [email protected] && afi-cli offboard 01F0RESOURCE0000000000000A --tenant 01F0TENANT00000000000000B --policy 01F0POLICY000000000000000C --reason "employee departure" --dry-run

모호한 이메일을 정식 Afi 리소스로 해석한 다음, 실제로 실행하기 전에 보호된 최종 백업-확인-해제 시퀀스를 미리 봅니다.

조용히 실패하는 백업 포착

ari-cli backup-stale --max-age 48h --json

가장 최근 아카이브가 이틀보다 오래된 보호된 리소스 - 어떤 포털 화면에서도 표시되지 않는 실패 클래스입니다.

라이선스 드리프트 확인

ari-cli reconcile-licenses --org 01F0ORG0000000000000000000 --json

구매한 구독 수량과 실제 보호된 리소스 수를 테넌트별로 비교합니다.

인증 설정

Afi 포털에서 애플리케이션 및 API 키를 생성하고(조직 수준: 구성 → 앱; 테넌트 수준: 서비스 → 설정 → 앱), AFI_API_KEY를 설정하세요. 키는 원시 Authorization 헤더 값으로 전송됩니다(Afi 키는 appkey-...처럼 보입니다. Bearer 접두사 없음). 각 애플리케이션은 교체를 위해 두 개의 키를 지원합니다. 키는 애플리케이션의 설치 범위를 상속받습니다. 결과에서 테넌트나 조직이 누락된 경우 애플리케이션이 설치된 위치를 확인하세요.

afi-cli doctor를 실행하여 설정을 확인하세요.

에이전트 모드

모든 명령어에 --agent를 추가하세요. 다음과 같이 확장됩니다: --json --compact --no-input --no-color --yes.

• 파이프 가능 - stdout에 JSON, stderr에 오류

• 필터 가능 - --select는 필드의 하위 집합을 유지합니다. 점으로 구분된 경로는 중첩 구조로 내려가고, 배열은 요소별로 순회합니다. 자세한 API에서 컨텍스트를 작게 유지하는 데 중요합니다:

  afi-cli orgs get <org-id> --agent --select id,name,status
  

• 미리 보기 가능 - --dry-run은 요청을 보내지 않고 표시합니다

• 오프라인 친화적 - sync/search 명령어는 사용 가능한 경우 로컬 SQLite 저장소를 사용할 수 있습니다

• 비대화형 - 프롬프트가 없으며 모든 입력은 플래그입니다

• 명시적 재시도 - --idempotent는 이미 존재하는 생성이 성공으로 간주되어야 하는 경우에만 사용하고, --ignore-missing은 누락된 삭제 대상이 성공으로 간주되어야 하는 경우에만 사용하세요

응답 봉투

로컬 저장소 또는 API에서 읽는 명령어는 출력을 출처 봉투에 래핑합니다:

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

데이터는 .results에서 구문 분석하고, .meta.source에서 실시간인지 로컬인지 확인하세요. 사람이 읽을 수 있는 N results (live) 요약은 stdout이 터미널이고 기계 형식 플래그(--json, --csv, --compact, --quiet, --plain, --select)가 설정되지 않은 경우에만 stderr로 출력됩니다. 파이프/에이전트 소비자와 명시적 형식 실행은 stdout에 순수 JSON을 얻습니다.

에이전트 피드백

사용자(또는 에이전트)가 이 CLI에서 이상한 점을 발견하면 기록하세요:

ari-cli feedback "the --since flag is inclusive but docs say exclusive"
ari-cli feedback --stdin < notes.txt
ari-cli feedback list --json --limit 10

항목은 ~/.local/share/afi-cli/feedback.jsonl에 로컬로 저장됩니다. AFI_FEEDBACK_ENDPOINT가 설정되고 --send가 전달되거나 AFI_FEEDBACK_AUTO_SEND=true인 경우에만 POST됩니다. 기본 동작은 로컬 전용입니다.

버그 보고서가 아니라 놀랐던 점을 작성하세요. 짧고, 구체적이며, 한 줄로: 그것이 누적되는 부분입니다.

출력 전달

모든 명령어는 --deliver <sink>를 허용합니다. 출력은 stdout 외에도(또는 대신) 명명된 싱크로 전송되므로 에이전트가 수동 파이핑 없이 명령어 결과를 라우팅할 수 있습니다. 세 가지 싱크가 지원됩니다:

싱크	효과
stdout	기본값; stdout에만 작성
file:<path>	출력을 원자적으로 <path>에 작성(tmp + 이름 변경)
webhook:<url>	출력 본문을 URL에 POST(application/json 또는 --compact일 때 application/x-ndjson)

알 수 없는 체계는 지원되는 세트를 명명하는 구조화된 오류와 함께 거부됩니다. 웹훅 실패는 0이 아닌 값을 반환하고 stderr에 URL + HTTP 상태를 기록합니다.

명명된 프로필

프로필은 저장된 플래그 값 세트로, 여러 호출에서 재사용됩니다. 예약된 에이전트가 매번 동일한 구성으로 동일한 명령어를 호출할 때 사용하세요.

ari-cli profile save briefing --json
ari-cli --profile briefing orgs get <org-id>
ari-cli profile list --json
ari-cli profile show briefing
ari-cli profile delete briefing --yes

명시적 플래그는 항상 프로필 값보다 우선하고, 프로필 값은 기본값보다 우선합니다. agent-context는 사용 가능한 모든 프로필을 available_profiles 아래에 나열하므로 내부 검사 에이전트가 런타임에 이를 발견합니다.

종료 코드

코드	의미
0	성공
2	사용법 오류(잘못된 인수)
3	리소스를 찾을 수 없음
4	인증 필요
5	API 오류(상위 문제)
7	요율 제한됨(대기 후 재시도)
10	구성 오류

인수 구문 분석

$ARGUMENTS 구문 분석:

1. 비어 있음, help 또는 --help → afi-cli --help 출력 표시
2. install로 시작함 → mcp로 끝남 → MCP 설치; 그렇지 않으면 → 위의 필수 조건 참조
3. 기타 → 직접 사용 (CLI 명령어로 --agent와 함께 실행)

MCP 서버 설치

1. MCP 바이너리 설치(필수 조건 섹션의 설치 스크립트 실행, 또는 에이전트별 설정은 mcp-install.md 참조).
2. Claude Code에 등록:

   claude mcp add afi-mcp -- afi-mcp
   

3. 확인: claude mcp list

직접 사용

1. 설치 여부 확인: which afi-cli 찾을 수 없으면 설치를 제안합니다(이 스킬 상단의 필수 조건 참조).
2. 사용자 쿼리를 위의 고유 기능 및 명령어 참조에서 가장 적합한 명령어와 일치시킵니다.
3. --agent 플래그와 함께 실행:

   afi-cli <command> [subcommand] [args] --agent
   

4. 모호한 경우 하위 명령어 도움말로 드릴다운: afi-cli <command> --help.