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: )
--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)

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

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: ]/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

export MASTODON_TOKEN="paste_token_here"

Step 5: Verify Token Works

./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 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: __CODE_BLOCK_10__ Or on error: __CODE_BLOCK_11__ The data` field contains the raw Mastodon API response without any modifications.