mastodon-scout

---
name: mastodon-scout
description: Read-only Mastodon CLI. Outputs human-readable timeline summaries or raw JSON.
metadata:
  {
    "openclaw":
      {
        "emoji": "🦣",
        "requires": { "anyBins": ["{baseDir}/bin/mastodon-scout", "mastodon-scout"] },
        "install":
          [
            {
              "id": "download-darwin-arm64",
              "kind": "download",
              "os": ["darwin"],
              "url": "https://github.com/patelhiren/mastodon-scout/releases/download/v1.0.2/mastodon-scout-darwin-arm64.zip",
              "archive": "zip",
              "bins": ["mastodon-scout"],
              "targetDir": "{baseDir}/bin",
              "label": "Install Mastodon Scout (macOS Apple Silicon)",
            },
            {
              "id": "download-darwin-amd64",
              "kind": "download",
              "os": ["darwin"],
              "url": "https://github.com/patelhiren/mastodon-scout/releases/download/v1.0.2/mastodon-scout-darwin-amd64.zip",
              "archive": "zip",
              "bins": ["mastodon-scout"],
              "targetDir": "{baseDir}/bin",
              "label": "Install Mastodon Scout (macOS Intel)",
            },
            {
              "id": "download-linux-amd64",
              "kind": "download",
              "os": ["linux"],
              "url": "https://github.com/patelhiren/mastodon-scout/releases/download/v1.0.2/mastodon-scout-linux-amd64.zip",
              "archive": "zip",
              "bins": ["mastodon-scout"],
              "targetDir": "{baseDir}/bin",
              "label": "Install Mastodon Scout (Linux)",
            },
            {
              "id": "download-windows-amd64",
              "kind": "download",
              "os": ["win32"],
              "url": "https://github.com/patelhiren/mastodon-scout/releases/download/v1.0.2/mastodon-scout-windows-amd64.zip",
              "archive": "zip",
              "bins": ["mastodon-scout.exe"],
              "targetDir": "{baseDir}/bin",
              "label": "Install Mastodon Scout (Windows)",
            },
          ],
      },
  }
---

# Mastodon Scout

## Purpose

Read-only Mastodon CLI that fetches data from the Mastodon API. Returns human-readable summaries by default, or raw JSON with `--json` flag.

---

## Invocation Rules (MANDATORY)

### Binary Selection
- **macOS / Darwin** → `dist/mastodon-scout`
- **Linux** → `dist/mastodon-scout-linux`

### Commands

#### Home Timeline
```
{baseDir}/bin/mastodon-scout home
```
Fetches the authenticated user's home timeline.

#### User Tweets
```
{baseDir}/bin/mastodon-scout user-tweets
```
Fetches the authenticated user's own posts.

#### Mentions
```
{baseDir}/bin/mastodon-scout mentions
```
Fetches mentions of the authenticated user.

#### Search
```
{baseDir}/bin/mastodon-scout search <query>
```
Searches for posts matching the query.

### Flags (Optional)
```
--instance <url>       # Mastodon instance URL (default: https://mastodon.social)
--limit <int>          # Number of items to return (default: 20)
--timeout <int>        # Timeout in seconds (default: 30)
--json                 # Output raw JSON instead of human-readable text
```

### Environment Variables (REQUIRED)
```
MASTODON_TOKEN         # OAuth bearer token for authentication
```

---

## Output Modes

### Text Mode (Default)
```bash
mastodon-scout home
```
Returns human-readable summary of timeline data.

The agent MAY summarize and explain the timeline results to make them more accessible to the user.

### JSON Mode
```bash
mastodon-scout --json home
```
Returns raw JSON data from the Mastodon API.

When JSON mode is used, return the output verbatim without interpretation.

---

## Error Handling

- If the binary exits non-zero:
  - In JSON mode: return error output verbatim
  - In text mode: the agent MAY explain the error to the user
  - Do not retry

- If MASTODON_TOKEN is not set:
  - The binary will exit with an error message
  - Agent should guide the user to the authentication setup section

---

## Examples That Trigger This Skill

- `mastodon-scout home`
- `show my mastodon timeline`
- `check mastodon mentions`
- `search mastodon for "golang"`
- `get my mastodon posts`

---

## Performance Requirements

- Execute binary directly
- No web searches
- No secondary tools beyond the binary
- Minimize latency

---

## Notes

- In text mode: agent MAY summarize and explain results
- In JSON mode: output verbatim, no interpretation
- This skill is **read-only** (no posting, following, or other mutations)

---

## Authentication Setup (Agent MAY Help)

**EXCEPTION TO STRICT MODE**: If the user needs help obtaining a token, the agent **may** provide guidance before executing the skill.

The tool requires a Mastodon OAuth bearer token set in the `MASTODON_TOKEN` environment variable.

### How to Obtain a Token (Guide the User):

**Step 1: Access Development Settings**
- User should log into their Mastodon instance (e.g., mastodon.social, fosstodon.org)
- Navigate to: **Settings → Development** (or Preferences → Development)
- Direct URL format: `https://[instance-domain]/settings/applications`

**Step 2: Create Application**
- Click "New Application"
- Fill in details:
  - **Application name**: `mastodon-scout` (or any name)
  - **Application website**: Can leave blank or use any URL
  - **Redirect URI**: `urn:ietf:wg:oauth:2.0:oob` (for CLI apps)
  - **Scopes**: **CRITICAL - Only select `read`** (uncheck write, follow, push)

**Step 3: Get Access Token**
- Click "Submit"
- Click on the created application to view details
- Copy the **"Your access token"** field value

**Step 4: Set Environment Variable**
```bash
export MASTODON_TOKEN="paste_token_here"
```

**Step 5: Verify Token Works**
```bash
./dist/mastodon-scout home
```

### Common Mastodon Instances:
- `mastodon.social` - General purpose (default)
- `fosstodon.org` - FOSS/tech community
- `mas.to` - Tech focused
- `hachyderm.io` - Tech/infosec community

Use `--instance https://your-instance.com` flag for non-default instances.

### Security Notes to Communicate:
- Token is **read-only** (cannot post, follow, or delete)
- Keep token secret (don't commit to git)
- Can be revoked anytime in Development settings
- Each Mastodon instance requires its own token

---

## Output Format

### Text Mode (Default)
Human-readable summary of posts, formatted for readability. The agent decides how to present the information.

### JSON Mode (`--json` flag)
All commands return JSON in the following format:

```json
{
  "success": true,
  "data": [ /* Mastodon API response */ ]
}
```

Or on error:

```json
{
  "success": false,
  "error": "error message"
}
```

The `data` field contains the raw Mastodon API response without any modifications.