Repository navigation
CLI reference
Generated by packaging/scripts/gen-cli-docs.py. Do not hand-edit.
Show the most recent alert deliveries, newest first.
Usage: findplus alerts deliveries [OPTIONS]
| option | default | help |
|---|---|---|
| --limit | 100 | |
| --json | Output JSON. |
Create an alert rule for a place, targeting a group or a single device.
Usage: findplus alerts rules add [OPTIONS]
| option | default | help |
|---|---|---|
| --group | ||
| --device-id | ||
| --place | ||
| --enter | ||
| --exit | ||
| --channel | Repeatable: --channel telegram --channel native. | |
| --cooldown | 30 | |
| --also-notify-members | ||
| --telegram-target | Repeatable: limit Telegram delivery to this saved chat id. Omit for every saved target. | |
| --telegram-all | Send to every saved Telegram target (the default). |
Edit an alert rule; only the given options change.
Usage: findplus alerts rules edit [OPTIONS]
| option | default | help |
|---|---|---|
| --name | Rename the rule. | |
| --place | ||
| --enter | ||
| --exit | ||
| --channel | Repeatable; passing any --channel replaces the whole set. | |
| --cooldown | ||
| --enable | ||
| --telegram-target | Repeatable: limit Telegram delivery to this saved chat id. | |
| --telegram-all | Switch back to every saved Telegram target. |
List every alert rule.
Usage: findplus alerts rules list [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Output JSON. |
Delete an alert rule.
Usage: findplus alerts rules remove [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm removal. |
Remove the stored Telegram bot token and chat id.
Usage: findplus alerts telegram-clear [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm clearing the Telegram configuration. |
Connect a Telegram bot: verify the token, then wait for the user to message it.
Usage: findplus alerts telegram-setup [OPTIONS]
| option | default | help |
|---|---|---|
| --token, -t | Bot token (prompted if omitted). | |
| --wait | 120 | Seconds to wait for a message. |
Replace the Telegram target list: chat ids or @usernames, comma separated.
Usage: findplus alerts telegram-targets [OPTIONS]
Send a test alert through the given channel.
Usage: findplus alerts test [OPTIONS]
| option | default | help |
|---|---|---|
| --channel |
Remove the stored webhook URL and secret.
Usage: findplus alerts webhook-clear [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm clearing the webhook configuration. |
Configure the webhook channel.
Usage: findplus alerts webhook-set [OPTIONS]
| option | default | help |
|---|---|---|
| --secret, -s | HMAC signing secret (optional). |
Remove the stored WhatsApp phone and apikey.
Usage: findplus alerts whatsapp clear [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm clearing the WhatsApp configuration. |
Configure the WhatsApp (CallMeBot) channel.
Usage: findplus alerts whatsapp set [OPTIONS]
| option | default | help |
|---|---|---|
| --phone | E.164 phone number, e.g. +34123123123. | |
| --apikey | CallMeBot API key. |
Register an accessory from a pairing --plist export or a --private-key.
Usage: findplus apple add-accessory [OPTIONS]
| option | default | help |
|---|---|---|
| --plist | ||
| --private-key |
List every registered accessory.
Usage: findplus apple list [OPTIONS]
Remove a registered accessory by its device ID.
Usage: findplus apple remove [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm removal. |
Sign in to a provider (Google via Chrome, or Apple interactively).
Usage: findplus auth [OPTIONS]
| option | default | help |
|---|---|---|
| --status | Print sign-in status and exit. | |
| --json | With --status, print JSON instead of a table. | |
| --sign-out | Remove this provider's saved sign-in credential and exit. | |
| --token | Google: sign in in your own Chrome and paste the oauth_token cookie (or set FINDPLUS_OAUTH_TOKEN). | |
| --unlock | Google: unlock encrypted locations with your Android phone's screen lock, in a Find+ Chrome window. | |
| --helper | Google: sign in through the Find+ helper in your own Chrome (the default in a terminal when the service is running), or skip it and use the separate window. | |
| --provider | google-find-hub | Provider to authenticate: google-find-hub or apple-find-my |
Print the value of KEY from config.env, or empty if unset.
Usage: findplus config get [OPTIONS]
Print all KEY=VALUE pairs in config.env.
Usage: findplus config list [OPTIONS]
Print the path to config.env.
Usage: findplus config path [OPTIONS]
Write KEY=VALUE to config.env after validating through Settings.
Usage: findplus config set [OPTIONS]
Remove KEY from config.env.
Usage: findplus config unset [OPTIONS]
A person's day in plain words: when they left, arrived and where they are.
Usage: findplus day [OPTIONS]
| option | default | help |
|---|---|---|
| --date | Local date, YYYY-MM-DD (default today). | |
| --days | 1 | Consecutive days. |
| --timezone | IANA zone (default this computer's). | |
| --json | Output JSON. | |
| --send | Also send it to the connected Telegram chat. |
Make a verified copy of the database now (kept until you delete it).
Usage: findplus db backup [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Print the result as JSON. |
List the backups on disk, newest first.
Usage: findplus db backups [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Print the list as JSON. |
Check the database for damage (quick, integrity and foreign-key checks).
Usage: findplus db check [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Print the result as JSON. |
Print the current Alembic revision of the database.
Usage: findplus db current [OPTIONS]
Load a full export (findplus export --format jsonl) into an empty database.
Usage: findplus db import [OPTIONS]
Print the absolute path to the SQLite database file.
Usage: findplus db path [OPTIONS]
Rebuild place, group and person state from the sightings (run it after an import).
Usage: findplus db rebuild-derived [OPTIONS]
| option | default | help |
|---|---|---|
| --force | Run even if Find+ looks like it is running. |
Re-score every sighting for 'looks wrong' flags (raw data is never changed).
Usage: findplus db recompute-quality [OPTIONS]
| option | default | help |
|---|---|---|
| --since | Only sightings from this local date, YYYY-MM-DD. |
Replace the database with a backup. Your current one is kept aside, not deleted.
Usage: findplus db restore [OPTIONS]
| option | default | help |
|---|---|---|
| --force | Restore even if Find+ looks like it is running. |
Run Alembic migrations to head. Safe to run repeatedly (idempotent).
Usage: findplus db upgrade [OPTIONS]
List the trackers Find+ knows about and choose which ones to track.
Usage: findplus devices [OPTIONS]
| option | default | help |
|---|---|---|
| --track | Track this device id (repeatable). | |
| --track-all | Track every device on the account. | |
| --untrack | Stop tracking a device id. | |
| --default | Device the dashboard opens on. | |
| --refresh | Re-query Find Hub for the list before printing it (needs a signed-in account). | |
| --json | Print the device list as JSON. |
List the available Lucide icon ids.
Usage: findplus devices icons [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Output JSON. |
Set a device's label, icon and/or color.
Usage: findplus devices label [OPTIONS]
| option | default | help |
|---|---|---|
| --label | Your own name for this tracker. | |
| --icon | lucide:, letter:, letter, none. | |
| --color | Lowercase #rrggbb. |
Diagnose the installation; with --repair, fix what can be fixed.
Usage: findplus doctor [OPTIONS]
| option | default | help |
|---|---|---|
| --repair | Attempt automatic fixes for repairable checks. | |
| --json | Print machine-readable JSON. |
Export history to CSV, JSON, GPX or KML; --format jsonl exports the whole database.
Usage: findplus export [OPTIONS]
| option | default | help |
|---|---|---|
| --format | csv | jsonl exports everything (devices, places, groups, rules) for findplus import. |
| --day | Single local day, YYYY-MM-DD. | |
| --start | Range start, YYYY-MM-DD. | |
| --end | Range end, YYYY-MM-DD. | |
| --all | Export the entire history. | |
| --device-id | Limit to one device. Omit for all devices. | |
| --group | Export every member's track (never merged). | |
| --output, -o |
Create a new device group.
Usage: findplus groups add [OPTIONS]
| option | default | help |
|---|---|---|
| --color | #27ae60 | |
| --quorum | majority | |
| --cluster-radius | 150 | |
| --stale-after | 90 | |
| --member | Device id; repeatable. |
Update one or more fields of an existing group.
Usage: findplus groups edit [OPTIONS]
| option | default | help |
|---|---|---|
| --name | ||
| --color | ||
| --quorum | ||
| --cluster-radius | ||
| --stale-after |
List group ENTER/EXIT crossings that met quorum.
Usage: findplus groups events [OPTIONS]
| option | default | help |
|---|---|---|
| --group | ||
| --place | ||
| --since | ||
| --until | ||
| --limit | 200 | |
| --format | table |
List every device group.
Usage: findplus groups list [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Output JSON. |
Replace a group's membership (full replace, not merge).
Usage: findplus groups members [OPTIONS]
| option | default | help |
|---|---|---|
| --set | Comma-separated device ids. |
Show live group presence: verdict, note, and a per-device table.
Usage: findplus groups presence [OPTIONS]
| option | default | help |
|---|---|---|
| --window | 60 | |
| --json | Output JSON. |
Delete a group and its membership rows.
Usage: findplus groups remove [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm removal. |
Load a full export (findplus export --format jsonl) into an empty database.
Usage: findplus import [OPTIONS]
Start the background service: auth check, then discover-and-track, then
Usage: findplus install-service [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Write and load the service files without asking. | |
| --no-open | Do not open the dashboard in a browser. | |
| --program, -P | Path to the daemon executable. The desktop app passes /Applications/Find+.app/Contents/MacOS/findplus-daemon here. | |
| --no-track-all | Discover devices but do not track them. |
Show, then optionally install, the watchdog job.
Usage: findplus install-watchdog [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Skip the confirmation prompt. |
Forgot your PIN? Remove the app lock from this machine.
Usage: findplus lock reset [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Skip the confirmation prompt. |
Start the Find+ MCP server (stdio transport).
Usage: findplus mcp [OPTIONS]
| option | default | help |
|---|---|---|
| --allow-writes | Register write tools (poll, places, groups, lock). | |
| --url | http://127.0.0.1:8647 | Base URL of the local Find+ daemon. |
Open the dashboard in the default browser.
Usage: findplus open [OPTIONS]
Create the suggested people (by --key or --all), or dismiss suggestions.
Usage: findplus people accept [OPTIONS]
| option | default | help |
|---|---|---|
| --key | A suggestion key from people suggest. |
|
| --all | Accept every suggestion as shown. | |
| --dismiss | A suggestion key to dismiss. | |
| --kind | Override the kind. | |
| --json | Output JSON. |
Show or change the evening summary (off until you turn it on).
Usage: findplus people digest [OPTIONS]
| option | default | help |
|---|---|---|
| --on | Switch the evening summary. | |
| --time | HH:MM, 24-hour (default 20:00). | |
| --person | Name or id; repeat for several. | |
| --all-people | Send for every person and pet. | |
| --channel | ||
| --always-send | Also send on a day with nothing tracked. | |
| --combined | One message for everyone (default), or one message per person. | |
| --json | Output JSON. |
Every person and pet, its trackers and where it likely is now.
Usage: findplus people list [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Output JSON. |
Set a tracker's role (phone, bag, shoes...) and optionally its carry weight.
Usage: findplus people set-role [OPTIONS]
| option | default | help |
|---|---|---|
| --weight | Carry weight 0 to 1 (default: role's). |
Preview people suggested from tracker names. Nothing is saved.
Usage: findplus people suggest [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Output JSON. |
Delete the PIN and turn the app lock off.
Usage: findplus pin reset [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Skip the confirmation prompt. |
Save a new place.
Usage: findplus places add [OPTIONS]
| option | default | help |
|---|---|---|
| --lat | Latitude (decimal degrees). | |
| --lon | Longitude (decimal degrees). | |
| --radius | Radius in metres. | |
| --color | #2f80ed | |
| --enter-confirmations | 1 | |
| --exit-confirmations | 2 |
Update one or more fields of an existing place.
Usage: findplus places edit [OPTIONS]
| option | default | help |
|---|---|---|
| --name | ||
| --lat | ||
| --lon | ||
| --radius | ||
| --color | ||
| --enter-confirmations | ||
| --exit-confirmations |
List geofence ENTER/EXIT events.
Usage: findplus places events [OPTIONS]
| option | default | help |
|---|---|---|
| --place | ||
| --device-id | ||
| --since | ||
| --until | ||
| --limit | 200 | |
| --format | table |
List every saved place.
Usage: findplus places list [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Output JSON. |
Delete a place. Requires --yes.
Usage: findplus places remove [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm removal. |
List places Find+ noticed from long stays (nothing is saved).
Usage: findplus places suggest [OPTIONS]
| option | default | help |
|---|---|---|
| --days | 30 | |
| --timezone | IANA zone; default is this computer's. | |
| --date | Last local day to look at (YYYY-MM-DD). | |
| --json | Output JSON. |
Run a single Find Hub poll immediately.
Usage: findplus poll-now [OPTIONS]
| option | default | help |
|---|---|---|
| --device-id | Poll only this device id (repeatable). Default: every tracked device. |
List installed location providers and whether they are ready to poll.
Usage: findplus providers [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Output as JSON |
Delete history before a date. Dry run unless --yes is given.
Usage: findplus prune [OPTIONS]
| option | default | help |
|---|---|---|
| --before | Delete observations before this local date. | |
| --yes | Actually delete. Without this it is a dry run. |
Forgot your PIN? Remove the app lock from this machine.
Usage: findplus reset-lock [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Skip the confirmation prompt. |
Restart the background service.
Usage: findplus restart [OPTIONS]
Check that this install can start sign-in helpers and has Apple support.
Usage: findplus selfcheck [OPTIONS]
| option | default | help |
|---|---|---|
| --no-apple | Skip the Apple Find My library check. |
Start the local API/UI and (unless disabled) the polling service.
Usage: findplus serve [OPTIONS]
| option | default | help |
|---|---|---|
| --foreground | Run in this terminal (used by the service). | |
| --no-poller | Serve the UI/API without polling Google. | |
| --host | ||
| --port |
Guided first-run setup: sign-in, devices, groups, places, notifications, app lock.
Usage: findplus setup [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Non-interactive: accept every default, skip every optional step. |
Start the background service: auth check, then discover-and-track, then
Usage: findplus start [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Write and load the service files without asking. | |
| --no-open | Do not open the dashboard in a browser. | |
| --program, -P | Path to the daemon executable. The desktop app passes /Applications/Find+.app/Contents/MacOS/findplus-daemon here. | |
| --no-track-all | Discover devices but do not track them. |
Show service, watchdog and daemon status.
Usage: findplus status [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Print machine-readable JSON. |
Stop the background service. Unit files are kept; the next login (or
Usage: findplus stop [OPTIONS]
Set the dashboard theme without opening the UI.
Usage: findplus theme [OPTIONS]
Show stays, trips and gaps for one device. Distances are approximate.
Usage: findplus trips [OPTIONS]
| option | default | help |
|---|---|---|
| --device-id | Device to show. Optional when one is tracked. | |
| --date | Local date, YYYY-MM-DD. Default today. | |
| --days | 1 | Number of days from --date. |
| --timezone | IANA zone. Default this computer's. | |
| --json | Print the API payload as JSON. |
Unload and delete the service and watchdog unit files, and daemon.json.
Usage: findplus uninstall [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Unload and delete the unit files without asking. |
Turn automatic updates on or off. Off: no update request unless you ask.
Usage: findplus update auto [OPTIONS]
Ask GitHub for the newest release now (one request, nothing about you is sent).
Usage: findplus update check [OPTIONS]
For developers: install local builds of Find+.app from PATH automatically.
Usage: findplus update dev-dir [OPTIONS]
| option | default | help |
|---|---|---|
| --clear | Stop using a developer build folder. |
Show the installed version and what the updater has found.
Usage: findplus update status [OPTIONS]
Print the installed version.
Usage: findplus version [OPTIONS]
| option | default | help |
|---|---|---|
| --check | Check for a newer release on GitHub. |
Check the local API and restart the service if it is not answering.
Usage: findplus watchdog [OPTIONS]
Ask the Find+ app to reload the widget's WidgetKit timelines.
Usage: findplus widget refresh [OPTIONS]
Show or hide the map preview in the large widget.
Usage: findplus widget show-map [OPTIONS]