agent-x 0.1.0

Agent-first Twitter/X CLI
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

# agent-x

Agent-first Twitter/X CLI. Binary: **`ax`**. Published as `agent-x` on crates.io.

Agents are the primary consumer, humans secondary. Full [NO_DNA](https://no-dna.org) compliance for structured, machine-readable output.

## Install

```bash
cargo install agent-x
```

Requires Rust 1.75+.

## Quick start

```bash
# Authenticate (OAuth 2.0 PKCE)
export X_CLIENT_ID="your-client-id"
ax auth login

# Post a tweet
ax tweet post "Hello from agent-x!"

# Get a tweet
ax tweet get 1234567890

# Search
ax tweet search "rust lang" --max-results 20

# User lookup
ax user get elonmusk
```

## Authentication

Three methods, resolved in priority order:

1. **OAuth 2.0 PKCE** — `ax auth login` (recommended, stored encrypted)
2. **OAuth 1.0a** — env vars `X_API_KEY`, `X_API_SECRET`, `X_ACCESS_TOKEN`, `X_ACCESS_TOKEN_SECRET`
3. **Bearer token** — env var `X_BEARER_TOKEN` (read-only)

## Command tree

```
ax [--output json|plain|markdown|human] [--verbose]
├── tweet post|get|delete|reply|quote|search|metrics
├── user get|timeline|followers|following
├── self mentions|bookmarks|like|unlike|retweet|unretweet|bookmark|unbookmark
└── auth login|status|logout
```

See `ax --help`, `ax <command> --help`, or [SKILL.md](SKILL.md) for full usage.

## Output modes

| Mode | Flag | Description |
|------|------|-------------|
| `json` | `-o json` | JSON (default when `NO_DNA=1`) |
| `plain` | `-o plain` | TSV for piping |
| `markdown` | `-o markdown` | Markdown tables |
| `human` | `-o human` | Rich terminal (default) |

## NO_DNA mode

```bash
NO_DNA=1 ax tweet get 123456
```

- JSON stdout, JSON stderr errors, no colors, no interactivity, ISO 8601 timestamps.

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Auth error |
| 3 | Not found |
| 4 | Rate limited |
| 5 | API error |

## Development

```bash
cargo build           # Build
cargo test            # Run tests
cargo clippy          # Lint
cargo run -- --help   # Run locally
```

## Project layout

```
agent-x/
├── Cargo.toml          # Package manifest
├── SKILL.md            # Agentskills spec
├── references/API.md   # X API v2 endpoint reference
├── src/
│   ├── main.rs         # Entry point, CLI dispatch
│   ├── config.rs       # RuntimeConfig (NO_DNA, output, verbosity)
│   ├── error.rs        # AgentXError enum, exit codes
│   ├── cli/            # Clap command definitions
│   ├── api/            # XClient, API types, endpoint impls
│   ├── auth/           # OAuth 2.0 PKCE, OAuth 1.0a, Bearer, token storage
│   └── output/         # Renderable trait, JSON/plain/markdown/human renderers
└── tests/              # Integration tests + fixtures
```

## License

MIT