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 under ~/.local/share/syncropel/backups/instance-<did-tail>/ (a per-instance directory keyed by the instance DID) 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 with 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/instance-<did-tail>/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, with 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 create 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 instance you sync with. 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 synced 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/instance-<did-tail>/hub.db.bak

The directory is keyed by the 24-hex tail of the instance DID. After a reset the instance that wrote it is gone, so just list what's there:

ls ~/.local/share/syncropel/backups/*/

Restore:

spl stop
cp ~/.local/share/syncropel/backups/instance-<tail>/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)