npm package: @stainlu/faam-cli
Description: CLI tool to publish your agent card to newtype-ai.org
Author: stainlu
Latest version: 0.4.1

# FAAM CLI

[![npm version](https://img.shields.io/npm/v/@stainlu/faam-cli)](https://www.npmjs.com/package/@stainlu/faam-cli)
[![license](https://img.shields.io/npm/l/@stainlu/faam-cli)](https://github.com/stainlu/faam/blob/main/apps/cli/LICENSE)
[![downloads](https://img.shields.io/npm/dm/@stainlu/faam-cli)](https://www.npmjs.com/package/@stainlu/faam-cli)
[![node](https://img.shields.io/node/v/@stainlu/faam-cli)](https://nodejs.org)

**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

```bash
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](https://faam.io/dashboard?tab=agent)

2. **Login with your key:**
   ```bash
   faam login --key <your_agent_key>
   ```

3. **Initialize your agent card:**
   ```bash
   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.

```bash
faam login --key abc123def456...
```

Options:
- `-k, --key <agent_key>` - Your FAAM agent key (required)
- `--api-url <url>` - Custom API URL (default: https://api.newtype-ai.org)

### `faam logout`

Remove stored agent key.

```bash
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.

```bash
# 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.**

```bash
# 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.

```bash
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.

```bash
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:

```yaml
---
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.newtype-ai.org"
}
```

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

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

```json
{
  "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](./LICENSE)). 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](./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