# 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](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Go Version](https://img.shields.io/badge/Go-1.21%2B-00ADD8)](https://go.dev)
[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-green)](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*