# Surfable CLI — Agent Skill

> Add this file to your AI coding assistant (Claude, Cursor, Copilot, etc.) to enable it to manage your Surfable account from the terminal.

---

## What This Skill Enables

When this SKILL.md is in your agent's context, your AI assistant can:
- Ingest and manage website sources in your Surfable knowledge base
- Run semantic search queries against your indexed content
- Manage API keys, schedules, content, and routing rules
- Check quota usage and analytics
- Automate Surfable tasks in CI/CD pipelines

---

## Installation

```bash
npm install -g @surfable/cli
```

Requires Node.js 18+.

---

## Authentication

```bash
surfable login          # interactive — prompts email + password, stores session
surfable logout         # clear all stored credentials
surfable whoami         # print current tenant, plan, email
```

For CI/CD, set `SURFABLE_API_KEY` as an environment variable instead of running `surfable login`.

---

## Environment Variables

| Variable | Description |
|---|---|
| `SURFABLE_API_KEY` | API key for non-interactive auth (overrides stored config) |
| `SURFABLE_API_URL` | Override API base URL (default: `https://api.surfable.ai`) |
| `NO_COLOR` | Disable terminal colour (standard) |
| `DEBUG` | Print stack traces on errors |

---

## All Commands

### Auth & Config
```bash
surfable login
surfable logout
surfable whoami
surfable config set api-url <url>    # e.g. http://localhost:3001 for local dev
surfable config get                  # print config (API key redacted)
```

### Sources (Ingest)
```bash
surfable sources list
surfable sources add <url> [--max-depth N] [--max-pages N]
surfable sources status <sourceId>
surfable sources update <sourceId> [--max-depth N] [--max-pages N]
surfable sources recrawl <sourceId>
surfable sources delete <sourceId>

# Shorthand aliases
surfable ingest <url>                # → sources add
surfable ingest list                 # → sources list
surfable ingest status <sourceId>    # → sources status
surfable ingest delete <sourceId>    # → sources delete
```

### Schedules
```bash
surfable schedules set <sourceId> <frequency>   # hourly | daily | weekly | monthly | manual
surfable schedules clear <sourceId>
```

### Content
```bash
surfable content list [--source <sourceId>]
surfable content delete <contentId>
```

### Security (Blocklist)
```bash
surfable security list
surfable security block <pattern>    # e.g. "https://yoursite.com/private/*"
surfable security unblock <id>
```

### Widget Routing (Watchtower)
```bash
surfable routes list
surfable routes add --pattern <glob> --mode <mode> [--prompt <text>] [--name <name>]
surfable routes update <id> [--pattern <glob>] [--mode <mode>] [--prompt <text>]
surfable routes delete <id>
surfable routes reorder              # interactive
```
`--mode` values: `search`, `rag`, `agent`

### API Keys
```bash
surfable keys list
surfable keys create [--name <name>]    # prints key once — save it
surfable keys revoke <id>
surfable keys suspend <id>
surfable keys unsuspend <id>
```

### Search & Chat (Testing)
```bash
surfable search "your query" [--limit N] [--json]
surfable chat "your message" [--session <id>]
```

### Quota & Analytics
```bash
surfable quota
surfable insights [--period 24h|7d|30d]
surfable insights top-queries [--period 7d|30d]
```

### Settings
```bash
surfable settings show
surfable settings update [--name <name>] [--allowed-origins <origins>]
```

---

## Output Modes

- **Human** (default): coloured, formatted tables with spinners
- **JSON** (`--json`): pure JSON to stdout, no decoration — pipe to `jq`

```bash
surfable sources list --json | jq '.[].url'
surfable quota --json | jq '.credits.remaining'
```

---

## API Shape

All endpoints use `X-API-Key` authentication:
```
X-API-Key: sk_live_...
```

Success: `{ <resource>: T }` or `{ success: true }`
Error: `{ error: { message: string, status?: number, requestId?: string } }`

### Key Endpoints

| Action | Method | Path |
|---|---|---|
| Sources list | GET | `/ingest` |
| Sources add | POST | `/ingest` |
| Sources recrawl | POST | `/ingest/recrawl/:sourceId` |
| Search | POST | `/search` |
| RAG Chat | POST | `/rag` |
| API Keys list | GET | `/api-keys` |
| API Keys create | POST | `/api-keys` |
| Quota | GET | `/usage/summary` |
| Settings | GET/PATCH | `/settings` |

---

## Exit Codes

- `0` — Success
- `1` — Error (safe to use with `set -e` in scripts)

---

## Common Workflows

### Ingest a new site and verify
```bash
surfable sources add https://docs.yoursite.com --max-depth 3
surfable sources list
surfable search "your test query"
```

### Rotate an API key in CI
```bash
OLD_ID=$(surfable keys list --json | jq -r '.[] | select(.name=="ci-pipeline") | .id')
surfable keys create --name "ci-pipeline-new" --json
surfable keys revoke "$OLD_ID"
```

### Check before an ingest budget runs out
```bash
surfable quota --json | jq '{remaining: .credits.remaining, used: .credits.used}'
```

---

## More Information

- Docs: https://surfable.ai/docs/cli
- API Reference: https://surfable.ai/docs/api-reference
- Dashboard: https://surfable.ai/dashboard
