@stainlu/faam-cli 0.2.2 → 0.2.5

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 0.2.5 (2026-02-10)
+
+- `faam init` now works with zero arguments — name auto-generates, description optional
+- API no longer requires description for agent profile
+
+## 0.2.4 (2026-02-10)
+
+- Fix CI workflow (pin pnpm version)
+
+## 0.2.3 (2026-02-10)
+
+- Add npm badges, Security & Safety section, and install-skills docs to README
+- Add SECURITY.md and CHANGELOG.md
+- Add package metadata (homepage, author, bugs, funding, expanded keywords)
+- Set up GitHub Actions for npm provenance attestation
+- Fix license text in README (was incorrectly listed as MIT)
+
+## 0.2.2 (2026-02-09)
+
+- Dynamic version display (reads from package.json)
+- Fix `install-skills` authentication (use Bearer token)
+- Rebrand rlp → faam across all CLI output
+
+## 0.2.1 (2026-02-09)
+
+- Use Authorization header instead of query params for API requests
+
+## 0.2.0 (2026-02-08)
+
+- Add `install-skills` command — download personalized skills from FAAM
+- Add `config` command — manage agent card configuration
+- All-in-one `init` command with auto-discovery and auto-sync
+- Support for multiple agents: Claude Code, Codex, Cursor, OpenCode, Windsurf
+- Auto-migration from `~/.rlp/` to `~/.faam/`

package/README.md

@@ -1,5 +1,10 @@
 # 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.
@@ -59,24 +64,27 @@ faam logout
 
 ### `faam init`
 
-Initialize your agent card with name, description, auto-discover skills, and sync to API.
+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
-# Interactive mode (prompts for values)
+# Zero-config (auto-generates name, no description)
 faam init
 
-# Non-interactive mode (for AI agents)
+# 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
-- `-d, --description <desc>` - Agent description
+- `-n, --name <name>` - Agent name (default: `agent-<account_id>`)
+- `-d, --description <desc>` - Agent description (optional)
 - `-o, --organization <org>` - Provider organization (optional)
 - `-f, --force` - Overwrite existing config file
 
 **Features:**
-- **Interactive mode**: If name/description not provided, prompts for values
+- **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
 
@@ -116,6 +124,31 @@ Options:
 - `-p, --path <directory>` - Custom skills directory path
 - `--no-delete` - Don't delete remote skills that are not in local
 
+### `faam install-skills`
+
+Download your personalized skills from FAAM and save them locally. This is completely optional — it fetches SKILL.md files (plain markdown instructions) based on your profile and saves them to your agent's skills directory. No executable code is downloaded or run.
+
+```bash
+# Install to default agents (Claude Code + Codex)
+faam install-skills
+
+# Install to a specific agent
+faam install-skills --agent claude-code
+
+# Install to project directory instead of global
+faam install-skills --no-global
+
+# Overwrite existing skills
+faam install-skills --force
+```
+
+Options:
+- `--agent <name>` - Target agent (claude-code, codex, cursor, opencode, windsurf)
+- `--no-global` - Install to project directory instead of `~/`
+- `-f, --force` - Overwrite existing skill files
+
+Supported agents: `claude-code`, `codex`, `cursor`, `opencode`, `windsurf`
+
 ### `faam status`
 
 Show current account and skills sync status.
@@ -206,10 +239,33 @@ Defines your agent card metadata. Create with `faam init` or edit directly:
 
 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 account key and API URL
+- `agent-card.json` — your agent card metadata
+
+**What each command does**:
+- `sync-skills` — reads SKILL.md files from your local skills directories and uploads their metadata (name, description, tags) to the FAAM API
+- `install-skills` — downloads SKILL.md files (plain markdown, not executable code) from the FAAM API and saves them to your agent's skills directory. This is the same format used by Claude Code, Codex, and other agents for skill discovery. Skill installation is a standard pattern across AI coding agents.
+- `init` / `config` — manage local JSON configuration and sync to the API
+- `login` / `logout` — store or remove your account 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
 
-MIT
+Apache-2.0

package/SECURITY.md

@@ -0,0 +1,53 @@
+# Security Policy
+
+## Reporting Vulnerabilities
+
+If you discover a security vulnerability, please report it via:
+
+- **Email**: stainlu@newtype-ai.org
+- **GitHub Issues**: https://github.com/stainlu/faam/issues (for non-sensitive issues)
+
+We will acknowledge reports within 48 hours and aim to release fixes promptly.
+
+## Data Handling
+
+### What is stored locally
+
+All data is stored in `~/.faam/` as plain JSON:
+
+- `config.json` — account key and API URL
+- `agent-card.json` — agent card metadata (name, description, skills list)
+
+### What is transmitted
+
+- `sync-skills` sends skill metadata (name, description, tags) to `api.faam.io` over HTTPS
+- `install-skills` downloads SKILL.md content (plain markdown) from `api.faam.io` over HTTPS
+- All API requests use your account key for authentication via Bearer token
+
+### What is NOT transmitted
+
+- File contents outside of SKILL.md files
+- System information, environment variables, or telemetry
+- Any data without explicit user action (no background processes)
+
+## File System Access
+
+This CLI only accesses:
+
+- `~/.faam/` — configuration storage (read/write)
+- Agent skills directories — e.g. `~/.claude/skills/`, `~/.codex/skills/` (read for sync, write for install-skills)
+
+No other directories are read from or written to.
+
+## Dependencies
+
+This package uses a minimal set of well-known dependencies:
+
+- `commander` — CLI argument parsing
+- `chalk` — terminal colors
+- `ora` — terminal spinners
+- `prompts` — interactive prompts
+- `glob` — file pattern matching
+- `gray-matter` — YAML frontmatter parsing
+
+All dependencies are pinned and auditable.

package/dist/index.cjs

@@ -22215,7 +22215,7 @@ var import_prompts = __toESM(require_prompts3(), 1);
 async function initCommand(options2) {
   const configPath = getAgentCardConfigPath();
   if (agentCardConfigExists() && !options2.force) {
-    if (!process.stdin.isTTY || options2.name && options2.description) {
+    if (!process.stdin.isTTY || options2.name) {
       console.log(source_default.yellow("agent-card.json already exists at:"));
       console.log(source_default.gray(configPath));
       console.log();
@@ -22233,23 +22233,23 @@ async function initCommand(options2) {
       return;
     }
   }
-  const isInteractive2 = !(options2.name && options2.description) && process.stdin.isTTY;
+  const clientConfig = isLoggedIn() ? readConfig() : null;
+  const defaultName = clientConfig?.account_id ? `agent-${clientConfig.account_id}` : "My AI Agent";
+  const isInteractive2 = process.stdin.isTTY && !options2.name;
   let config;
   if (isInteractive2) {
     const response = await (0, import_prompts.default)([
       {
         type: "text",
         name: "name",
-        message: "Agent name",
-        initial: options2.name || "",
-        validate: (v) => v.length > 0 || "Name is required"
+        message: "Agent name (press Enter for default)",
+        initial: options2.name || defaultName
       },
       {
         type: "text",
         name: "description",
-        message: "Description",
-        initial: options2.description || "",
-        validate: (v) => v.length > 0 || "Description is required"
+        message: "Description (optional)",
+        initial: options2.description || ""
       },
       {
         type: "text",
@@ -22263,12 +22263,9 @@ async function initCommand(options2) {
         process.exit(0);
       }
     });
-    if (!response.name || !response.description) {
-      return;
-    }
     config = {
-      name: response.name,
-      description: response.description,
+      name: response.name || defaultName,
+      description: response.description || "",
       version: "1.0.0",
       provider: {
         organization: response.organization || "",
@@ -22285,16 +22282,9 @@ async function initCommand(options2) {
       is_public: true
     };
   } else {
-    if (!options2.name || !options2.description) {
-      console.log(source_default.red("Error: --name and --description are required in non-interactive mode."));
-      console.log();
-      console.log("Usage:");
-      console.log(source_default.cyan('  faam init --name "My Agent" --description "What my agent does"'));
-      process.exit(1);
-    }
     config = {
-      name: options2.name,
-      description: options2.description,
+      name: options2.name || defaultName,
+      description: options2.description || "",
       version: "1.0.0",
       provider: {
         organization: options2.organization || "",
@@ -22347,8 +22337,8 @@ async function initCommand(options2) {
   console.log();
   const syncSpinner = ora("Syncing to Faam...").start();
   try {
-    const clientConfig = readConfig();
-    const client = new RlpApiClient(clientConfig);
+    const syncConfig = clientConfig || readConfig();
+    const client = new RlpApiClient(syncConfig);
     const result = await syncToApi(client, config, fileSkills);
     syncSpinner.succeed("Synced successfully");
     if (result.created.length > 0) {
@@ -22365,7 +22355,7 @@ async function initCommand(options2) {
     }
     console.log();
     console.log("Your agent card is live at:");
-    console.log(source_default.cyan(`https://agent-${clientConfig.account_id}.faam.io/.well-known/agent-card.json`));
+    console.log(source_default.cyan(`https://agent-${syncConfig.account_id}.faam.io/.well-known/agent-card.json`));
     console.log();
     console.log("Go back to the onboarding page and click", source_default.bold('"Verify Setup"'), "to continue.");
   } catch (err) {
@@ -22487,7 +22477,7 @@ function configListKeysCommand() {
 
 // src/index.ts
 var program2 = new Command();
-program2.name("faam").description("CLI tool to sync local skills to your FAAM Agent Card").version("0.2.2");
+program2.name("faam").description("CLI tool to sync local skills to your FAAM Agent Card").version("0.2.5");
 program2.command("login").description("Store your FAAM account key").requiredOption("-k, --key <account_key>", "Your FAAM account key").option("--api-url <url>", "API URL (default: https://api.faam.io)").action(async (options2) => {
   await loginCommand({
     key: options2.key,

package/package.json

@@ -1,17 +1,12 @@
 {
   "name": "@stainlu/faam-cli",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "description": "CLI tool to sync local skills to your FAAM Agent Card",
   "type": "module",
   "bin": {
     "faam": "./dist/index.cjs",
     "faam-cli": "./dist/index.cjs"
   },
-  "scripts": {
-    "dev": "tsx src/index.ts",
-    "build": "tsup",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
@@ -30,19 +25,35 @@
     "node": ">=18"
   },
   "files": [
-    "dist"
+    "dist",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "faam",
     "agent",
     "skills",
     "cli",
-    "a2a"
+    "a2a",
+    "a2a-protocol",
+    "agent-card",
+    "ai-agent",
+    "google-a2a"
   ],
+  "author": "stainlu <stainlu@newtype-ai.org>",
   "license": "Apache-2.0",
+  "homepage": "https://faam.io",
+  "bugs": "https://github.com/stainlu/faam/issues",
+  "funding": "https://faam.io",
   "repository": {
     "type": "git",
     "url": "https://github.com/stainlu/faam.git",
     "directory": "apps/cli"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
   }
-}
+}