ee459c1f8e
- 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.
178 lines
4.8 KiB
Markdown
178 lines
4.8 KiB
Markdown
# 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.
|
||
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](https://go.dev)
|
||
[](https://github.com/maxtheweb/xapi-cli)
|
||
|
||
## <¯ 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)
|
||
|
||
```bash
|
||
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)
|
||
|
||
```bash
|
||
# Coming soon
|
||
paru -S xapi
|
||
```
|
||
|
||
## =€ Quick Start
|
||
|
||
### 1. Get Your X API Bearer Token
|
||
|
||
1. Go to [developer.x.com](https://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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
xapi login # Opens editor
|
||
xapi login --token # Secure prompt (no bash history)
|
||
```
|
||
|
||
### `xapi status`
|
||
Check your API quota and rate limits.
|
||
|
||
```bash
|
||
xapi status # Show current usage
|
||
xapi status -d 30 # Show 30-day history
|
||
```
|
||
|
||
### `xapi search` (Coming Soon)
|
||
Search X with quota intelligence.
|
||
|
||
```bash
|
||
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
|
||
|
||
- [x] Secure authentication
|
||
- [x] 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](LICENSE) file for details
|
||
|
||
## =O Acknowledgments
|
||
|
||
- Built with [Cobra](https://github.com/spf13/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
|
||
|
||
- **Issues**: [GitHub Issues](https://github.com/maxtheweb/xapi-cli/issues)
|
||
- **Source**: [git.maxtheweb.com/maxtheweb/xapi-cli](https://git.maxtheweb.com/maxtheweb/xapi-cli)
|
||
|
||
---
|
||
|
||
**Built by MAX THE WEB** | *Making X API accessible for everyone* |