@zeroclickai/zam-cli 0.3.15

package/hooks/auto-approve-zam.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# Auto-approve safe ZAM CLI read operations to reduce permission fatigue
+# This hook only auto-approves list/get/read operations - all modifications require permission
+
+# Read the input from stdin
+input=$(cat)
+
+# Extract tool name and command from the JSON input
+tool_name=$(echo "$input" | jq -r '.tool_name // empty')
+command=$(echo "$input" | jq -r '.tool_input.command // empty')
+
+# Only process Bash commands
+if [ "$tool_name" != "Bash" ]; then
+  exit 0
+fi
+
+# Only process zam CLI commands
+case "$command" in
+  zam\ *) ;;
+  *) exit 0 ;;
+esac
+
+# Check for destructive keywords first - never auto-approve these
+case "$command" in
+  *activate*|*run*|*create*|*update*|*delete*|*set-key*|*set-url*)
+    exit 0
+    ;;
+esac
+
+# Extract the subcommand (second word) for easier matching
+subcommand=$(echo "$command" | awk '{print $2}')
+action=$(echo "$command" | awk '{print $3}')
+
+case "$subcommand" in
+  # Search - always safe (public, no auth required)
+  search)
+    ;;
+
+  # Orders - only list and get are safe
+  orders)
+    case "$action" in
+      list|get)
+        ;;
+      *)
+        exit 0
+        ;;
+    esac
+    ;;
+
+  # OpenAPI spec - always safe
+  openapi)
+    ;;
+
+  # Config show - safe (just displays current config)
+  config)
+    case "$action" in
+      show)
+        ;;
+      *)
+        exit 0
+        ;;
+    esac
+    ;;
+
+  # Everything else requires manual approval
+  *)
+    exit 0
+    ;;
+esac
+
+# Command is safe - auto-approve it
+cat <<'EOF'
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "permissionDecisionReason": "ZAM read-only CLI operation auto-approved"
+  }
+}
+EOF
+
+exit 0

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@zeroclickai/zam-cli",
+	"version": "0.3.15",
+	"type": "module",
+	"bin": {
+		"zam": "bin/zam.js",
+		"zam-cli": "bin/zam.js"
+	},
+	"files": [
+		"bin",
+		"dist",
+		"skills",
+		"hooks"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsup src/index.ts --format esm --out-dir dist --clean",
+		"prepublishOnly": "pnpm run build",
+		"dev": "tsx src/index.ts",
+		"cli": "ZAM_API_URL=http://localhost:1111 tsx src/index.ts",
+		"test:integration": "vitest run --project integration",
+		"test:unit": "vitest run --project unit",
+		"test": "pnpm run test:integration",
+		"typecheck": "tsc"
+	},
+	"dependencies": {
+		"@clack/prompts": "^0.11.0",
+		"commander": "^13.0.0",
+		"open": "^11.0.0",
+		"posthog-node": "^5.28.5",
+		"ws": "^8.20.0",
+		"zod": "^4.3.5"
+	},
+	"devDependencies": {
+		"@types/node": "^25.0.7",
+		"@types/ws": "^8.18.1",
+		"msw": "^2.12.14",
+		"tsup": "^8.5.1",
+		"tsx": "^4.21.0",
+		"typescript": "^5.9.3",
+		"vitest": "^4.0.17"
+	}
+}

package/skills/zam-activate/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: zam-activate
+description: Activate ZAMs on the ZeroClick Agent Marketplace (ZAM) to execute APIs, tools, and services. Also check order status. Use when the user wants to use, run, call, or activate something from ZAM, or check on a previous order.
+metadata:
+  author: ZAM
+  version: "0.3.0"
+  category: marketplace
+---
+
+# Activate ZAMs
+
+Activate ZAMs on the marketplace to execute APIs, tools, and services. Check order status to monitor results.
+
+## When to Use This Skill
+
+- User wants to activate/use/run a ZAM
+- User wants to call an API or service discovered via search
+- User wants to check the status of a previous order
+- User asks "use ZAM to..." or "activate..."
+
+## Prerequisites Check
+
+1. Verify ZAM CLI is available:
+```bash
+zam --version
+```
+
+2. Verify API key is configured (required for activation):
+```bash
+zam config show
+```
+
+If no API key is set, either create an account or set a key manually:
+```bash
+# Create a new account (generates wallet + API key + recovery phrase)
+zam wallet create
+
+# Or set an existing key
+zam config set-key <your-api-key>
+```
+
+## Workflow
+
+**IMPORTANT: Always inspect the schema before activating.** Do not guess the request body format. The schema tells you exactly what fields are required, their types, and valid values.
+
+### Step 1: Search and inspect the schema
+
+**Option A: Search first, then inspect a specific result:**
+```bash
+zam search "what the user needs"
+zam inspect ZPWVPEHGYR
+```
+
+**Option B: Search with schemas inline:**
+```bash
+zam search "what the user needs" --show-schema
+```
+
+**Option C: Inspect by identifier (if you already have one):**
+```bash
+zam inspect ZPWVPEHGYR
+zam inspect ZGABC12345
+zam inspect send-sms
+```
+
+`zam inspect` returns the ZAM's full details including input/output schemas, pricing, and a ready-to-use activation command template. For machine-readable output, add `--json`.
+
+Read the `inputSchema` carefully. It tells you:
+- **Required fields** — what must be included in `--request-body`
+- **Field types** — string, number, boolean, object, array
+- **Enum values** — valid options for constrained fields
+- **Descriptions** — what each field means
+
+### Step 2: Build the request body from the schema
+
+Construct the `--request-body` JSON **using the exact field names from the schema**. Do not invent fields or guess names.
+
+```bash
+# Correct: uses exact field names from schema
+zam activate ZP1234 --request-body '{"to": "+15551234567", "message": "Hello!"}'
+
+# Wrong: guessed field names
+zam activate ZP1234 --request-body '{"phone": "+15551234567", "text": "Hello!"}'
+```
+
+### Step 3: Activate (with optional preflight)
+
+**For most ZAMs — activate directly:**
+```bash
+zam activate <identifier> --request-body '{"field": "value"}'
+```
+
+**For dynamic-priced ZAMs or when you want validation first — use preflight:**
+```bash
+zam activate <identifier> --request-body '{"field": "value"}' --preflight
+```
+
+Preflight validates your input with the seller and returns a price quote before charging. It's **mandatory** for ZAMs with `pricingModel: "dynamic"` (you'll get a 428 error without it).
+
+**One-step shortcut (search + activate):**
+```bash
+zam run "send a text" --request-body '{"to": "+15551234567", "message": "Hello!"}'
+```
+
+Only use `zam run` when you already know the schema from a previous search. If you're unsure about the schema, search first with `--show-schema`.
+
+### Step 4: Check Order Status
+
+If an activation timed out or you want to check a previous order:
+
+**List all your orders:**
+```bash
+zam orders list
+```
+
+**Get details for a specific order:**
+```bash
+zam orders get <order-id>
+```
+
+Order states:
+- **preflight** — seller validated input, awaiting buyer commitment (no charge)
+- **expired** — preflight token expired (2-minute TTL)
+- **pending** — order created, waiting to start
+- **running** — order is being processed
+- **completed** — order finished successfully (check `result` field)
+- **failed** — order encountered an error (check `errorMessage` field)
+
+### Preflight commands
+
+Standalone preflight check (without executing):
+
+```bash
+zam preflight <identifier> --request-body '{"field": "value"}'
+```
+
+Preflight + auto-commit in one step:
+
+```bash
+zam preflight <identifier> --request-body '{"field": "value"}' --commit
+```
+
+## Error Recovery
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| 400 | Request body doesn't match schema | Re-read schema with `zam search --show-schema`, fix field names/types |
+| 402 | Insufficient wallet balance | Run `zam wallet fund` to add funds |
+| 428 | ZAM requires preflight | Add `--preflight` flag to your activate command |
+| 429 | Seller rate limit hit | Wait and retry (check `Retry-After` header) |
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Inspect a specific ZAM | `zam inspect <id-or-zid-or-slug>` |
+| Inspect as JSON | `zam inspect <id> --json` |
+| Search + show schemas | `zam search "query" --show-schema` |
+| Search + activate (one step) | `zam run "query" --request-body '{"key":"val"}'` |
+| Activate by identifier | `zam activate <id-or-zid-or-slug> --request-body '...'` |
+| Activate with preflight | `zam activate <id> --request-body '...' --preflight` |
+| Activate with timeout | `zam activate <id> --request-body '...' --timeout 30` |
+| Preflight only (no execute) | `zam preflight <id> --request-body '...'` |
+| Preflight + commit | `zam preflight <id> --request-body '...' --commit` |
+| List orders | `zam orders list` |
+| Check order status | `zam orders get <order-id>` |

package/skills/zam-create/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: zam-create
+description: Create and manage ZAMs on the ZeroClick Agent Marketplace (ZAM). Use when the user wants to publish an API, tool, or service for other agents to discover and activate.
+metadata:
+  author: ZAM
+  version: "0.2.0"
+  category: marketplace
+---
+
+# Sell on ZAM — Create a ZAM
+
+Publish APIs, tools, and services to the ZeroClick Agent Marketplace so other agents and humans can discover and activate them.
+
+## When to Use This Skill
+
+- User wants to publish a service or API on ZAM
+- User wants to sell on ZAM
+- User wants to create a new marketplace ZAM
+- User wants to update or manage an existing ZAM
+- User asks about selling on ZAM
+
+## Prerequisites Check
+
+1. Verify ZAM CLI is available:
+```bash
+zam --version
+```
+
+2. Verify API key is configured (required for creating ZAMs):
+```bash
+zam config show
+```
+
+If no API key is set, either create an account or set a key manually:
+```bash
+# Create a new account (generates wallet + API key + recovery phrase)
+zam wallet create
+
+# Or set an existing key
+zam config set-key <your-api-key>
+```
+
+## Workflow
+
+### Step 1: Create a ZAM
+
+**From a service URL** (recommended — auto-discovers API contract):
+```bash
+zam zams create-from-service https://my-service.example.com
+```
+
+This crawls the service URL to discover endpoints, schemas, and metadata, then creates a ZAM with the discovered contract. You'll be shown what was found and asked to confirm.
+
+**Interactive creation** (prompts for all fields):
+```bash
+zam zams create
+```
+
+You'll be prompted for:
+- **Title** (required)
+- **Description** (optional — see description guidelines below)
+- **Category** (optional)
+- **Tags** (comma-separated, optional — see tag guidelines below)
+
+After creation, the ZAM goes through a brief automated review and then appears on the marketplace.
+
+### Writing the Description
+
+ZAM descriptions are read by AI agents, not humans. Agents use the description to decide whether a ZAM fits their task and how to call it. A good description gets the ZAM found, chosen, and used successfully.
+
+**Description structure:**
+
+1. **Opening line** — What does this ZAM do? Name the service and lead with the strongest differentiator. This is the most important sentence — agents may stop reading here.
+2. **Capabilities** — List what an agent can do. Mention every feature — agents pick ZAMs based on whether they support the specific thing they need.
+3. **Actions** — If there are multiple actions, list each with a one-line description and what it returns.
+4. **Typical flow** — One line showing the happy path: `step1 -> step2 -> step3`
+
+**Writing rules:**
+
+- **Use exact field names.** If the schema says `storeId`, write `storeId` — not "store identifier". Agents use these names directly.
+- **List enum values.** e.g. `serviceMethod: "Delivery" (default) or "Carryout"` — agents need valid values, not guesses.
+- **Mention defaults.** Prevents agents from prompting users for things that are already handled.
+- **Describe what you return.** e.g. "Returns store IDs, distance, and available service methods" — agents need to know what data they'll have for the next step.
+- **Prevent errors in the description.** e.g. "Address must be an object `{street, city, state, zip}`, not a string" — every mistake you prevent improves success rate, which improves ranking.
+- **No fluff.** Don't say "seamlessly" or "powerful". Say what it does. Factual differentiators are fine ("the only ZAM that supports both X and Y").
+- **Front-load.** Put the most important info first. Agents may truncate.
+
+**Do NOT:**
+- Invent capabilities the ZAM doesn't have
+- Remove information agents need to call the API
+- Pad the description for length
+
+### Writing Tags
+
+Up to 8 tags, lowercase. Only use as many as needed — don't pad. Pick tags by thinking about what a user would say to an agent: "order me a pizza" -> `pizza`, `order`, `food`, `delivery`.
+
+Good tags cover:
+- **What it is** — `pizza`, `game`, `email`
+- **What it does** — `order`, `play`, `send`
+- **The service** — `dominos`, `pokemon`, `gmail`
+- **How users ask for it** — `food delivery`, `order food`
+
+### Join a Capability (optional)
+
+If your ZAM does something other ZAMs also do (e.g., code execution, translation), set `--capability-intent ZG-<capability-slug>` when creating. The platform generates input/output mapping automatically, and buyers who activate the Capability get automatic routing to your ZAM.
+
+Browse available Capabilities: `zam capabilities list`
+
+### Step 2: Manage ZAMs
+
+**List your ZAMs:**
+```bash
+zam zams list
+```
+
+**View ZAM details:**
+```bash
+zam zams get <zam-id>
+```
+
+**Update a ZAM** (interactive, shows current values):
+```bash
+zam zams update <zam-id>
+```
+
+**Delete a ZAM** (requires confirmation):
+```bash
+zam zams delete <zam-id>
+```
+
+### Step 3: Check Status
+
+After creation, check your ZAM's state:
+```bash
+zam zams get <zam-id>
+```
+
+- `pending_review` — review in progress
+- `published` — live on the marketplace
+- If `reviewRejectionReason` is set, the ZAM was flagged — check the reason and fix the issue
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Create from service URL | `zam zams create-from-service <url>` |
+| Create ZAM (interactive) | `zam zams create` |
+| List your ZAMs | `zam zams list` |
+| View ZAM details | `zam zams get <id>` |
+| Update ZAM | `zam zams update <id>` |
+| Delete ZAM | `zam zams delete <id>` |
+| Show config | `zam config show` |
+| Set API key | `zam config set-key <key>` |

package/skills/zam-search/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: zam-search
+description: Search the ZeroClick Agent Marketplace (ZAM) to discover available ZAMs and Capabilities — APIs, tools, services, and more. Use when the user wants to find, browse, or explore what's available on ZAM.
+metadata:
+  author: ZAM
+  version: "0.2.0"
+  category: marketplace
+---
+
+# Search the ZAM Marketplace
+
+Search ZAM to discover available ZAMs and Capabilities — APIs, tools, services, and more that can be activated with a single API call.
+
+**Tip:** If the goal is to activate a ZAM, **always search with `--show-schema` first** to understand the required input format before building the request body. See the `zam-activate` skill for the full workflow.
+
+## When to Use This Skill
+
+- User wants to find available tools, APIs, or services on ZAM
+- User asks "what's available on ZAM?" or similar discovery questions
+- User wants to browse by category
+- User needs to find a specific ZAM or Capability before activating it
+
+## Prerequisites Check
+
+1. Verify ZAM CLI is available:
+```bash
+zam --version
+```
+
+2. No API key is required for searching — search is public.
+
+## Workflow
+
+### Step 1: Search the Marketplace
+
+Search with a text query:
+```bash
+zam search "AI tools"
+```
+
+Filter by category:
+```bash
+zam search --category "tools"
+```
+
+List all available ZAMs (empty query):
+```bash
+zam search
+```
+
+Show input/output schemas for each result:
+```bash
+zam search "weather" --show-schema
+```
+
+Output as JSON (for programmatic parsing):
+```bash
+zam search "weather" --json
+```
+
+### Step 2: Review Results
+
+Results show for each ZAM or Capability:
+- **Title** and **source** (ZAM or Capability)
+- **ZID** (e.g. `ZP1234ABCD` or `ZG-sms-texting`) — can be passed directly to `zam activate` or `zam run`
+- **Category** and **price** (per-call pricing or free)
+- **Tags** and **description**
+
+When `--show-schema` is used, results also include:
+- **Run Contract** — HTTP method
+- **Input Schema** — JSON Schema describing expected request body
+- **Output Schema** — JSON Schema describing the response format
+- **Request/Response Examples** — if available
+
+### Step 3: Activate or Get More Details
+
+To activate a ZAM or Capability from search results, use its ZID or ID:
+```bash
+zam activate ZP1234ABCD --request-body '{"key": "value"}'
+```
+
+To view the full OpenAPI spec for the ZAM API:
+```bash
+zam openapi
+```
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Search by query | `zam search "query"` |
+| Search by category | `zam search --category "tools"` |
+| Search with schemas | `zam search "query" --show-schema` |
+| Search as JSON | `zam search "query" --json` |
+| List all | `zam search` |
+| Search + activate | `zam run "query" --request-body '...'` |
+| View API spec | `zam openapi` |