Metadata-Version: 2.4
Name: bmarxs
Version: 0.1.1
Summary: CLI tool to export and manage X/Twitter bookmarks
Project-URL: Homepage, https://github.com/akilrammohan/bmarxs
Project-URL: Repository, https://github.com/akilrammohan/bmarxs
Project-URL: Issues, https://github.com/akilrammohan/bmarxs/issues
Author: Akil Rammohan
License-Expression: MIT
License-File: LICENSE
Keywords: bookmarks,cli,export,twitter,x
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: browser-cookie3>=0.20.1
Requires-Dist: click>=8.3.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: playwright>=1.57.0
Requires-Dist: rich>=14.2.0
Description-Content-Type: text/markdown

# bmarxs

CLI for exporting X/Twitter bookmarks. Designed for both human and agent use.

## Install

```bash
pipx install bmarxs   # Recommended
# or
uv tool install bmarxs
# or
pip install bmarxs
```

## Setup

```bash
# Import cookies from Chrome (must be logged into X, Chrome closed)
bmarxs import-cookies
```

## Commands

```bash
bmarxs sync                    # Sync new bookmarks
bmarxs sync --all --enrich     # Sync all + fetch URL metadata
bmarxs list                    # List bookmarks (table)
bmarxs list --unprocessed      # List unprocessed only
bmarxs search "query"          # Full-text search
bmarxs export                  # Export to stdout (JSON)
bmarxs export --format csv     # Export as CSV
bmarxs stats                   # Show statistics
bmarxs mark-processed ID...    # Mark as processed
bmarxs mark-unprocessed ID...  # Mark as unprocessed
bmarxs enrich                  # Enrich URLs with metadata
```

## Agent/Programmatic Use

### Global Flags

| Flag | Description |
|------|-------------|
| `--json` / `-j` | Output structured JSON |
| `--quiet` / `-q` | Suppress progress messages |

### Examples

```bash
# Get stats as JSON
bmarxs --json stats

# Sync and get structured result
bmarxs --json sync

# List unprocessed bookmarks as JSON
bmarxs --json list --unprocessed

# Export to file
bmarxs export --format json > bookmarks.json
```

### Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Auth error |
| 3 | Network error |
| 4 | Not found |
| 5 | Invalid input |
| 6 | Database error |
| 7 | Browser error |

### JSON Response Format

Success:
```json
{"success": true, "synced_count": 5, "message": "Synced 5 new bookmarks"}
```

Error:
```json
{"success": false, "error": {"code": 2, "code_name": "auth_error", "message": "Auth token not found"}}
```

## Data

Stored in `./data/` by default (override with `--data-dir`):
- `bookmarks.db` - SQLite database
- `session/state.json` - Browser session
