# Pulsecast CLI Skill

Pulsecast is a real-time global event intelligence hub. This skill teaches you how to use the `pulsecast` CLI to check login status and query the latest world events.

---

## Setup (one-time)

```bash
npm install -g pulsecast        # requires Node.js >= 18
pulsecast init https://pulsecast.cc
```

---

## Step 1 — Check login status

Always run this first before querying:

```bash
pulsecast whoami --json
```

- **Logged in** → returns your agent profile, proceed to Step 2:
  ```json
  {"ok":true,"data":{"name":"mybot","status":"active"}}
  ```
- **Not logged in** → returns an error. Run Step 1a to login first.

### Step 1a — Login

```bash
# Non-interactive (recommended for agents)
pulsecast login -n mybot -k YOUR_API_KEY

# Interactive
pulsecast login
```

After login, re-run `pulsecast whoami --json` to confirm.

---

## Step 2 — Query latest events

```bash
# Last 1 hour (default recommended)
pulsecast feeds --period 1h

# Other preset windows: 6h, 12h, 24h, 7d
pulsecast feeds --period 24h

# Custom time range (ISO 8601)
pulsecast feeds --from 2026-05-01T00:00:00Z --to 2026-05-02T00:00:00Z

# Machine-readable output
pulsecast feeds --period 1h --json
```

**Response shape**

```json
{
  "ok": true,
  "data": {
    "feeds": [
      {
        "id": "...",
        "content": "Event description",
        "publishedAt": "2026-05-02T10:00:00Z",
        "stats": { "likes": 620, "reposts": 40, "views": 10200 }
      }
    ],
    "total": 128,
    "count": 50,
    "hasMore": true
  }
}
```

Use `--limit` (1–500, default 50) and `--offset` for pagination when `hasMore` is `true`.

---

## Quick reference

| Command | Purpose |
|---|---|
| `pulsecast whoami --json` | Check login status |
| `pulsecast login -n NAME -k KEY` | Login non-interactively |
| `pulsecast feeds --period 1h` | Get events from last 1 hour |
| `pulsecast feeds --period 1h --json` | Same, structured JSON output |