servosity/msp-skills/afi

Afi - Claude Code Skill

Prerequisites: Install the CLI

This skill drives the afi-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. macOS / Linux:

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

1. Windows (PowerShell):

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

1. Verify: afi-cli --version
2. Ensure ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows) is on $PATH.

The installer downloads the afi-cli and afi-mcp binaries into ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows). It does not register the skill with your agent and writes no MCP client config - see mcp-install.md for that wire-up.

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

An open-source CLI and MCP server for Afi, whose vendor explicitly discourages API polling. This CLI walks the whole hierarchy into local SQLite once (fleet-sync), then answers fleet-wide questions (coverage-gaps, fleet-health, backup-stale, reconcile-licenses) offline. A guarded offboard command runs the vendor's own archive-then-release sequence with a verification gate the portal lacks.

When to Use This CLI

Use this CLI for any programmatic question about Afi SaaS backup fleets: backup coverage, nightly task health, quota breaches, archive staleness, license reconciliation, and the guarded archive-and-offboard sequence for departing employees. It is the right choice for MSP-scale questions across many tenants, where the portal forces a per-tenant walk and the rate-limited API punishes polling - sync once, then query the local store.

Anti-triggers

Do not use this CLI for:

• Performing restores, exports, or browsing actual backup data - the Afi public API does not expose restore/export initiation or data download; use the Afi web portal
• Creating or editing backup policies - policies are read-only in the public API; configure them in the portal
• Real-time monitoring or continuous polling of task status - Afi explicitly throttles and may suspend polling applications; use scheduled syncs instead
• Managing Afi portal user accounts, SSO, or notification settings - not part of the public API surface

Unique Capabilities

These capabilities aren't available in any other tool for this API.

Local state that compounds

• `fleet-sync` - Walk the whole Afi hierarchy - installations, orgs, tenants, then each tenant's resources, protections, policies, archives, quotas, and task stats - into local SQLite in one respectful pass.

_Run this first (and on a schedule): every fleet question afterward - coverage, staleness, licensing, scorecards - answers offline without tripping Afi's rate limits._

``bash afi-cli fleet-sync ``

• `coverage-gaps` - Find resources in a tenant that have no backup protection applied - the backup blind spots.

_Reach for this when asked whether every mailbox, site, or drive is actually being backed up - it answers fleet-coverage questions one API can't._

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

• `fleet-health` - One table across all synced tenants: task success/failure counts, failed-task list, and quota breaches.

_Use this for the Monday-morning 'is the whole fleet green' sweep instead of walking tenants one portal tab at a time._

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

• `resolve` - Map a Microsoft 365 / Google Workspace ID, email, or name to the canonical Afi resource or tenant, including Multi-Geo fan-out.

_Run this before any offboard or audit to be certain which Afi object corresponds to an external-system identity._

``bash afi-cli resolve jane.doe@example.com --agent ``

• `reconcile-licenses` - Compare purchased subscription quantities against actually-protected resource counts per tenant to flag over- and under-provisioning.

_Use this for the weekly licensing drift check that today requires manual spreadsheet stitching across two portal screens._

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

• `backup-stale` - Flag protected resources that are not getting backed up (no archive at all, or no backup task finished in their tenant in the synced window) - protected-but-silently-failing resources.

_Use this to catch the silent-failure class: resources that have a policy attached but whose backups quietly stopped landing._

``bash afi-cli backup-stale --agent ``

• `tenant-scorecard` - One tenant's full backup posture: coverage percentage, last task status, newest/oldest archive age, and quota state.

_Generate this card when prepping a customer ticket or QBR - the per-tenant deep dive that complements fleet-health._

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

Guarded workflows

• `offboard` - Safely back up a departing user's resource, verify the archive landed, then release the protection - refusing the irreversible step until the backup is confirmed.

_Use this when offboarding an employee so the final backup is verified before the M365/GWS seat is released - never lose a leaver's data._

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

Command Reference

applications - Manage applications

• afi-cli applications - Lists installations for the application identified by the authentication key.

orgs - Manage orgs

• afi-cli orgs create - Creates a new child organization.
• afi-cli orgs get - Retrieves an organization by its ID.

tenants - Manage tenants

• afi-cli tenants <id> - Retrieves a tenant by its ID.

backup-stale

• afi-cli backup-stale - Flag protected resources that are not getting backed up (no archive at all, or no backup task finished in their tenant in the synced window) - protected-but-silently-failing resources.

coverage-gaps

• afi-cli coverage-gaps - Find resources in a tenant that have no backup protection applied - the backup blind spots.

fleet-health

• afi-cli fleet-health - One table across all synced tenants: task success/failure counts, failed-task list, and quota breaches.

fleet-sync

• afi-cli fleet-sync - Walk the whole Afi hierarchy - installations, orgs, tenants, then each tenant's resources, protections, policies, archives, quotas, and task stats - into local SQLite in one respectful pass.

offboard

• afi-cli offboard - Safely back up a departing user's resource, verify the archive landed, then release the protection - refusing the irreversible step until the backup is confirmed.

reconcile-licenses

• afi-cli reconcile-licenses - Compare purchased subscription quantities against actually-protected resource counts per tenant to flag over- and under-provisioning.

resolve

• afi-cli resolve - Map a Microsoft 365 / Google Workspace ID, email, or name to the canonical Afi resource or tenant, including Multi-Geo fan-out.

tenant-scorecard

• afi-cli tenant-scorecard - One tenant's full backup posture: coverage percentage, last task status, newest/oldest archive age, and quota state.

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

afi-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match - fall back to --help or use a narrower query. --json (and other machine formats) keep that exit-2 contract and write {"matches":[]} on stdout so agents can inspect the envelope without treating a miss as success.

Recipes

Monday fleet sweep

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

Refresh the fleet store (skipping the heavy archives walk), then list only the tenants with failed tasks or quota breaches.

Find backup blind spots in one tenant

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

LEFT JOIN of resources against protections, narrowed to the three fields an agent needs to open tickets.

Offboard a departed employee safely

afi-cli resolve jane.doe@example.com && afi-cli offboard 01F0RESOURCE0000000000000A --tenant 01F0TENANT00000000000000B --policy 01F0POLICY000000000000000C --reason "employee departure" --dry-run

Resolve the ambiguous email to the canonical Afi resource, then preview the guarded final-backup-verify-release sequence before running it for real.

Catch silently failing backups

afi-cli backup-stale --json

Protected resources with no archive at all, or in a tenant where no backup task finished in the synced window - the failure class no portal screen surfaces.

Licensing drift check

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

Purchased subscription quantities vs actually-protected resource counts, per tenant.

Auth Setup

Create an Application and API key in the Afi portal (org level: Configuration → Apps; tenant level: Service → Settings → Apps), then set AFI_API_KEY. The key is sent as the raw Authorization header value (Afi keys look like appkey-...; no Bearer prefix). Each Application supports two keys for rotation. Keys inherit the Application's installation scope - if a tenant or org is missing from results, check where the Application is installed.

Run afi-cli doctor to verify setup.

Credential safety

• The API key goes only to the Afi API host. AFI_API_KEY (sent raw in the Authorization header) goes only to the scheme, host and port of https://papi.afi.ai, or of AFI_BASE_URL when set. A redirect to any other host is refused, and a request that would carry the key anywhere but that header (a query value, an org name, another header) is refused before it is sent.
• Any output, file or MCP result that would repeat the key, or a credential-named value from a response, prints "[text withheld: it repeated a secret value this program holds]" in its place. Responses are never cached on disk, and credential-named fields are dropped before anything reaches the local store.
• Only credentials.toml (mode 0600) holds a credential; auth set-token reads the key from stdin, never from an argument.
• --dry-run sends nothing. Over MCP, every tool that changes Afi data (orgs_create, tenants_archives_delete, tenants_jobs_tasks-trigger, tenants_resources_protections-protect, tenants_resources_protections-unprotect, offboard) returns a preview and sends only with confirm: true, and a tool argument can never name a file to read or write (so import, which reads a local file, is CLI-only).

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color.

Global format flags share one contract on promoted, novel, sync, and --deliver paths: