Twitter CLI Daemon

A lightweight daemon for posting tweets from your terminal. Built with Python and systemd, it provides a simple command interface for Twitter/X API v2.

Features

• 🚀 Post tweets directly from terminal with a simple t command
• 💬 Real-time feedback with tweet URL and content confirmation
• 🔒 Secure credential storage via environment variables
• 🌐 Proxy support (works in restricted regions)
• 🪶 Minimal resource usage (0% CPU when idle)
• 🐧 Linux systemd integration for reliability

Prerequisites

• Linux with systemd (tested on Manjaro Linux)
• Python 3.9+
• Poetry (for dependency management)
• Twitter Developer Account with API access

Quick Start

# Clone the repository
git clone https://github.com/yourusername/twitter-cli
cd twitter-cli

# Install dependencies
poetry install

# Set up your Twitter API credentials
cp .env.example .env
nano .env  # Add your credentials

# Install the daemon
./install.sh

# Start the service
systemctl --user start twitter-cli
systemctl --user enable twitter-cli

# Send your first tweet!
t Hello Twitter from my terminal!

Installation

1. Get Twitter API Credentials

Step 1: Create Developer Account

1. Go to developer.twitter.com
2. Click "Sign up" for a developer account
3. Choose "Hobbyist" → "Making a bot"
4. Fill in the required information about your use case
5. Verify your email address

Step 2: Create a Project

1. In the Developer Portal, click "Projects & Apps"
2. Click "New Project"
3. Name your project (e.g., "Personal Twitter CLI")
4. Choose your use case (e.g., "Making a bot")

Step 3: Create an App

1. Inside your project, click "Create App"
2. Choose a unique app name (e.g., "yourname-cli-bot")
3. Save the API Key and API Key Secret shown (you'll need these!)

Step 4: Set App Permissions

1. Go to your app settings
2. Click "User authentication settings" → "Set up"
3. Enable OAuth 1.0a
4. Under "App permissions", select "Read and write"
5. Set Callback URI to: http://localhost:3000
6. Set Website URL to: https://example.com
7. Save settings

Step 5: Generate Access Tokens

1. Go to "Keys and tokens" tab
2. Under "Authentication Tokens", click "Generate" for Access Token and Secret
3. Save all 4 credentials:
   • API Key (Consumer Key)
   • API Key Secret (Consumer Secret)
   • Access Token
   • Access Token Secret

Note: Free tier allows 500 tweets per month. If you get "403 Forbidden" errors, make sure you've set "Read and write" permissions and regenerated your Access Tokens after changing permissions.

2. Install Dependencies

# Install Poetry if you haven't already
curl -sSL https://install.python-poetry.org | python3 -

# Install project dependencies
poetry install

3. Configure Credentials

cp .env.example .env
nano .env

Add your Twitter API credentials to the .env file.

4. Install the Daemon

./install.sh

This will:

• Copy the t command to /usr/local/bin
• Set up the systemd user service
• Configure proper permissions

5. Start the Service

systemctl --user daemon-reload
systemctl --user enable twitter-cli
systemctl --user start twitter-cli

Usage

Post a Tweet

t Hello world from Linux terminal!

You'll see:

✅ Tweet published!

📝 Text: Hello world from Linux terminal!

🔗 Link: https://twitter.com/yourusername/status/1234567890

Check Status

t status

Stop the Daemon

t stop
# or
systemctl --user stop twitter-cli

View Logs

# Service logs
journalctl --user -u twitter-cli -f

# Application logs
tail -f twitter-daemon.log

Configuration

For zsh Users

To properly handle special characters (!,*,?), add this alias to your ~/.zshrc:

alias t="noglob t"

Proxy Support

If you're in a region where Twitter is blocked, the daemon supports proxychains. Edit the systemd service file:

nano ~/.config/systemd/user/twitter-cli.service

And modify ExecStart to include proxychains:

ExecStart=/usr/bin/proxychains -q /path/to/poetry run python /path/to/twitter-daemon.py

Architecture

The system consists of two main components:

1. Daemon (twitter-daemon.py): Runs as a systemd service, listens for commands via named pipe
2. Client (t): Simple bash script that sends commands to the daemon

Communication happens through named pipes:

• /tmp/twitter-cli-pipe - for sending commands
• /tmp/twitter-cli-response - for receiving responses

Troubleshooting

Daemon Won't Start

Check the logs:

journalctl --user -u twitter-cli -n 50

Common issues:

• Invalid API credentials
• Missing dependencies
• Permission issues

403 Forbidden Error

Your app needs "Read and write" permissions:

1. Go to Twitter Developer Portal
2. Edit your app's User authentication settings
3. Set permissions to "Read and write"
4. Regenerate your Access Token and Secret
5. Update .env and restart the daemon

Command Not Found

sudo cp t /usr/local/bin/t
sudo chmod +x /usr/local/bin/t

Uninstall

# Stop and disable the service
systemctl --user stop twitter-cli
systemctl --user disable twitter-cli

# Remove files
rm ~/.config/systemd/user/twitter-cli.service
sudo rm /usr/local/bin/t

Security Notes

• API credentials are stored in .env file (not in version control)
• Named pipes have 666 permissions (any local user can send commands)
• Consider adjusting permissions based on your security requirements

Contributing

Pull requests are welcome! Please feel free to submit issues and enhancement requests.

License

MIT License - see LICENSE file for details

Acknowledgments

Built with Claude Code in 20 minutes! 🚀