maxtheweb/xapi-cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ee459c1f8e
xapi-cli/README.md
Soldier ee459c1f8e feat: Initial MVP release with authentication and quota tracking 
- Add secure login command with smart editor detection
- Implement Bearer token authentication with hidden input option
- Add status command showing monthly quota and rate limits
- Support for Free/Basic/Pro tier detection
- Smart editor detection (nvim, vim, nano, etc.)
- Secure token storage in ~/.config/xapi/config.toml
- Add comprehensive README and documentation
- Add .gitignore for binaries and IDE files

Features:
- xapi login: Configure credentials securely
- xapi login --token: Hidden input mode (no bash history)
- xapi status: Check quota usage and recommendations
- xapi status --days N: View N-day usage history

Security:
- Token input without shell history exposure
- Config file with 0600 permissions
- HTTPS-only API communication
- Clear security warnings in config

Built with Cobra CLI framework for a professional CLI experience.
Next: Search command with dry-run mode to preview before burning quota.
2025-11-13 16:19:30 +00:00

4.8 KiB
Raw Blame History

xapi - The Quota-Intelligent X API CLI

Preview searches before you burn API quota. Built for developers on X's Free and Basic tiers who need to maximize every API call.

License: MIT Go Version Platform

<¯ Why xapi?

X (Twitter) API's free tier gives you just 100 reads/month. That's ~3 searches per day. One bad query and you've burned a day's quota.

xapi solves this:

  • = Dry-run by default - Preview results before consuming quota
  • =Ê Real-time quota tracking - Know exactly what you have left
  • =¾ Smart caching - Never waste quota on duplicate searches
  • <¯ Query optimization - Get maximum data per API call

( Features

  • Smart Authentication: Secure token input without shell history exposure
  • Quota Intelligence: See exactly how many operations you have left
  • Search Preview: Validate queries before executing (dry-run mode)
  • Multiple Editor Support: Auto-detects nvim, vim, nano, and more
  • Rate Limit Awareness: Shows both monthly quota and 15-min rate windows

=æ Installation

From Source (Recommended)

git clone https://git.maxtheweb.com/maxtheweb/xapi-cli.git
cd xapi-cli
go build -o xapi .
sudo mv xapi /usr/local/bin/

Arch Linux (AUR)

# Coming soon
paru -S xapi

=€ Quick Start

1. Get Your X API Bearer Token

  1. Go to developer.x.com
  2. Create a new app (or use existing)
  3. Navigate to "Keys and tokens"
  4. Copy your Bearer Token

2. Configure xapi

# Option 1: Secure prompt (recommended - no shell history)
xapi login --token
Enter your X API Bearer token (input hidden): ****

# Option 2: Use your editor
xapi login  # Opens $EDITOR (nvim/vim/nano)

3. Check Your Status

xapi status

=Ê MONTHLY QUOTA STATUS
PPPPPPPPPPPPPPPPPPPPPPP
 Type: Free Tier (100 total operations/month)
 Used: 47 / 100 operations (47.0%)
 Remaining: 53 operations
 Resets in: 15 days

ñ  15-MIN RATE WINDOW
PPPPPPPPPPPPPPPPPPPPP
 Requests: 0 / 1 available
 Resets in: 14 minutes 59 seconds

=¡ RECOMMENDATIONS
PPPPPPPPPPPPPPPPP
 You have 53 operations left for 15 days
 That's ~3.5 operations per day
 Each search query will consume 1 operation

=Ö Commands

xapi login

Configure your X API credentials securely.

xapi login           # Opens editor
xapi login --token   # Secure prompt (no bash history)

xapi status

Check your API quota and rate limits.

xapi status          # Show current usage
xapi status -d 30    # Show 30-day history

xapi search (Coming Soon)

Search X with quota intelligence.

xapi search --query "golang"           # Dry-run by default
xapi search --query "golang" --execute  # Actually perform search

= Security

  • No Shell History: Token input uses secure prompts
  • File Permissions: Config stored with 0600 permissions
  • HTTPS Only: All API calls use encrypted connections
  • Local Storage: Credentials never leave your machine

<× Architecture

xapi-cli/
 cmd/
    root.go      # Base command setup
    login.go     # Authentication handling
    status.go    # Quota checking
 main.go          # Entry point
 go.mod           # Dependencies
 README.md        # You are here

> Contributing

Contributions welcome! This is an open-source project designed to help developers maximize their X API usage.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

=Ý Roadmap

  • Secure authentication
  • Quota tracking
  • Search with dry-run
  • Result caching
  • Query history
  • Export formats (JSON, CSV)
  • Multiple account support
  • AUR package

= Known Issues

  • The X API returns combined quota for reads/posts (not separated)
  • Rate limit headers may take a few seconds to update after requests

=Ü License

MIT License - see LICENSE file for details

=O Acknowledgments

  • Built with Cobra - The CLI framework used by Docker, Kubernetes, and Hugo
  • Inspired by the need to not waste precious API quota
  • Created for the developer community struggling with X's API limits

=¬ Support

Built by MAX THE WEB | Making X API accessible for everyone