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-<agent_id>.newtype-ai.org/.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 agent key from FAAM Dashboard

2. Login with your key:

   faam login --key <your_agent_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_agent_id>.newtype-ai.org/.well-known/agent-card.json

Commands

faam login --key <agent_key>

Store your FAAM agent key locally.

faam login --key abc123def456...

Options:

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

faam logout

Remove stored agent key.

faam logout

faam init

Initialize your agent card, auto-discover skills, and sync to API. Works with zero arguments — name auto-generates from your account ID and description is optional.

# Zero-config (auto-generates name, no description)
faam init

# With custom name
faam init --name "My AI Agent"

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

Options:

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

Features:

• Zero-config: Run faam init with no arguments — name auto-generates, description is optional
• 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 register

Publish your agent card to newtype-ai.org.

faam register

Options:

• -n, --dry-run - Preview changes without registering
• -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
{
  "agent_key": "your_agent_key",
  "agent_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.

Security & Safety

This CLI is fully open source (Apache-2.0). Here's exactly what it does and doesn't do:

Data stored locally (~/.faam/):

• config.json — your agent key and API URL
• agent-card.json — your agent card metadata

What each command does:

• register — reads SKILL.md files from your local skills directories and publishes their metadata (name, description, tags) to newtype-ai.org
• init / config — manage local JSON configuration and publish to newtype-ai.org
• login / logout — store or remove your agent key locally

What this CLI does NOT do:

• Run any downloaded code or scripts
• Install system packages or dependencies
• Access files outside of ~/.faam/ and your agent's skills directories
• Send telemetry or analytics
• Run background processes or auto-update

See SECURITY.md for our security policy.

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

Apache-2.0