xcom-rs

xcom-rs is an experimental, agent-friendly CLI for X.com-style operations.

The project is designed around predictable, machine-readable responses (JSON/YAML/NDJSON) while still supporting a human-readable text mode.

Features

• Output envelope with consistent ok/error/meta fields
• Output formats: text, json, yaml, ndjson
• Introspection helpers: commands, schema, help
• Tweet operations: tweets create, tweets list, tweets like, tweets unlike, tweets retweet, tweets reply, tweets thread, tweets show, tweets conversation
• Search: search recent, search users
• Timeline: timeline home, timeline mentions, timeline user
• Media: media upload
• Bookmarks: bookmarks add, bookmarks remove, bookmarks list
• Auth and billing helpers (local state): auth status, auth import, auth export
• Diagnostics: doctor (with optional --probe for API connectivity check)
• Embedded skill installer for agent toolchains (install-skills)

Install

Prerequisites

• Rust (1.70+)

From crates.io

cargo install xcom-rs

Homebrew

This repository includes a Homebrew formula at Formula/xcom_rs.rb.

To install via a tap (recommended for now):

brew tap tumf/tap
brew install xcom_rs

Notes:

• The formula name is xcom_rs, but the installed binary is xcom-rs.
• If you don't have a tap yet, copy Formula/xcom_rs.rb into your tap repo under Formula/.

From Source

cargo install --path .

For development setup and Makefile workflows, see CONTRIBUTING.md.

Quick Start

# 1. Install
cargo install xcom-rs

# 2. Authenticate — import a base64-encoded bearer token
xcom-rs auth import "$XCOM_AUTH_DATA" --output json

# 3. Verify setup with doctor
xcom-rs doctor --output json

# 4. Create your first tweet
xcom-rs tweets create "Hello from xcom-rs!" --output json

# 5. Browse your home timeline
xcom-rs timeline home --limit 5 --output json

Usage

Global Flags

• --output {text|json|yaml|ndjson}
• --log-format {text|json}
• --trace-id <id>
• --non-interactive
• --dry-run
• --max-cost-credits <n>
• --budget-daily-credits <n>

Authentication

xcom-rs currently supports importing/exporting a bearer token for local use. OAuth login flows are not implemented yet.

Check current auth status:

xcom-rs auth status --output json

Import credentials (expects a base64-encoded JSON token):

XCOM_AUTH_DATA="$(python - <<'PY'
import base64, json

token = {
  "accessToken": "YOUR_TOKEN",
  "tokenType": "bearer",
  "expiresAt": None,
  "scopes": ["tweet.read", "tweet.write"],
}

print(base64.b64encode(json.dumps(token).encode()).decode())
PY
)"

xcom-rs auth import "$XCOM_AUTH_DATA" --output json

By default, credentials are stored at $XDG_DATA_HOME/xcom-rs/auth.json or ~/.local/share/xcom-rs/auth.json.

Security note: the export/import payload is base64 (not encrypted). Treat it like a secret.

Examples

List agent-facing command metadata:

xcom-rs commands --output json

Get a JSON schema for a command response envelope:

xcom-rs schema --command commands --output json

Create a tweet (demo):

xcom-rs tweets create "Hello from xcom-rs" --output json

List tweets (demo):

xcom-rs tweets list --limit 5 --output text

Install embedded skills:

xcom-rs install-skills --yes

Shell Completions

xcom-rs can generate shell completion scripts for Bash, Zsh, and Fish.

Bash

# Generate and source immediately
source <(xcom-rs completion --shell bash)

# Or persist to a file (reload your shell afterwards)
xcom-rs completion --shell bash > ~/.local/share/bash-completion/completions/xcom-rs

Zsh

# Generate and source immediately
source <(xcom-rs completion --shell zsh)

# Or add to your fpath (e.g. ~/.zsh/completions/)
mkdir -p ~/.zsh/completions
xcom-rs completion --shell zsh > ~/.zsh/completions/_xcom-rs

# Ensure the directory is in your fpath (add to ~/.zshrc if not already present)
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Fish

xcom-rs completion --shell fish | source

# Or persist to the completions directory
xcom-rs completion --shell fish > ~/.config/fish/completions/xcom-rs.fish

Contributing

For developer setup, workflows, and repository layout, see CONTRIBUTING.md.

Docs

• CLI examples: docs/examples.md
• Implementation notes: docs/implementation/
• Validation reports: docs/validation/

License

MIT