Setting up Truth Social Credentials for last30days-skill: A Complete Configuration Guide

To enable Truth Social in last30days-skill, export TRUTHSOCIAL_TOKEN as an environment variable or add it to a .claude/last30days.env file in your project root, then verify detection with python3 scripts/last30days.py --diagnose.

The last30days skill aggregates recent content from platforms like Reddit, X, and YouTube, including optional Truth Social integration via its Mastodon-compatible API. Setting up Truth Social credentials for last30days-skill requires obtaining a Bearer token and storing it in one of three configuration layers that the skill automatically loads at runtime. This guide walks through the exact source file locations, precedence rules, and verification commands needed to authenticate successfully.

Understanding the Configuration System

The skill implements a hierarchical configuration system in scripts/lib/env.py, specifically within the get_config() and _find_project_env() functions. Credentials load in the following order of precedence:

1. Environment variables (os.environ) — highest priority
2. Per-project file — .claude/last30days.env located by walking up from the current working directory
3. Global file — ~/.config/last30days/.env — lowest priority

When the TRUTHSOCIAL_TOKEN is present in any of these sources, the is_truthsocial_available() function (lines 494-500 in scripts/lib/env.py) returns True, enabling the Truth Social client in scripts/lib/truthsocial.py.

Obtaining Your Truth Social Bearer Token

Truth Social uses a standard Bearer token authentication scheme based on JWT. To extract your token:

1. Log in to truthsocial.com in your web browser
2. Open browser Developer Tools (F12 or Cmd+Option+I)
3. Navigate to any authenticated endpoint in the Network tab
4. Locate the Authorization request header
5. Copy the string following Bearer (e.g., eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...)

This token grants API access equivalent to your web session and is required by the search_truthsocial() function in scripts/lib/truthsocial.py.

Configuring the TRUTHSOCIAL_TOKEN

Choose one of the following three methods based on your security and portability needs.

Method 1: Per-Project Configuration File (Recommended)

Create a file named .claude/last30days.env at your repository root. The _find_project_env() function automatically discovers this file by traversing parent directories from your current working directory.

# Create the configuration directory and file

mkdir -p .claude
echo "TRUTHSOCIAL_TOKEN=YOUR_BEARER_TOKEN_HERE" > .claude/last30days.env

# Set restrictive permissions (the env.py helper will warn if world-readable)

chmod 600 .claude/last30days.env

Method 2: Global Configuration File

For system-wide persistence across all projects, create the global configuration file:

# Create the global config directory

mkdir -p ~/.config/last30days

# Write the token

echo "TRUTHSOCIAL_TOKEN=YOUR_BEARER_TOKEN_HERE" > ~/.config/last30days/.env
chmod 600 ~/.config/last30days/.env

The get_config() function in scripts/lib/env.py merges this file after checking for the per-project variant, applying lower precedence.

Method 3: Direct Environment Variable

For temporary or CI/CD usage, export the variable in your shell session:

export TRUTHSOCIAL_TOKEN="YOUR_BEARER_TOKEN_HERE"
python3 scripts/last30days.py "query" --sources=all

This method overrides any file-based configuration due to the highest precedence in the merged_env dictionary built by load_env_file.

Verifying Your Setup

Validate that the skill detects your Truth Social credentials before running research queries:

python3 scripts/last30days.py --diagnose

Look for the following output in the diagnostic logs:

✅ Truth Social: enabled

If you see ❌ Truth Social: disabled (token not configured), verify that:

• The token value is correctly spelled as TRUTHSOCIAL_TOKEN
• The file is readable by your user (check with ls -la .claude/last30days.env)
• You are running the command from a directory at or below where .claude/last30days.env exists

Running Research Queries with Truth Social

Once configured, the run_research() function in scripts/last30days.py automatically includes Truth Social when you specify --sources=all or explicitly include truthsocial in your source list:

# Search all enabled sources including Truth Social

python3 scripts/last30days.py "latest political memes" \
    --sources=all \
    --emit=compact

# Search only Truth Social

python3 scripts/last30days.py "election updates" \
    --sources=truthsocial \
    --days=30

The pipeline executes search_truthsocial() in a separate thread, which constructs the Mastodon API request with the Authorization: Bearer <TOKEN> header and parses the response into normalized items rendered by scripts/lib/render.py.

Troubleshooting Common Issues

• Error: "Truth Social token not configured"
  Verify the token exists in your chosen config location and that env.get_config() can read it. Check file permissions—the _check_file_permissions() helper in env.py warns if your .env file is world-readable.

• Error: "Truth Social token expired"
  Truth Social Bearer tokens are JWTs with an exp claim. When expired, return to the web interface and extract a fresh token, then update your configuration file.

• Error: "Truth Social access denied (Cloudflare)"
  Cloudflare may block automated requests. Verify the token works in a browser, then add delays between API calls or use a residential IP/VPN if making frequent queries.

• No Truth Social results with --sources=all
  Ensure the token is present and the source is not excluded by your --search parameter. Explicitly include it with --sources=truthsocial,x,reddit to force inclusion.

Summary

• Configuration hierarchy: Environment variables override .claude/last30days.env, which overrides ~/.config/last30days/.env
• Token location: Store TRUTHSOCIAL_TOKEN in .claude/last30days.env for per-project isolation (recommended)
• Key files: scripts/lib/env.py handles loading; scripts/lib/truthsocial.py handles API calls
• Verification: Use python3 scripts/last30days.py --diagnose to confirm the is_truthsocial_available() check passes
• Usage: Include truthsocial in --sources or use --sources=all to query the Truth Social Mastodon API

Frequently Asked Questions

Where does last30days-skill look for the Truth Social token?

The skill searches three locations in order: first os.environ for TRUTHSOCIAL_TOKEN, then walks up the directory tree from your current working directory looking for .claude/last30days.env, and finally checks ~/.config/last30days/.env. This logic is implemented in get_config() and _find_project_env() within scripts/lib/env.py.

How long does a Truth Social Bearer token remain valid?

Truth Social tokens are JWTs that typically expire after a set session duration (often hours or days). When you receive an expiration error or the API returns 401 Unauthorized, you must generate a new token from the browser and replace the old value in your configuration file.

Can I use the same token across multiple projects?

Yes. Place the token in ~/.config/last30days/.env for global access across all last30days-skill invocations on your machine. However, for security isolation between projects, per-project .claude/last30days.env files are recommended.

Why does the skill require a Bearer token instead of username/password?

The last30days-skill communicates with Truth Social's Mastodon-compatible API, which follows OAuth 2.0 Bearer token authentication. The token represents an authenticated session without exposing your credentials, allowing the search_truthsocial() function to make authorized API calls on your behalf.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}