Skip to content

CLI reference

github-actions[bot] edited this page Sep 27, 2026 · 17 revisions

CLI reference

Generated by packaging/scripts/gen-cli-docs.py. Do not hand-edit.

findplus alerts deliveries

Show the most recent alert deliveries, newest first.

Usage: findplus alerts deliveries [OPTIONS]

option default help
--limit 100
--json Output JSON.

findplus alerts rules add

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).

findplus alerts rules edit

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.

findplus alerts rules list

List every alert rule.

Usage: findplus alerts rules list [OPTIONS]

option default help
--json Output JSON.

findplus alerts rules remove

Delete an alert rule.

Usage: findplus alerts rules remove [OPTIONS]

option default help
--yes Confirm removal.

findplus alerts telegram-clear

Remove the stored Telegram bot token and chat id.

Usage: findplus alerts telegram-clear [OPTIONS]

option default help
--yes Confirm clearing the Telegram configuration.

findplus alerts telegram-setup

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.

findplus alerts telegram-targets

Replace the Telegram target list: chat ids or @usernames, comma separated.

Usage: findplus alerts telegram-targets [OPTIONS]

findplus alerts test

Send a test alert through the given channel.

Usage: findplus alerts test [OPTIONS]

option default help
--channel

findplus alerts webhook-clear

Remove the stored webhook URL and secret.

Usage: findplus alerts webhook-clear [OPTIONS]

option default help
--yes Confirm clearing the webhook configuration.

findplus alerts webhook-set

Configure the webhook channel.

Usage: findplus alerts webhook-set [OPTIONS]

option default help
--secret, -s HMAC signing secret (optional).

findplus alerts whatsapp clear

Remove the stored WhatsApp phone and apikey.

Usage: findplus alerts whatsapp clear [OPTIONS]

option default help
--yes Confirm clearing the WhatsApp configuration.

findplus alerts whatsapp set

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.

findplus apple add-accessory

Register an accessory from a pairing --plist export or a --private-key.

Usage: findplus apple add-accessory [OPTIONS]

option default help
--plist
--private-key

findplus apple list

List every registered accessory.

Usage: findplus apple list [OPTIONS]

findplus apple remove

Remove a registered accessory by its device ID.

Usage: findplus apple remove [OPTIONS]

option default help
--yes Confirm removal.

findplus auth

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.
--provider google-find-hub Provider to authenticate: google-find-hub or apple-find-my

findplus config get

Print the value of KEY from config.env, or empty if unset.

Usage: findplus config get [OPTIONS]

findplus config list

Print all KEY=VALUE pairs in config.env.

Usage: findplus config list [OPTIONS]

findplus config path

Print the path to config.env.

Usage: findplus config path [OPTIONS]

findplus config set

Write KEY=VALUE to config.env after validating through Settings.

Usage: findplus config set [OPTIONS]

findplus config unset

Remove KEY from config.env.

Usage: findplus config unset [OPTIONS]

findplus db current

Print the current Alembic revision of the database.

Usage: findplus db current [OPTIONS]

findplus db path

Print the absolute path to the SQLite database file.

Usage: findplus db path [OPTIONS]

findplus db upgrade

Run Alembic migrations to head. Safe to run repeatedly (idempotent).

Usage: findplus db upgrade [OPTIONS]

findplus devices

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.

findplus devices icons

List the available Lucide icon ids.

Usage: findplus devices icons [OPTIONS]

option default help
--json Output JSON.

findplus devices label

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.

findplus doctor

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.

findplus export

Export history to CSV, JSON, GPX or KML.

Usage: findplus export [OPTIONS]

option default help
--format csv
--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

findplus groups add

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.

findplus groups edit

Update one or more fields of an existing group.

Usage: findplus groups edit [OPTIONS]

option default help
--name
--color
--quorum
--cluster-radius
--stale-after

findplus groups events

List group ENTER/EXIT crossings that met quorum.

Usage: findplus groups events [OPTIONS]

option default help
--group
--place
--since
--until
--limit 200
--format table

findplus groups list

List every device group.

Usage: findplus groups list [OPTIONS]

option default help
--json Output JSON.

findplus groups members

Replace a group's membership (full replace, not merge).

Usage: findplus groups members [OPTIONS]

option default help
--set Comma-separated device ids.

findplus groups presence

Show live group presence: verdict, note, and a per-device table.

Usage: findplus groups presence [OPTIONS]

option default help
--window 60
--json Output JSON.

findplus groups remove

Delete a group and its membership rows.

Usage: findplus groups remove [OPTIONS]

option default help
--yes Confirm removal.

findplus install-service

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.

findplus install-watchdog

Show, then optionally install, the watchdog job.

Usage: findplus install-watchdog [OPTIONS]

option default help
--yes Skip the confirmation prompt.

findplus lock reset

Forgot your PIN? Remove the app lock from this machine.

Usage: findplus lock reset [OPTIONS]

option default help
--yes Skip the confirmation prompt.

findplus mcp

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.

findplus open

Open the dashboard in the default browser.

Usage: findplus open [OPTIONS]

findplus pin reset

Delete the PIN and turn the app lock off.

Usage: findplus pin reset [OPTIONS]

option default help
--yes Skip the confirmation prompt.

findplus places add

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

findplus places edit

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

findplus places events

List geofence ENTER/EXIT events.

Usage: findplus places events [OPTIONS]

option default help
--place
--device-id
--since
--until
--limit 200
--format table

findplus places list

List every saved place.

Usage: findplus places list [OPTIONS]

option default help
--json Output JSON.

findplus places remove

Delete a place. Requires --yes.

Usage: findplus places remove [OPTIONS]

option default help
--yes Confirm removal.

findplus poll-now

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.

findplus providers

List installed location providers and whether they are ready to poll.

Usage: findplus providers [OPTIONS]

option default help
--json Output as JSON

findplus prune

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.

findplus reset-lock

Forgot your PIN? Remove the app lock from this machine.

Usage: findplus reset-lock [OPTIONS]

option default help
--yes Skip the confirmation prompt.

findplus restart

Restart the background service.

Usage: findplus restart [OPTIONS]

findplus selfcheck

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.

findplus serve

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

findplus setup

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.

findplus start

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.

findplus status

Show service, watchdog and daemon status.

Usage: findplus status [OPTIONS]

option default help
--json Print machine-readable JSON.

findplus stop

Stop the background service. Unit files are kept; the next login (or

Usage: findplus stop [OPTIONS]

findplus theme

Set the dashboard theme without opening the UI.

Usage: findplus theme [OPTIONS]

findplus uninstall

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.

findplus version

Print the installed version.

Usage: findplus version [OPTIONS]

option default help
--check Check for a newer release on GitHub.

findplus watchdog

Check the local API and restart the service if it is not answering.

Usage: findplus watchdog [OPTIONS]

findplus widget refresh

Ask the Find+ app to reload the widget's WidgetKit timelines.

Usage: findplus widget refresh [OPTIONS]

findplus widget show-map

Show or hide the map preview in the large widget.

Usage: findplus widget show-map [OPTIONS]

Clone this wiki locally