Afi - Habilidad para Claude Code

Requisitos previos: Instalar la CLI

Esta habilidad utiliza el binario afi-cli. Debes verificar que la CLI esté instalada antes de invocar cualquier comando de esta habilidad. Si no está presente, instálala primero:

macOS / Linux:

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

Windows (PowerShell):

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

Verifica: afi-cli --version
Asegúrate de que ~/.local/bin (macOS / Linux) o %LOCALAPPDATA%\Programs\msp-skills (Windows) estén en $PATH.

El instalador descarga los binarios afi-cli y afi-mcp en ~/.local/bin (macOS / Linux) o %LOCALAPPDATA%\Programs\msp-skills (Windows). No registra la habilidad con tu agente ni escribe configuración de cliente MCP; consulta mcp-install.md para esa configuración.

Si --version informa "command not found" después de la instalación, el entorno de ejecución no puede ver el directorio de los binarios en $PATH. No continúes con los comandos de la habilidad hasta que la verificación sea exitosa.

Una CLI y servidor MCP de código abierto para Afi, cuyo proveedor desaconseja explícitamente las consultas periódicas a la API. Esta CLI recorre toda la jerarquía en una base de datos SQLite local una sola vez (fleet-sync), luego responde preguntas a nivel de flota (brechas de cobertura, estado de la flota, copias de seguridad obsoletas, conciliación de licencias) sin conexión. Un comando de desvinculación protegido ejecuta la secuencia de archivado y liberación del propio proveedor con una comprobación de verificación que no está disponible en el portal.

Cuándo usar esta CLI

Usa esta CLI para cualquier pregunta programática sobre flotas de copia de seguridad SaaS de Afi: cobertura de copias de seguridad, estado de las tareas nocturnas, infracciones de cuotas, antigüedad de archivos, conciliación de licencias y la secuencia protegida de archivado y desvinculación para empleados que se van. Es la opción correcta para preguntas a escala de MSP en muchos inquilinos, donde el portal obliga a recorrer cada inquilino y la API con límite de tasa penaliza las consultas repetitivas: sincroniza una vez y luego consulta el almacén local.

Anti-desencadenantes

No uses esta CLI para:

Realizar restauraciones, exportaciones o navegar por datos de copia de seguridad reales: la API pública de Afi no expone el inicio de restauración/exportación ni la descarga de datos; usa el portal web de Afi
Crear o editar políticas de copia de seguridad: las políticas son de solo lectura en la API pública; configúralas en el portal
Monitoreo en tiempo real o consulta continua del estado de las tareas: Afi limita explícitamente y puede suspender aplicaciones de consulta; usa sincronizaciones programadas
Gestionar cuentas de usuario del portal de Afi, SSO o configuraciones de notificaciones: no forman parte de la superficie de la API pública

Capacidades Únicas

Estas capacidades no están disponibles en ninguna otra herramienta para esta API.

Estado local que se acumula

fleet-sync: Recorre toda la jerarquía de Afi (instalaciones, organizaciones, inquilinos, y luego los recursos, protecciones, políticas, archivos, cuotas y estadísticas de tareas de cada inquilino) en una base de datos SQLite local en una sola pasada respetuosa.

Ejecuta esto primero (y de forma programada): cada pregunta posterior sobre la flota (cobertura, antigüedad, licencias, tarjetas de puntuación) se responde sin conexión sin alcanzar los límites de tasa de Afi.
```
afi-cli fleet-sync
```
coverage-gaps: Busca recursos en un inquilino que no tienen ninguna protección de copia de seguridad aplicada: los puntos ciegos de la copia de seguridad.

Recurre a esto cuando se te pregunte si cada buzón, sitio o unidad realmente está siendo respaldado: responde preguntas de cobertura de flota que la API no puede.
```
afi-cli coverage-gaps --tenant 01F000000000000411Z1101G1Y --agent
```
fleet-health: Una tabla en todos los inquilinos sincronizados: recuentos de tareas exitosas/fallidas, lista de tareas fallidas e infracciones de cuotas.

Usa esto para el barrido del lunes por la mañana '¿está toda la flota en verde?' en lugar de recorrer los inquilinos una pestaña del portal a la vez.
```
afi-cli fleet-health --since 24h --agent
```
resolve: Asigna un ID de Microsoft 365 / Google Workspace, correo electrónico o nombre al recurso o inquilino canónico de Afi, incluida la expansión Multi-Geo.

Ejecuta esto antes de cualquier desvinculación o auditoría para estar seguro de qué objeto de Afi corresponde a una identidad de un sistema externo.
```
afi-cli resolve [email protected] --agent
```
reconcile-licenses: Compara las cantidades de suscripciones adquiridas con los recuentos de recursos realmente protegidos por inquilino para señalar el exceso o la falta de aprovisionamiento.

Usa esto para la verificación semanal de desviación de licencias que hoy requiere unir hojas de cálculo manualmente en dos pantallas del portal.
```
afi-cli reconcile-licenses --org 01F0ORG0000000000000000000 --json
```
backup-stale: Señala los recursos protegidos cuyo archivo de copia de seguridad más reciente es más antiguo que un umbral: recursos protegidos pero que fallan silenciosamente.

Usa esto para detectar la clase de fallo silencioso: recursos que tienen una política adjunta pero cuyas copias de seguridad dejaron de ejecutarse sin previo aviso.
```
afi-cli backup-stale --max-age 48h --agent
```
tenant-scorecard: La postura completa de copia de seguridad de un inquilino: porcentaje de cobertura, estado de la última tarea, antigüedad del archivo más nuevo/más antiguo y estado de la cuota.

Genera esta tarjeta cuando prepares un ticket de cliente o una revisión trimestral (QBR): el análisis profundo por inquilino que complementa fleet-health.
```
afi-cli tenant-scorecard 01F000000000000411Z1101G1Y --agent --select tenant_id,coverage_pct,quotas_exceeded
```

Flujos de trabajo protegidos

offboard: Realiza una copia de seguridad segura del recurso de un usuario que se va, verifica que el archivo se haya creado correctamente y luego libera la protección, negándose a realizar el paso irreversible hasta que se confirme la copia de seguridad.

Usa esto al desvincular a un empleado para que la copia de seguridad final se verifique antes de liberar la licencia de M365/GWS: nunca pierdas los datos de un empleado que se va.
```
afi-cli offboard 01F0RESOURCE0000000000000A --tenant 01F0TENANT00000000000000B --policy 01F0POLICY000000000000000C --reason "employee departure"
```

Referencia de comandos

applications: Gestionar aplicaciones

afi-cli applications: Lista las instalaciones de la aplicación identificada por la clave de autenticación.

orgs: Gestionar organizaciones

afi-cli orgs create: Crea una nueva organización hija.
afi-cli orgs get: Recupera una organización por su ID.

tenants: Gestionar inquilinos

afi-cli tenants <id>: Recupera un inquilino por su ID.

Encontrar el comando correcto

Cuando sepas lo que quieres hacer pero no qué comando lo hace, pregunta directamente a la CLI:

  afi-cli which "<capacidad en tus propias palabras>"

which resuelve una consulta de capacidad en lenguaje natural al comando que mejor coincide del índice de funciones seleccionadas de esta CLI. El código de salida 0 significa al menos una coincidencia; el código de salida 2 significa que no hay una coincidencia segura: recurre a --help o usa una consulta más específica.

Recetas

Barrido de flota del lunes

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

Actualiza el almacén de la flota (saltando el pesado recorrido de archivos), luego lista solo los inquilinos con tareas fallidas o infracciones de cuotas.

Buscar puntos ciegos de copia de seguridad en un inquilino

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

LEFT JOIN de recursos contra protecciones, reducido a los tres campos que un agente necesita para abrir tickets.

Desvincular a un empleado que se va de forma segura

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

Resuelve el correo electrónico ambiguo al recurso canónico de Afi, luego previsualiza la secuencia protegida de copia de seguridad final, verificación y liberación antes de ejecutarla realmente.

Detectar copias de seguridad que fallan silenciosamente

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

Recursos protegidos cuyo archivo más reciente tiene más de dos días: la clase de fallo que ninguna pantalla del portal muestra.

Verificación de desviación de licencias

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

Cantidades de suscripciones adquiridas frente a recuentos de recursos realmente protegidos, por inquilino.

Configuración de autenticación

Crea una aplicación y una clave de API en el portal de Afi (nivel de organización: Configuración → Aplicaciones; nivel de inquilino: Servicio → Configuración → Aplicaciones), luego establece AFI_API_KEY. La clave se envía como el valor del encabezado Authorization sin procesar (las claves de Afi tienen el formato appkey-...; no se requiere el prefijo Bearer). Cada aplicación admite dos claves para rotación. Las claves heredan el ámbito de instalación de la aplicación: si falta un inquilino u organización en los resultados, verifica dónde está instalada la aplicación.

Ejecuta afi-cli doctor para verificar la configuración.

Modo agente

Agrega --agent a cualquier comando. Se expande a: --json --compact --no-input --no-color --yes.

Encadenable: JSON en la salida estándar, errores en la salida de error estándar
Filtrable: --select mantiene un subconjunto de campos. Las rutas con puntos descienden en estructuras anidadas; los arrays se recorren elemento por elemento. Es fundamental para mantener el contexto pequeño en API detalladas:
```
afi-cli orgs get <org-id> --agent --select id,name,status
```
Previsualizable: --dry-run muestra la solicitud sin enviarla
Amigable sin conexión: los comandos de sincronización/búsqueda pueden usar el almacén SQLite local cuando esté disponible
No interactivo: nunca solicita entrada, cada entrada es una bandera
Reintentos explícitos: usa --idempotent solo cuando una creación ya existente deba contar como éxito, y --ignore-missing solo cuando un objetivo de eliminación faltante deba contar como éxito

Sobre de respuesta

Los comandos que leen del almacén local o de la API envuelven la salida en un sobre de procedencia:

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

Analiza .results para los datos y .meta.source para saber si es en vivo o local. Un resumen legible por humanos de N resultados (en vivo) se imprime en la salida de error estándar solo cuando la salida estándar es una terminal Y no se establece ninguna bandera de formato de máquina (--json, --csv, --compact, --quiet, --plain, --select): los consumidores en tubería/agente y las ejecuciones con formato explícito obtienen JSON puro en la salida estándar.

Retroalimentación del agente

Cuando tú (o el agente) notes algo extraño en esta CLI, regístralo:

afi-cli feedback "la bandera --since es inclusiva pero la documentación dice exclusiva"
afi-cli feedback --stdin < notes.txt
afi-cli feedback list --json --limit 10

Las entradas se almacenan localmente en ~/.local/share/afi-cli/feedback.jsonl. Nunca se envían mediante POST a menos que AFI_FEEDBACK_ENDPOINT esté configurado Y se pase --send o AFI_FEEDBACK_AUTO_SEND=true. El comportamiento predeterminado es solo local.

Escribe lo que te sorprendió, no un informe de error. Corto, específico, una línea: esa es la parte que se acumula.

Entrega de resultados

Cada comando acepta --deliver <destino>. La salida se envía al destino nombrado además de (o en lugar de) la salida estándar, para que los agentes puedan enrutar los resultados de los comandos sin necesidad de tuberías manuales. Se admiten tres destinos:

Destino	Efecto
`stdout`	Predeterminado; escribe solo en la salida estándar
`file:<ruta>`	Escribe atómicamente la salida en `<ruta>` (archivo temporal + renombrar)
`webhook:<url>`	Envía el cuerpo de la salida mediante POST a la URL (`application/json` o `application/x-ndjson` cuando se usa `--compact`)

Los esquemas desconocidos se rechazan con un error estructurado que nombra el conjunto admitido. Las fallas de webhook devuelven un código distinto de cero y registran la URL + el estado HTTP en la salida de error estándar.

Perfiles con nombre

Un perfil es un conjunto guardado de valores de bandera, reutilizado en múltiples invocaciones. Úsalo cuando un agente programado llame al mismo comando cada vez con la misma configuración.

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

Las banderas explícitas siempre ganan a los valores del perfil; los valores del perfil ganan a los valores predeterminados. agent-context lista todos los perfiles disponibles bajo available_profiles para que los agentes de introspección los descubran en tiempo de ejecución.

Códigos de salida

Código	Significado
0	Éxito
2	Error de uso (argumentos incorrectos)
3	Recurso no encontrado
4	Autenticación requerida
5	Error de API (problema ascendente)
7	Límite de tasa alcanzado (esperar y reintentar)
10	Error de configuración

Análisis de argumentos

Analiza $ARGUMENTS:

Vacío, help o --help: muestra la salida de afi-cli --help
Comienza con install: termina con mcp → instalación de MCP; de lo contrario → consulta los requisitos previos anteriores
Cualquier otra cosa: Uso directo (ejecutar como comando CLI con --agent)

Instalación del servidor MCP

Instala el binario MCP (ejecuta el script de instalación de la sección de requisitos previos, o consulta mcp-install.md para la configuración por agente).
Regístrate con Claude Code:
```
claude mcp add afi-mcp -- afi-mcp
```
Verifica: claude mcp list

Uso directo

Verifica si está instalado: which afi-cli Si no se encuentra, ofrece instalar (consulta los requisitos previos al principio de esta habilidad).
Relaciona la consulta del usuario con el mejor comando de las Capacidades Únicas y la Referencia de comandos anteriores.

Ejecuta con la bandera --agent:

afi-cli <comando> [subcomando] [args] --agent

Si es ambiguo, profundiza en la ayuda del subcomando: afi-cli <comando> --help.

Servosity/afi

¿Qué es afi?

Preguntar en tu IA favorita

Documentación