@stainlu/faam-cli 0.2.0

package/README.md

@@ -0,0 +1,215 @@
+# 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
+
+```bash
+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](https://faam.io/dashboard?tab=agent)
+
+2. **Login with your key:**
+   ```bash
+   faam login --key <your_account_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_account_id>.faam.io/.well-known/agent-card.json
+   ```
+
+## Commands
+
+### `faam login --key <account_key>`
+
+Store your FAAM account key locally.
+
+```bash
+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.
+
+```bash
+faam logout
+```
+
+### `faam init`
+
+Initialize your agent card with name, description, auto-discover skills, and sync to API.
+
+```bash
+# 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.**
+
+```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 sync-skills`
+
+Sync local skills and agent card configuration to FAAM.
+
+```bash
+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.
+
+```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
+{
+  "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:
+
+```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.
+
+## 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