Syncthing CLI Helper

A tiny command‑line wrapper around the Syncthing REST API. It lets you quickly inspect folders, see sync status, list recently synced files, poke the raw API, and more.

---

Features

• List folders configured in Syncthing
• Browse a folder’s files (optionally show mtime, depth‑limit, strip folder prefix)
• Show sync status (in‑progress, queued, the rest)
• See the last N synced files
• Hit the raw API for anything not yet wrapped
• Show config
• List devices

---

Requirements

• Python 3.8+
• A running Syncthing instance with its GUI/API enabled
• Your Syncthing API key (read from the SYNCTHING_API_KEY env var or auto‑discovered via local_api_key())

Default API host: http://localhost:8384

---

Installation

Clone the repo and install:

git clone <this-repo>
cd <this-repo>
pip install -e .

Or install via git url

pip install --user git+https://git.linuxhomelab.net/nc/syncthing_cli

You can then run it via the installed console script:

syncli ...

---

Authentication

The script looks for a key in this order:

1. SYNCTHING_API_KEY environment variable
2. local_api_key() (reads from your local Syncthing config)

If neither is found, it exits with: Can't find a api key.

Set it explicitly if needed:

export SYNCTHING_API_KEY=xxxxxxxxxxxxxxxx

---

Usage

syncli [--host HOST] [--api-key KEY] <command> [options]

Global options

• --host (default: http://localhost:8384)
• --api-key (default: env SYNCTHING_API_KEY or discovered with local_api_key())

---

Commands

folders list

List all configured folders.

syncli folders list

---

browse

Browse files inside a folder.

Options:

• --folder, -f (required): folder ID/name to browse
• --depth, -d (default: -1, infinite)
• --remove-name, -r: strip the folder name from the output
• --show-modified, -m: include modification timestamps

Example:

syncli browse -f photos -d 2 -m

---

status

Show sync status for a folder (or all folders).

Options:

• --folder, -f: specific folder
• --show-progress, -p (default: True): show files currently syncing
• --show-queued, -q (default: False): show queued files
• --show-rest, -r (default: False): show everything else

Example:

syncli status -f docs -p -q

---

last-synced

Show the last N synced files.

Options:

• --amount, -a (default: 10)
• --folder, -f: specific folder
• --show-modified, -m: include modification timestamps
• --remove-name, -r: strip folder name from the output

Example:

syncli last-synced -a 25 -f media -m

---

api

Fire a raw request at the Syncthing REST API.

Options:

• --url, -u: path (e.g. /rest/system/status)
• --args: JSON or query args the underlying helper expects

Example:

syncli api -u /rest/system/status

---

config

Print the current Syncthing config.

syncli config

---

devices list

List devices known to this node.

syncli devices list

---

Examples

# List folders
syncli folders list

# See what’s syncing right now across all folders
syncli status -p

# Show queued files for a single folder
syncli status -f media -q

# Show the last 50 synced files across all folders with mtimes
syncli last-synced -a 50 -m

# Browse a folder to depth 1, without folder prefix
syncli browse -f docs -d 1 -r

# Hit any API endpoint directly
syncli api -u /rest/system/error

---

Troubleshooting

• Can't find a api key Export SYNCTHING_API_KEY or ensure local_api_key() can read your Syncthing config.

• Connection errors Verify --host matches your Syncthing GUI/API address and that the API is enabled.

---

Contributing

Issues and PRs welcome! Please keep CLI flags and help messages consistent and documented here.

---