Skip to content

CLI reference

github-actions[bot] edited this page Oct 3, 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.
--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

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 day

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.

findplus db backup

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.

findplus db backups

List the backups on disk, newest first.

Usage: findplus db backups [OPTIONS]

option default help
--json Print the list as JSON.

findplus db check

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.

findplus db current

Print the current Alembic revision of the database.

Usage: findplus db current [OPTIONS]

findplus db import

Load a full export (findplus export --format jsonl) into an empty database.

Usage: findplus db import [OPTIONS]

findplus db path

Print the absolute path to the SQLite database file.

Usage: findplus db path [OPTIONS]

findplus db rebuild-derived

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.

findplus db recompute-quality

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.

findplus db restore

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.

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; --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

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 import

Load a full export (findplus export --format jsonl) into an empty database.

Usage: findplus import [OPTIONS]

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 people accept

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.

findplus people digest

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.

findplus people list

Every person and pet, its trackers and where it likely is now.

Usage: findplus people list [OPTIONS]

option default help
--json Output JSON.

findplus people set-role

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

findplus people suggest

Preview people suggested from tracker names. Nothing is saved.

Usage: findplus people suggest [OPTIONS]

option default help
--json Output JSON.

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 places suggest

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.

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 trips

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.

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 update auto

Turn automatic updates on or off. Off: no update request unless you ask.

Usage: findplus update auto [OPTIONS]

findplus update check

Ask GitHub for the newest release now (one request, nothing about you is sent).

Usage: findplus update check [OPTIONS]

findplus update dev-dir

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.

findplus update status

Show the installed version and what the updater has found.

Usage: findplus update status [OPTIONS]

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