Reset and Uninstall

Two distinct operations.

• Reset wipes ~/.syncro/ (identity, keys, records, token, config) but leaves the spl binary installed and ~/.syncro-data/ (your task content) untouched. Use this when you want a clean first-run experience without reinstalling.
• Uninstall removes the spl binary itself. Use this when you're done with Syncropel on this machine.

Automatic backups at ~/.local/share/syncropel/backups/hub.db.bak are written outside ~/.syncro/, so they survive reset but not full disk cleanup. The backup is destructive — every instance start overwrites it. If you care about your records, copy them off-host before running either of the operations on this page.

Clean reset — spl reset

spl reset is the canonical way to wipe ~/.syncro/ back to a fresh state. It refuses to run while the instance is up, prints a plan of what it will touch, prompts for confirmation, and creates a timestamped backup of hub.db before deleting anything.

spl stop                                # stop the instance first
systemctl --user stop spl-serve.service         # if you use a systemd unit (reset will refuse otherwise)
spl reset                                       # interactive: print plan, prompt y/N, back up hub.db, wipe
spl init                                        # regenerate identity and config (no --force needed)
spl serve                              # start fresh

What spl reset deletes: everything inside ~/.syncro/, then ~/.syncro/ itself. The command lists the directory at reset time and removes every entry that isn't explicitly preserved by a --keep-* flag — that catches accumulated state like vfs.db*, agent/, content/, serve.log, and any old backup files without needing the reset command to know about every possible path.

What spl reset never deletes:

~/.syncro/ itself is also removed when no --keep-* flag is passed — so the next spl init works without --force. With any --keep-* flag set, the home dir is left in place containing only the kept entries, and the next spl init needs --force.

How reset detects a running instance

spl reset refuses if any of these signals are positive:

1. PID file at ~/.syncro/run/spl.pid points at a live process.
2. Unix socket at ~/.syncro/run/spl.sock accepts a connection.
3. (Default ~/.syncro/ home only) TCP 127.0.0.1:9100 accepts a connection.
4. (Linux, default home only) systemctl --user is-active spl-serve.service returns active.

Signals 3+4 are scoped to the default ~/.syncro/ home so multi-instance setups and tests using SYNCROPEL_HOME=/some/other/path aren't blocked by an unrelated instance. If you use a systemd user unit to keep spl serve running, the command will tell you to stop the unit first — bringing the instance down with just kill isn't enough because the unit will respawn it the moment state is deleted.

Common flags

spl reset --dry-run         # print plan + exit. No prompt, no backup, no deletes.
spl reset --json            # structured output for scripts and CI gates
spl reset --force           # skip the y/N confirmation
spl reset --keep-keys       # preserve identity (same DID after `spl init`)
spl reset --keep-config     # preserve config.toml (API keys + routing rules survive)
spl reset --keep-secrets    # preserve the secrets/ directory
spl reset --wipe-task-data  # also delete ~/.syncro-data/ (requires extra confirmation)

--dry-run is useful as a CI gate or a "what would this delete" check before you commit:

spl reset --dry-run --json | jq '.plan[] | select(.action == "delete")'

Windows

spl stop
spl reset
spl init
spl serve

Fallback — when spl reset itself can't run

If the spl binary is broken (a corrupt upgrade, a --insecure-localhost instance that refuses to stop, an orphaned PID file confusing the lifecycle), fall back to the manual procedure:

# Linux / macOS
spl stop || pkill -f "spl serve"
rm -rf ~/.syncro
spl init

# Windows
spl stop
Remove-Item -Recurse -Force $env:USERPROFILE\.syncro
spl init

The manual rm -rf does NOT auto-back up hub.db first, so if there's anything you want to keep, copy it off-host before running this. The instance-startup backup at ~/.local/share/syncropel/backups/hub.db.bak is your last line of defense after the fact.

After either path, you're back at the start of the onboarding flow. The spl init command prints the next steps — open the local front door at http://127.0.0.1:9100/ or pair Studio at https://syncropel.com/connect?url=http://127.0.0.1:9100.

First boot after reset

The canonical post-reset sequence is two commands:

spl init       # generate identity + config
spl serve      # start the instance in the background
# Verify
spl status   # instance healthy
spl doctor   # all green

spl task add "...", spl thread list, spl status, and every other CLI command works immediately — no service account, no bearer token, no --insecure-localhost step. The local CLI authenticates via the Unix socket at ~/.syncro/run/spl.sock (mode 0700 owned by your user); filesystem permissions are the authentication.

You only need to mint a service account when delegating scoped access to a different principal — a browser pair, a paired phone, an MCP client, a remote CLI, or another federating instance. See Service accounts and tokens.

On older instances that don't support Unix-socket trust, the legacy --insecure-localhost + service-account create --bootstrap + token save + restart-secure flow still works — but upgrading (curl get.syncropic.com/spl | sh) skips it.

Full uninstall

Linux

spl stop                                   # graceful instance shutdown
rm ~/.local/bin/spl                                # remove the binary
rm -rf ~/.syncro                                   # remove state
rm -rf ~/.local/share/syncropel                    # remove backups

If you added ~/.local/bin to PATH specifically for spl, clean that line out of your shell rc:

grep -n "/.local/bin" ~/.bashrc ~/.zshrc ~/.config/fish/config.fish 2>/dev/null

Edit by hand to remove.

Windows

spl stop
Remove-Item "$env:LOCALAPPDATA\Programs\spl" -Recurse -Force
Remove-Item $env:USERPROFILE\.syncro -Recurse -Force
Remove-Item "$env:LOCALAPPDATA\syncropel" -Recurse -Force -ErrorAction SilentlyContinue

Clean the user PATH:

$current = [Environment]::GetEnvironmentVariable('Path','User')
$updated = ($current -split ';' | Where-Object { $_ -notmatch 'spl' }) -join ';'
[Environment]::SetEnvironmentVariable('Path', $updated, 'User')

Close and reopen PowerShell for the PATH change to apply.

macOS

spl stop
rm ~/.local/bin/spl
rm -rf ~/.syncro
rm -rf ~/.local/share/syncropel

If you installed the Windows Service wrapper

Uninstall the service before removing the binary — the SCM needs spl.exe to exist for the uninstall call.

# From elevated PowerShell
spl serve --uninstall-service
# then proceed with the uninstall steps above

See the Operator runbook for Windows-specific service notes.

If you installed a systemd user unit (Linux)

systemctl --user stop spl-serve.service
systemctl --user disable spl-serve.service
rm ~/.config/systemd/user/spl-serve.service
systemctl --user daemon-reload

What survives

What a reset leaves alone

• The spl binary itself.
• Any entries you added to your shell's PATH.
• ~/.syncro-data/ (task content + alias mappings) — the operator's authored content lives in a separate directory from .syncro/ for exactly this reason. spl reset never touches it unless you pass --wipe-task-data and confirm the extra prompt. Manual rm -rf ~/.syncro doesn't touch it either.
• Backups at ~/.local/share/syncropel/backups/. The pre-reset snapshot hub.db.pre-reset.<iso8601> that spl reset writes lands here too, so reset is recoverable. Only full uninstall removes this directory.
• OS keyring entries (if you use a keyring backend). spl init overwrites the entry on next start.

What an uninstall leaves alone

• System-level PATH entries set by another tool.
• Any data you've copied out of ~/.syncro/ to elsewhere on disk.

What neither removes

• Records that were federated to another instance before the reset or uninstall. Those live on the remote peer independently.
• Git repos, source checkouts, or other project state that happens to be adjacent on disk.

Restoring from backup after a reset

If you reset by mistake, the most recent instance startup backup is at:

~/.local/share/syncropel/backups/hub.db.bak

Restore:

spl stop
cp ~/.local/share/syncropel/backups/hub.db.bak ~/.syncro/hub.db
spl serve

The identity in config.toml is independent of the records file, so a restored hub.db works with your current DID — as long as you haven't re-initialized to a new keypair in between. If you have, records will still restore but they'll be signed under the old key. See Operator runbook → Recovery for the full procedure.

See also

• Operator runbook → Backup discipline — how the automatic backup works and why off-host copies matter
• First run — what a fresh spl init creates
• Troubleshooting — when a reset is the right answer (usually it isn't)