Every installation uses its owner's Tesla Developer application, credentials, HTTPS domain and key. The project does not provide a shared Client ID, private key or backend. Tesla approval, API access and billing requirements are controlled by Tesla.
Install xBar, Python 3.9 or newer, Go 1.23 or newer, Git, OpenSSL and Apple's Command Line Tools. On macOS with Homebrew:
xcode-select --install
brew install python go
brew install --cask xbar
git clone https://github.com/kolisko/tesla-xbar.git
cd tesla-xbar
python3 -m scripts.installThe installer builds the Swift Keychain helper and a pinned version of Tesla's official command helper. For a new profile it generates an independent P-256 key in:
~/Library/Application Support/Tesla xBar/command-key.pem
The matching public key is exported as public-key.pem in the same directory. The private key stays outside the checkout. Back up your private profile securely; updates preserve it and will refuse to silently generate a replacement key for an existing profile.
Copy only public-key.pem to this path on a public HTTPS domain you control:
https://your-app.example.com/.well-known/appspecific/com.tesla.3p.public-key.pem
The URL must serve the PEM file directly, without authentication. A static hosting service is sufficient; the site does not forward requests to your Mac. If using a GitHub Pages user site, use the domain root and add .nojekyll so .well-known is served. Do not upload command-key.pem, credentials or the private profile.
See Tesla's virtual key documentation.
Create your application in the Tesla Developer portal. Use your own app name and domain. Configure:
| Setting | Value |
|---|---|
| Allowed origin | Your public HTTPS origin, such as https://your-app.example.com |
| Redirect URI | http://localhost:8765/callback |
| Grant types | Authorization Code and Client Credentials / Machine-to-Machine |
| Vehicle access | Vehicle Information, Vehicle Commands, Vehicle Charging Management |
The plugin requests openid offline_access vehicle_device_data vehicle_cmds vehicle_charging_cmds. Command scopes cover the explicit wake, charging, climate, Sentry, lock and trunk controls. Location is optional: enable Vehicle Location for the developer app, then choose Location → Enable Location… and approve that scope on Tesla’s consent page. This adds vehicle_location. No energy-product scopes are requested. Tesla's charging scope may cover more information than this plugin uses; inspect Tesla's consent page before granting access.
Complete any required app review and billing setup in the portal. Keep your Client Secret private. See Tesla's authentication guide and billing documentation.
Open Settings… in the xBar plugin. Enter your Client ID, Client Secret, public-key domain and region (eu, na or cn). The secret prompt is hidden. The optional local browser form is available through tesla-action.sh provision; both interfaces use the same settings schema and validation. examples/config.example.json documents the non-secret fields; the installer does not copy example values over an existing profile.
Register your domain in the selected Fleet API region from Terminal:
TESLA_XBAR_ACTION="$HOME/Library/Application Support/Tesla xBar/tesla-action.sh"
"$TESLA_XBAR_ACTION" registerThen choose Connect Tesla account… in xBar, sign in on Tesla's website and grant access to your vehicle. The browser returns to a temporary localhost callback on your Mac. It closes after authorization; ongoing refresh uses the saved tokens in Keychain. After sign-in the plugin checks the account’s region once using Tesla’s region endpoint. Only the official regional hosts are accepted. If verification is unavailable, your configured region remains in use. If Tesla identifies a different region, domain registration may also be required there; it is never submitted automatically.
If you have multiple vehicles, choose Select vehicle in the menu. Menu bar display switches between Range and Percentage.
Reading battery data does not require adding a virtual key to the vehicle. Many vehicles require the app's key for signed charging and charge-port commands.
Camp Mode, Pet Mode, running climate, unlocked-vehicle, Sentry and front/rear trunk
indicators use the same vehicle-data permission as battery readings. They need no
additional consent or virtual-key pairing. After updating, they appear when the
next successful online refresh supplies the relevant fields. The fan means
is_climate_on is true; an open padlock means locked is explicitly false.
Front/rear trunk icons use their own closure readings and may appear regardless
of the lock state. Missing, offline/asleep or old information does not activate
an icon. Controls are grouped under Clima, Sentry and Locks and trunks;
using these actions requires the command permissions described below.
The Clima submenu provides normal climate, Keep Climate On, Camp Mode, Pet Mode,
temperature selection, modes off and full climate/modes off. These actions use
vehicle_cmds; reconnect with Vehicle Commands enabled if Tesla denies access.
Signed commands also require the paired app key. Normal climate and full shutdown
first exit the active keeper mode. Temperature is in °C, uses limits returned by
the vehicle, and sets both front zones in 0.5 °C steps. If limits are missing,
refresh while the vehicle is online. Setting a temperature alone does not turn
climate on. A clicked command can wake the vehicle; routine refresh cannot.
Inside temperature and Outside temperature show Tesla's measured readings, separately from Target temperature. Unavailable readings are labeled as such; saved readings from an offline/asleep vehicle or a failed refresh use Last known.
When upgrading from a version without Clima controls, use the full installer
(python3 -m scripts.install) to rebuild the command helper with its mode adapter.
Choose Charging and port → Add key to vehicle…, open the link on a phone with the Tesla app and approve the key for the correct vehicle. The link uses your configured domain. Then choose Check command setup.
Test physical commands yourself when appropriate. Start charging, Stop charging and port actions can wake the vehicle. Ordinary Refresh now does not send wake commands. Opening a port is not a physical cable-removal mechanism.
The Locks and trunks submenu groups Lock vehicle, Unlock vehicle, Open front trunk and Open / close rear trunk. It uses the same Vehicle Commands permission and paired key as Clima and Sentry, with no extra setup. These explicit actions may wake the car. Rear-trunk opening/closing is one toggle according to the vehicle's position; closing requires support from the vehicle. The front trunk has no remote close action. Lock and trunk readings come from the normal vehicle-data request and remain labeled Last known while unavailable. After a click, the plugin distinguishes command acceptance from confirmation by a new reading. A trunk marked open may be ajar rather than fully raised.
git pull --ff-only
python3 -m scripts.installPython modules are installed as one atomic tesla-runtime.zip bundle beside the entrypoint; the source has dependency-separated layers under src/tesla_bar/. See Architecture.
For an update that only changes Python code, icons or the wrapper, you can reuse installed helpers:
python3 -m scripts.install --runtime-onlyBoth paths preserve configuration, keys, tokens, saved readings and the active wrapper's interval. The runtime-only path must not be used when an update requires new helper binaries. Never copy another person's profile or signing key.
- Offline / asleep: the last known reading remains visible. A small trailing dot marks offline/asleep (for example,
360 km ·). A last known connected cable keeps the text green; unplugged readings keep their usual range color. The original timestamp and Last known cable state remain in the menu. Use the explicit wake action only when you want to wake the car. - No data yet: confirm registration, region, consent and the vehicle's connectivity.
- Missing key: pair your own app key in the Tesla mobile app. Do not create a new key to fix an existing profile unless you also update the hosted public key and vehicle pairing.
- Expired login: reconnect the account. Tokens normally refresh automatically.
- Busy notice: another operation is running; the rejected action is not queued. Try again after it finishes.
- Billing / rate-limit error: follow Tesla's portal instructions. The plugin honors the server's retry delay.
- Port 8765 unavailable: close an earlier sign-in attempt or free the local port before reconnecting.
Do not paste tokens, callback URLs, VINs or private profile files into GitHub issues. Use fictional examples and redact screenshots.
Sentry uses vehicle_cmds and the existing paired virtual key. Clicking on/off may wake an unavailable vehicle. A normal refresh only reads Sentry state.
Location is disabled by default. To enable it:
- In the Tesla Developer portal, open your app’s scope management and enable Vehicle Location.
- In xBar, choose Location → Enable Location….
- On Tesla’s consent page, allow Vehicle Location. Existing battery and command permissions remain requested.
- Refresh the plugin while the vehicle is online. The Location submenu shows the address and Open in Apple Maps. It does not automatically wake the car.
- Optionally choose Location → Enable map preview. This shares map bounds centered on the vehicle with MapMap, a separate provider. No map API key, account, Documents permission or Mac GPS access is required. The map appears above the address with a blue dot and no POI pins.
Enabling Location shares the vehicle’s latitude/longitude with Apple’s geocoding service to obtain an address. It does not read your Mac’s location or send Apple your Tesla credentials or VIN. Address lookup runs only when needed and is bounded to eight seconds; no daemon is installed. Existing coordinates reuse their matching address. Changed coordinates never inherit the old address.
Offline/asleep vehicles retain the last known position and its original time. If Apple has no address or lookup fails, the map still opens the coordinate. An address may lack a house number or describe the nearest street; it cannot identify an exact parking space. Tesla may show its location-sharing indicator in the vehicle.
Disable Location clears the saved location/address and rendered map link and stops requesting GPS data. It does not revoke Tesla’s server-side permission; use Tesla account permissions to revoke that separately.
The map preview uses location_map_enabled (default false) and the tesla-map-image helper. Run the full installer when upgrading to this feature. A changed saved position causes at most one MapMap request during the normal plugin refresh; the same position reuses its cached image. No extra Tesla request or wake is sent. If map retrieval fails after movement, the previous map is hidden rather than presented as the new position; the Apple Maps link remains. The map uses the location timestamp already shown in the submenu, including while the vehicle sleeps.
Hide map preview deletes location-map.png and stops map requests, while retaining the address and Apple Maps link. Disable Location also deletes the map. Map images and menu snapshots are private location data; never attach them to a public issue.