# xapi - X API for Everyone

> A simple CLI tool to help developers learn and use X API on their own accounts

[![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)
[![Status](https://img.shields.io/badge/Status-MVP%20v0.1.0-orange)](https://git.maxtheweb.com/maxtheweb/xapi-cli)

---

## The Vision

X API should be accessible to all developers. Whether you want to automate your tweets, search for content, or build tools for your own account, you shouldn't need complex SDKs or third-party services.

**xapi exists to help YOU:**
- Learn how X API works by using it directly
- Control your own X account programmatically
- Understand OAuth authentication in practice
- Build on top of a simple, clear foundation

This tool is built with simplicity in mind. No hidden complexity, no unnecessary features. Just a straightforward CLI that does what you need and gets out of your way.

---

## What is xapi? (Current MVP)

xapi is a command-line tool that provides:

- **OAuth 1.0a authentication** - Industry-standard signing with HMAC-SHA1
- **4 simple commands** - login, status, search, create
- **Editor-based configuration** - Edit credentials in your favorite editor
- **Local-first security** - All credentials stay on your machine
- **Clear error messages** - Helpful guidance when things go wrong

**This is day 1.** This MVP was built today, and development continues tomorrow. It works, it's useful, and it's ready for you to try.

---

## Installation

### From Source

```bash
git clone https://git.maxtheweb.com/maxtheweb/xapi-cli.git
cd xapi-cli
go build -o xapi .
```

### Using Make

```bash
# Build the binary
make build

# Install system-wide (requires sudo)
make install

# Install for current user only
make install-user

# Clean up
make clean
```

### Arch Linux (AUR) - Coming Soon

```bash
paru -S xapi
# or
yay -S xapi
```

---

## Getting Started

### Step 1: Create an X Developer Account

1. Go to https://developer.x.com/en/portal/dashboard
2. Create a new project and app (or use an existing one)
3. Important: Set app permissions to **"Read and Write"** (required for posting)

### Step 2: Get Your OAuth Credentials

You need 4 OAuth 1.0a credentials:

1. Go to your app's **"Keys and tokens"** tab
2. Find your **OAuth 1.0a** section:
   - **Consumer Key** (API Key)
   - **Consumer Secret** (API Secret)
   - **Access Token**
   - **Access Token Secret**

3. Optional: Get your **OAuth 2.0 Client ID and Secret** (for future features)

**Important:** If you change app permissions from "Read" to "Read and Write", you must **regenerate your Access Token and Access Token Secret**. The Consumer Key/Secret stay the same.

### Step 3: Configure xapi

```bash
./xapi login
```

This opens your editor (nvim/vim/nano) with a config template. Fill in your credentials:

```toml
# OAuth 1.0a Credentials (required)
[oauth]
consumer_key = "YOUR_CONSUMER_KEY"
consumer_secret = "YOUR_CONSUMER_SECRET"
access_token = "YOUR_ACCESS_TOKEN"
access_token_secret = "YOUR_ACCESS_TOKEN_SECRET"

# OAuth 2.0 Credentials (optional, for future features)
[oauth2]
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
```

Save and exit. Your credentials are stored in `~/.config/xapi/config.toml` with secure 0600 permissions.

### Step 4: Test Your Authentication

```bash
./xapi status
```

If everything is set up correctly, you'll see:

```
TESTING AUTHENTICATION
======================

Authenticating with X API...

AUTHENTICATION SUCCESSFUL
=========================

Authenticated as:
  Name:     Your Name
  Username: @yourusername
  User ID:  1234567890

Your OAuth credentials are working correctly!
You can now use 'xapi search' and 'xapi create'
```

### Step 5: Use xapi

**Search for tweets:**

```bash
# Preview search (doesn't consume quota)
./xapi search preview

# Execute search
./xapi search now
```

**Post a tweet:**

```bash
# Preview post
./xapi create preview

# Post immediately
./xapi create now
```

---

## Commands

### `xapi login`

Opens your text editor to configure X API credentials.

- Creates config template at `~/.config/xapi/config.toml`
- Secure file permissions (0600)
- Auto-detects your editor (nvim, vim, vi, nano, emacs)

```bash
./xapi login
```

### `xapi status`

Tests your OAuth authentication by fetching your user information.

- Verifies your credentials work
- Shows your authenticated username
- Detects permission errors

```bash
./xapi status
```

### `xapi search`

Search for tweets using X API v2.

- `preview` - Edit search config, don't execute
- `now` - Execute configured search

Configuration is stored in `~/.config/xapi/search.toml`:

```toml
[query]
text = "golang"
max_results = 10

[filters]
start_time = ""
end_time = ""

[fields]
tweet_fields = ["created_at", "author_id", "public_metrics"]
user_fields = ["username", "verified"]
```

```bash
./xapi search          # Open editor
./xapi search preview  # Preview configured search
./xapi search now      # Execute search
```

### `xapi create`

Post tweets to X.

- `preview` - Edit post config, don't post
- `now` - Post immediately

Configuration is stored in `~/.config/xapi/create.toml`:

```toml
[text]
content = "Hello from xapi!"

[schedule]
schedule_at = ""  # ISO 8601 format, or empty for immediate

[visibility]
reply_settings = "everyone"  # everyone, mentioned_users, or followers
```

```bash
./xapi create          # Open editor
./xapi create preview  # Preview configured post
./xapi create now      # Post immediately
```

---

## How It Works

### Configuration Files

All configuration is stored in `~/.config/xapi/`:

- `config.toml` - OAuth credentials
- `search.toml` - Search parameters
- `create.toml` - Post parameters

Files are created with 0600 permissions and never leave your machine.

### Authentication

xapi uses **OAuth 1.0a** with HMAC-SHA1 signing:

1. Generates OAuth signature base string from request parameters
2. Signs with consumer secret + access token secret
3. Includes signature in Authorization header
4. X API verifies the signature

This is the same authentication used by Twitter's official clients.

### API Endpoints Used

- `GET /2/users/me` - Verify authentication (status command)
- `GET /2/tweets/search/recent` - Search tweets
- `POST /2/tweets` - Create tweets

---

## Security

- **Local storage only** - Credentials never transmitted to third parties
- **Secure permissions** - Config files use 0600 (owner read/write only)
- **No shell history exposure** - Editor-based input, not terminal prompts
- **HTTPS only** - All API calls use encrypted connections
- **Standard OAuth** - Industry-standard authentication, no custom schemes

Your credentials are as secure as your home directory. Never commit config files to git (already in `.gitignore`).

---

## Troubleshooting

### "Permission Error: Your app only has READ permissions"

Your X app needs "Read and Write" permissions to post tweets:

1. Go to https://developer.x.com/en/portal/dashboard
2. Select your project > App settings
3. Change permissions to "Read and Write"
4. **Important:** Regenerate your Access Token and Access Token Secret
5. Run `xapi login` and update your credentials
6. Run `xapi status` to verify

### "Authentication Failed"

Check your credentials:

```bash
./xapi login  # Re-enter credentials
./xapi status # Test authentication
```

Make sure you're using OAuth 1.0a credentials, not Bearer tokens.

### "No text editor found"

Install a text editor:

```bash
# Arch Linux
sudo pacman -S neovim

# Debian/Ubuntu
sudo apt install vim

# macOS
brew install neovim
```

Or set your preferred editor:

```bash
export EDITOR=nano
```

---

## What's Next

This is day 1 of xapi. More features are coming:

**Planned for upcoming releases:**
- Bearer token generation for OAuth 2.0 endpoints
- Quota checking with `/2/usage/tweets` endpoint
- More X API v2 endpoints (user lookup, likes, retweets)
- Bulk operations (batch posting, search export)
- Better output formatting (JSON, CSV, table)
- Rate limit handling and retry logic
- Multiple account support
- Shell completion (bash, zsh, fish)

**Want to help?** Contributions are welcome! See below.

---

## Contributing

xapi is open source and contributions are encouraged.

**How to contribute:**

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/your-feature`
3. Make your changes
4. Test thoroughly
5. Commit: `git commit -m "Add your feature"`
6. Push: `git push origin feature/your-feature`
7. Open a Pull Request

**Ideas for contributions:**
- Add new X API endpoints
- Improve error messages
- Write tests
- Improve documentation
- Report bugs
- Share your use cases

---

## Project Structure

```
xapi-cli/
├── cmd/
│   ├── root.go      # Root command and CLI setup
│   ├── login.go     # OAuth configuration
│   ├── status.go    # Authentication testing
│   ├── search.go    # Tweet search
│   ├── create.go    # Tweet posting
│   └── oauth.go     # OAuth 1.0a signing
├── main.go          # Entry point
├── go.mod           # Go dependencies
├── Makefile         # Build shortcuts
├── PKGBUILD         # Arch Linux package
├── LICENSE          # MIT License
└── README.md        # You are here
```

---

## A Note from the Author

I built xapi today because I believe X API should be accessible to everyone. Not just corporations with expensive SDKs, not just developers with complex infrastructure—everyone.

This tool is about **freedom**. The freedom to control your own account. The freedom to learn by doing. The freedom to build without barriers.

I'm working on this because it brings me purpose and joy. Knowing that other developers will grab this tool, use it, learn from it, and maybe even improve it—that makes me happy.

**This is just day 1.** I'll be working on xapi tomorrow, and the day after. It will grow with the community's needs. It will stay simple, because simplicity is power.

If you use xapi, if it helps you, if it teaches you something—that's why I built it.

**Grab it. Use it. Build with it.**

— maxtheweb

---

## License

MIT License - See [LICENSE](LICENSE) for details.

Copyright (c) 2025 maxtheweb

---

## Links

- **Source Code**: https://git.maxtheweb.com/maxtheweb/xapi-cli
- **Issues**: https://git.maxtheweb.com/maxtheweb/xapi-cli/issues
- **Author**: max@maxtheweb.com

---

**Built with purpose. Built for you.**