Metadata-Version: 2.5
Name: tweetnook
Version: 0.0.9
Summary: Self-hosted Web archive for Twitter/X bookmarks, likes, tweets, and official exports.
Project-URL: Homepage, https://github.com/gezerwezer/tweetnook
Project-URL: Repository, https://github.com/gezerwezer/tweetnook
Project-URL: Issues, https://github.com/gezerwezer/tweetnook/issues
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: archive,bookmarks,cli,tweets,twitter/x
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: fastapi<1,>=0.110
Requires-Dist: httpx<1,>=0.27
Requires-Dist: lancedb<0.35,>=0.34
Requires-Dist: loguru<1,>=0.7
Requires-Dist: platformdirs>=4.9.4
Requires-Dist: pyarrow<23,>=20
Requires-Dist: pydantic<3,>=2
Requires-Dist: rich<14,>=13
Requires-Dist: tqdm<5,>=4.66
Requires-Dist: typer<1,>=0.12
Requires-Dist: uvicorn<1,>=0.29
Provides-Extra: automated-tagging
Requires-Dist: google-genai<3,>=2.12.1; extra == 'automated-tagging'
Requires-Dist: pillow<12.0,>=10.0; extra == 'automated-tagging'
Description-Content-Type: text/markdown

# TweetNook

TweetNook is a self-hosted archive for your Twitter/X bookmarks, likes, and tweets.
Run it on your own computer or  server, import an archive downloaded from
Twitter/X, keep it updated with automated syncs, and browse everything in a Web UI from
your network. Search by words, author, date, or tag to find something you saved
without scrolling through your account.

## Features

- **Archive your tweets:** save bookmarks, likes, and your own tweets, along with replies and quoted tweets
- **Import existing data:** bring in an official Twitter/X archive.
- **Browse in your browser:** read saved threads, view photos and videos, and
  explore quoted tweets and articles.
- **Search and organize:** combine search filters, add your own tags, and edit
  local descriptions.
- **Automated tagging:** with an optional add-on, you can use Gemini to suggest tags and describe media.
- **Keep it up to date:** run a sync from the web app or terminal, or schedule
  regular syncs.
- **Unavailable-tweet recovery:** periodically recheck
  for unavailable tweets that might return.
- **Export your collection:** save tweet data as JSON for use in other tools.

## Project background

This project began as a fork of the [upstream project](https://github.com/lhl/tweetxvault),
which provides the foundation for this work. This version is developed independently.

Thanks to [rrika](https://github.com/rrika) for sharing their
[archive like-order research](https://github.com/lhl/tweetxvault/issues/2).

> [!NOTE]
> If you are upgrading from an older upstream installation that uses LanceDB, see the [migration instructions](docs/maintenance.md#upgrade-or-migrate-an-older-archive).

The original project provides the foundation for syncing, archive imports, media
downloads, thread expansion, article retrieval, and link previews. This fork is
developed independently and continues to build on that foundation.

## Getting started

You need **macOS or Linux** and **Python 3.12 or newer**. Live syncing also needs
a browser signed in to your Twitter/X account. You can import a downloaded archive
without connecting to Twitter/X first.

### 1. Install

Install TweetNook with pip:

```bash
python3 -m pip install tweetnook
````

To include automated tagging support:

```bash
python3 -m pip install "tweetnook[automated-tagging]"
```

### 2. Install the service

For a persistent homelab/server installation, install TweetNook as a system service:

```bash
sudo tweetnook service install
```

This installs and enables the TweetNook service so it starts automatically at boot and keeps running in the background.

Check its status with:

```bash
tweetnook service status
```

You can also manage it with:

```bash
sudo tweetnook service restart
sudo tweetnook service stop
sudo tweetnook service start
```

### 3. Open TweetNook

After the service starts, open the Web UI using the address shown by TweetNook, for example:

```text
http://192.168.1.50:8000
```

On first launch, the Web UI will guide you through setup.


## Everyday use

### Keep your archive up to date

Run `tweetnook sync` again whenever you want to save new bookmarks and likes.
To automate it, open **Settings → Schedule**, choose when to run, and save.
The TweetNook server/service must stay running for scheduled syncs to work;
the browser can be closed. Your own tweets still use the separate
`tweetnook sync tweets` command.

| Task | Command |
|---|---|
| Save bookmarks only | `tweetnook sync bookmarks` |
| Save likes only | `tweetnook sync likes` |
| Continue collecting older history | `tweetnook sync --backfill` |
| Limit collection to five pages each | `tweetnook sync --limit 5` |
| Skip media downloads for this sync | `tweetnook sync --skip-media` |
| View archive counts and progress | `tweetnook stats` |
| Browse the latest saved tweets in the terminal | `tweetnook view all --limit 20` |

A sync page normally contains up to 20 tweets; `--limit` counts pages, not tweets.
The limit does not bound all follow-up work. Run one archive job at a time and
read the final summary for any downloads or lookups that need another attempt.

Use **Stop Task** in the web app or **Ctrl+C** in the terminal to interrupt a job.
Wait for it to finish stopping before starting another. Stopping TweetNook also asks its active Web or scheduled job to stop gracefully,
preserving already committed work.

### Search saved tweets

Type words and filters together in the web app's search box:

| Find… | Query |
|---|---|
| An exact phrase | `"night sky"` |
| Images from an author | `from:alice has:image` |
| Tweets from January 2026 | `since:2026-01-01 until:2026-02-01` |
| A local tag | `tag:"read later"` |
| Links, excluding reposts | `has:links -is:retweet` |

The same queries work in the terminal:

```bash
tweetnook search '"night sky" has:image' --sort newest --limit 20
```

Dates use UTC, and `until` excludes the date entered. See
[Search](docs/search.md) for all filters and search limits.

### Add tags

Open a tweet's menu in the web app to add tags or a description. Click a tag to
find related tweets. **Settings → Tags** lets you merge or delete tags across
your archive.

### Fill in missing details

Normal sync handles follow-up work automatically. You can also run individual
jobs when you need them:

```bash
tweetnook import enrich
tweetnook threads expand
tweetnook media download --retry-failed
```

These commands fill in eligible missing details, expand saved conversations, and
retry media downloads. Run only the jobs you need. See
[Enrichment](docs/enrichment.md) for articles and link previews too.

## Optional Gemini tagging

Gemini can suggest tags for text and media tweets and add media descriptions.
To install support in the active pip environment:

```bash
python -m pip install "tweetnook[automated-tagging]"
```

Restart the TweetNook server afterward. For a systemd installation, use the
service restart command; for a foreground `tweetnook serve` process, stop and
start it again. Developers using uv can install the extra once with
`uv sync --extra automated-tagging`. No runtime `--extra` flag is needed.

Open **Settings → Automated Tagging**, enable the controls, enter your Gemini API
key, choose a model and Free or Paid mode, and set the usage limits. Try one
archived tweet with **Test run**, then save when you want tagging enabled.

Once saved and enabled, tagging runs after sync. To tag existing eligible tweets
without syncing:

```bash
tweetnook tag
```

Tagging sends selected content to Google. Test runs also use real requests and
can consume quota or incur charges, though they do not save generated tags.
Read [Automated tagging](docs/automated-tagging.md) for setup, privacy,
and spend controls.

## Your files and backups

| System | Default data folder |
|---|---|
| macOS | `~/Library/Application Support/tweetnook` |
| Linux | `~/.local/share/tweetnook` |

The folder contains the archive database, downloaded media, tags, and activity
history. [Configuration](docs/configuration.md#resolved-directories)
explains custom locations.

To back up, stop the app and all archive jobs, then copy the **complete data
folder** and your configuration. Keep original Twitter/X downloads separately.
[Backups and maintenance](docs/maintenance.md) covers restoring
and checking a backup.

To export tweet data for analysis or another tool:

```bash
tweetnook export json --out my-tweets.json
```

JSON exports do not include media files or everything needed to restore an
archive. Use a full folder backup for recovery.


## Documentation and help

Use `tweetnook --help` to list commands or add `--help` to a command, such as
`tweetnook sync --help`.

| Guide | Covers |
|---|---|
| [User guide](docs/README.md) | All feature guides and references |
| [Syncing](docs/syncing.md) | Older history, resuming work, and sync options |
| [Web app](docs/web-app.md) | Browsing, settings, schedules, and activity |
| [Importing](docs/importing.md) | Official Twitter/X archives |
| [Configuration](docs/configuration.md) | Settings, defaults, and file locations |
| [CLI reference](docs/cli-reference.md) | Commands and options |
| [Troubleshooting](docs/troubleshooting.md) | Common errors and next steps |
| [Development guide](docs/development/README.md) | Architecture, tests, and contribution workflow |

## License

[Apache License 2.0](LICENSE). See [upstream](https://github.com/lhl/tweetxvault)
for the original project.
