Metadata-Version: 2.5
Name: tweetnook
Version: 0.1.0
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: platformdirs>=4.9.4
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'
Provides-Extra: legacy-migration
Requires-Dist: lancedb<0.35,>=0.34; extra == 'legacy-migration'
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.

Want to see TweetNook before installing it? [View the live demo](https://gezerwezer.github.io/tweetnook/).

## 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 [TweetXVault](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).


## 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
````

If you need to migrate from a TweetXVault LanceDB archive, install the migration support too:

```bash
python3 -m pip install "tweetnook[legacy-migration]"
```

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
```

### Update TweetNook

For an installation created by `tweetnook service install`, update TweetNook with:

```bash
sudo tweetnook update
```

The command gracefully stops active Web and scheduled work, upgrades TweetNook in the exact Python
environment recorded by the managed systemd service, and restarts the service afterward.

### 3. Open TweetNook

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

```text
http://[Machine IP]:8000
```

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


## Everyday use

### Keep your archive up to date

Run a sync from the sync menu or `tweetnook sync` 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.

For a full list of CLI sync commands, see [syncing](docs/syncing.md).

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
```

See [Search](docs/search.md) for all filters and search behavior.

### 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.

## 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`.

>[!IMPORTANT]
> Please read [Automated tagging](docs/automated-tagging.md) before enabling.

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
```

### 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.

## Your files

| 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.


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.


## 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.
