Start with a practice run.

1. Install the tool

You need Python 3.11 or newer. Use either of these:

pipx install sociyx

uv tool install sociyx

For Instagram, add the optional extra, for example pipx install "sociyx[instagram]" or uv tool install "sociyx[instagram]".

Check it works:

sociyx --help

2. Get the browser used for logins

Logins happen in a visible Chromium window that Playwright manages, so you type your password and pass MFA yourself. Download that browser once:

uv tool run --from sociyx playwright install chromium

If your installer keeps tools in isolated environments, as pipx and uv do, the playwright command lives inside sociyx's environment, which is why the line above runs it through sociyx. If Chromium later reports missing system libraries on Linux, the same command with install-deps chromium installs them (it uses sudo for apt packages).

If Playwright's Chromium cannot start at all, sociyx falls back to opening your default browser for OAuth logins.

3. First run: practice on fake data

Demo mode shows fake accounts and data in a throw-away folder. Your real data is not touched and no platform is contacted.

sociyx tui --demo

Running sociyx with no arguments in a terminal opens the same guided UI for real accounts. The flow is Home, Account, Scan, Browse and select, Review, Run, Results. Press ? for key help.

Prefer a browser?

The local web UI runs on your own computer. Practice with the same fake data first:

sociyx ui --demo

Run sociyx ui for real accounts. The server listens only on your computer, and real platform login and deletion through this UI remain unverified. Keep it running in your terminal while you use it.

Prefer plain commands? The same practice flow works with the fake fixture platform:

sociyx login fixture --account alice
sociyx scan fixture
sociyx list fixture --type post --limit 10
sociyx plan create fixture --type post
sociyx plan list

That prints a plan ID. sociyx plan show PLAN_ID --all lists every item, and sociyx plan execute PLAN_ID is a dry run that deletes nothing and prints the live command.

4. Your first real account

Log in, scan, and look before you plan. For Bluesky:

sociyx login bluesky --account you.bsky.social
sociyx scan bluesky
sociyx list bluesky --type post --limit 20

The same pattern works for mastodon (--account @you@your.instance) and instagram. Create a plan with filters that match one to three items, review it with plan show PLAN_ID --all, and run the dry run. Copy the printed live command only when you are sure. Then sociyx report PLAN_ID shows the per-item results.

Filters available when listing and planning include --type, --since, --until, --keyword and --exclude-keyword.

Where your data lives

In ~/.local/share/sociyx, or $XDG_DATA_HOME/sociyx. Set SOCIYX_HOME to use another folder. See the safety page for how to remove it.

Upgrade or uninstall

pipx upgrade sociyx      # or: uv tool upgrade sociyx
pipx uninstall sociyx    # or: uv tool uninstall sociyx

Uninstalling the tool leaves your data folder in place. Delete it yourself if you want it gone.