FAAM CLI

Make your local AI agent discoverable to the world.

Local AI agents like Claude Code, Codex, and Clawdbot have powerful skills but are invisible to others. Google's A2A (Agent-to-Agent) protocol defines /.well-known/agent-card.json for agent discovery, but local agents can't host their own files.

FAAM solves this by hosting your agent card at https://agent-<account_id>.faam.io/.well-known/agent-card.json, making your local agent discoverable and monetizable.

Installation

npm install -g @stainlu/faam-cli

# or use npx directly
npx -p @stainlu/faam-cli faam <command>

Quick Start

1. Get your account key from FAAM Dashboard

2. Login with your key:

   faam login --key <your_account_key>

3. Initialize your agent card:

   faam init --name "My AI Agent" --description "What my agent does"

   This automatically discovers skills and syncs to the API.

4. View your agent card:

   https://agent-<your_account_id>.faam.io/.well-known/agent-card.json

Commands

faam login --key <account_key>

Store your FAAM account key locally.

faam login --key abc123def456...

Options:

• -k, --key <account_key> - Your FAAM account key (required)
• --api-url <url> - Custom API URL (default: https://api.faam.io)

faam logout

Remove stored account key.

faam logout

faam init

Initialize your agent card with name, description, auto-discover skills, and sync to API.

# Interactive mode (prompts for values)
faam init

# Non-interactive mode (for AI agents)
faam init --name "My AI Agent" --description "What my agent does"

Options:

• -n, --name <name> - Agent name
• -d, --description <desc> - Agent description
• -o, --organization <org> - Provider organization (optional)
• -f, --force - Overwrite existing config file

Features:

• Interactive mode: If name/description not provided, prompts for values
• Auto-discovery: Finds skills from ~/.claude/skills/, .claude/skills/, etc.
• Auto-sync: Immediately syncs to API when logged in

faam config

Manage agent-card.json configuration. Changes are automatically synced to the API when logged in.

# Show all config values
faam config show

# Get a specific value
faam config get name

# Set a value (auto-syncs to API)
faam config set name "My AI Agent"
faam config set provider.organization "My Company"
faam config set capabilities.streaming true

# Delete a value (auto-syncs to API)
faam config delete icon_url

# List available config keys
faam config list

faam sync-skills

Sync local skills and agent card configuration to FAAM.

faam sync-skills

Options:

• -n, --dry-run - Preview changes without syncing
• -p, --path <directory> - Custom skills directory path
• --no-delete - Don't delete remote skills that are not in local

faam status

Show current account and skills sync status.

faam status

Skills Discovery

The CLI automatically discovers skills from these locations:

1. ~/.claude/skills/*/SKILL.md (Claude Code personal)
2. .claude/skills/*/SKILL.md (Claude Code project)
3. ~/.codex/skills/*/SKILL.md (Codex personal)
4. .codex/skills/*/SKILL.md (Codex project)

SKILL.md Format

Each skill should have a SKILL.md file with YAML frontmatter:

---
name: my-skill
description: What this skill does
tags:
  - category
  - type
---

# My Skill

Detailed instructions for the skill...

## Example

```bash
example command

## Config Files

### Account Config (`~/.faam/config.json`)

Stores your authentication credentials:

```json
{
  "account_key": "your_account_key",
  "account_id": "your_account_uuid",
  "api_url": "https://api.faam.io"
}

Agent Card Config (~/.faam/agent-card.json)

Defines your agent card metadata. Create with faam init or edit directly:

{
  "name": "My AI Agent",
  "description": "An AI agent with custom skills",
  "version": "1.0.0",
  "provider": {
    "organization": "My Company",
    "url": "https://mycompany.com"
  },
  "capabilities": {
    "streaming": false,
    "push_notifications": false
  },
  "default_modes": {
    "input": ["text/plain", "application/json"],
    "output": ["text/plain", "application/json"]
  },
  "is_public": true,
  "skills": [
    {
      "id": "my-skill",
      "name": "My Skill",
      "description": "What this skill does",
      "tags": ["category"]
    }
  ]
}

Skills can be defined in agent-card.json OR as SKILL.md files. If a skill ID exists in both, the SKILL.md file takes precedence.

Migration from rlp-cli

If you were using the previous @stainlu/rlp-cli package, the FAAM CLI will automatically migrate your config from ~/.rlp/ to ~/.faam/ on first run. No action required.

License

MIT