[![License](https://img.shields.io/github/license/Stopa/tyta)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/tyta?logo=pypi&logoColor=white&label=PyPI)](https://pypi.org/project/tyta/)
[![Python](https://img.shields.io/pypi/pyversions/tyta?logo=python&logoColor=white&label=Python)](https://pypi.org/project/tyta/)
[![CI](https://img.shields.io/github/actions/workflow/status/Stopa/tyta/ci.yml?logo=github&label=CI)](https://github.com/Stopa/tyta/actions/workflows/ci.yml)

# tyta

A command-line interface for Toyota Connected Services (EU). Communicate with your Toyota vehicle
directly from the terminal or from automation scripts.

> **Note:** EU region only. Requires a Toyota Connected Services account.

> **Disclaimer:** This is an unofficial, community-built tool with no affiliation with Toyota.
> It is provided **as-is**, with no warranty of any kind. AI was used heavily in the making of this tool.
> Toyota may change or discontinue their API at any time without notice, which may break this tool.
> Use at your own risk. The author accepts no liability for any damage, data loss, unintended vehicle
> commands, or service disruption arising from use of this software.

## Install

```bash
pipx install tyta
```

Or for development:

```bash
pipx install --editable .
```

## Quick Start

```bash
# Authenticate
tyta auth login

# Check auth status
tyta auth status

# List your vehicles
tyta vehicles list

# Set a default vehicle (so you don't need --vin on every command)
tyta vehicles use JTDKB3FU803012345

# Show vehicle status
tyta status
```

## Global Options

These options are accepted by every command:

| Option | Env Var | Default | Description |
|---|---|---|---|
| `--json` | — | off | Output raw JSON envelope instead of human-readable text |
| `--auth-file PATH` | `TOYOTA_AUTH_FILE` | `~/.config/tyta/auth.json` | Path to auth token file |
| `--config-file PATH` | `TOYOTA_CONFIG_FILE` | `~/.config/tyta/config.json` | Path to config file |
| `--debug` | — | off | Enable debug logs to stderr; show tracebacks on error |

## Environment Variables

| Variable | Description |
|---|---|
| `TOYOTA_USERNAME` | Toyota account email. Used for non-interactive login and headless re-auth. |
| `TOYOTA_PASSWORD` | Toyota account password. Used for non-interactive login and headless re-auth. |
| `TOYOTA_AUTH_FILE` | Override path to the auth token file. |
| `TOYOTA_CONFIG_FILE` | Override path to the config file. |
| `TOYOTA_VIN` | Default VIN for per-vehicle commands. Overridden by `--vin` flag; overrides config default. |

### Headless / CI environments

If `TOYOTA_USERNAME` and `TOYOTA_PASSWORD` are both set, the CLI will re-authenticate
automatically whenever tokens expire — no manual intervention needed.

```bash
export TOYOTA_USERNAME="user@example.com"
export TOYOTA_PASSWORD="secret"
tyta status   # re-auths silently if tokens have expired
```

## Commands

### Auth

```bash
tyta auth login       # Authenticate and save tokens
tyta auth logout      # Delete saved tokens
tyta auth status      # Show authentication state and token expiry
```

`tyta auth login` supports non-interactive mode via `TOYOTA_USERNAME` and `TOYOTA_PASSWORD`
environment variables.

### Vehicles

```bash
tyta vehicles list                    # List all vehicles linked to the account
tyta vehicles use <VIN>               # Set the default VIN (validates against API)
tyta vehicles info [--vin VIN]        # Model, year, colour, fuel type
tyta vehicles capabilities [--vin VIN]
tyta vehicles features [--vin VIN]
tyta vehicles subscriptions [--vin VIN]
```

### Status

```bash
tyta status [--vin VIN]        # Combined: telemetry + location + lock + health
tyta telemetry [--vin VIN]     # Raw telemetry: fuel, odometer, battery
tyta location [--vin VIN]      # Raw GPS location: coordinates and timestamp
tyta health [--vin VIN]        # Raw vehicle health: warning lights and alerts
```

`tyta status` returns a combined envelope with all four data sources. Use the individual
commands for targeted queries.

### Electric

```bash
tyta electric status [--vin VIN]
tyta electric refresh [--vin VIN]     # Real-time refresh (warns about 12V drain)
tyta electric charge-now [--vin VIN]

tyta electric reserve-charge \
    --day MONDAY --start 07:00 [--end 08:00] [--charge-type startOnly|startEnd] \
    [--vin VIN]

tyta electric set-charging-time \
    --day MONDAY --start 07:00 [--end 08:00] [--charge-type startOnly|startEnd] \
    [--vin VIN]
```

`--day` accepts uppercase weekday names: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`,
`SATURDAY`, `SUNDAY`.

`--start` / `--end` accept 24-hour time as `HH:MM` (e.g. `07:30`).

`--charge-type` defaults to `startOnly`; use `startEnd` when `--end` is provided.

### Climate

```bash
tyta climate status [--vin VIN]
tyta climate settings [--vin VIN]
tyta climate set [--temperature FLOAT] [--unit C|F] [--on | --off] [--vin VIN]
tyta climate on [--vin VIN]
tyta climate off [--vin VIN]
```

`tyta climate set` performs a read-modify-write: it fetches current settings, applies your
changes, and POSTs them back. All flags are optional; omitting `--on`/`--off` leaves the on/off
state unchanged.

### Trips

```bash
tyta trips list [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--limit N] [--page N] [--routes] [--vin VIN]
```

`trips list` defaults to the last 30 days. `--limit` controls results per page (default 10, max 50);
`--page` selects the page (default 1). `--routes` includes per-trip route geometry.

### Remote

```bash
tyta remote [--vin VIN]               # Show remote/lock status (no subcommand)
tyta remote lock [--vin VIN]
tyta remote unlock [--vin VIN]
tyta remote horn [--vin VIN]
tyta remote find [--vin VIN]          # Flash lights + sound horn
tyta remote headlights on [--vin VIN]
tyta remote headlights off [--vin VIN]
tyta remote hazard on [--vin VIN]
tyta remote hazard off [--vin VIN]
```

`tyta remote` with no subcommand shows the current remote/lock status. Action commands
(`lock`, `unlock`, `horn`, etc.) are fire-and-forget: the API acknowledges immediately;
vehicle execution is asynchronous.

## Configuration

tyta reads a JSON config file (default: `~/.config/tyta/config.json`) for persistent settings. Use `tyta config` to manage them:

```bash
tyta config show                        # Print all config keys and their current values
tyta config set date_format iso         # iso | human (default: human)
tyta config set distance_unit mi        # km | mi (default: km)
tyta config set default_vin <VIN>       # Set default VIN (also set by `tyta vehicles use`)
```

| Key | Accepted values | Default | Effect |
|---|---|---|---|
| `date_format` | `human`, `iso` | `human` | `human` → "24 Mar 2026, 08:04 UTC"; `iso` → pass-through |
| `distance_unit` | `km`, `mi` | `km` | Unit for distance values in trip output |
| `default_vin` | any string | (none) | Default VIN used when `--vin` flag is not provided |

Use `--config-file PATH` (or `TOYOTA_CONFIG_FILE` env var) to point to a custom config file.

## VIN Resolution

For all per-vehicle commands, the VIN is resolved in this order:

1. `--vin` flag on the command
2. `TOYOTA_VIN` environment variable
3. `default_vin` from config file (set via `tyta vehicles use <vin>`)
4. Auto-select if the account has exactly one vehicle (emits a warning)

## Output Format

By default, commands print human-readable text to stdout. Pass `--json` to get a machine-readable
JSON envelope instead — useful for scripting, piping to `jq`, or feeding to an LLM.

```bash
tyta --json status
tyta --json telemetry --vin JTDKB3FU803012345
```

### Success

```json
{
  "ok": true,
  "warnings": [],
  "data": { ... }
}
```

### Success with warnings

```json
{
  "ok": true,
  "warnings": ["No default vehicle set, using only available vehicle: VIN XXXXXXX"],
  "data": { ... }
}
```

### Error

```json
{
  "ok": false,
  "error": {
    "code": "not_authenticated",
    "message": "Not authenticated. Run `tyta auth login`."
  }
}
```

### Error Codes

| Code | Meaning |
|---|---|
| `not_authenticated` | No token file found |
| `token_expired` | Tokens expired and refresh failed |
| `api_error` | Toyota API returned a non-2xx response |
| `vehicle_not_found` | Specified VIN not found in account |
| `no_vehicles` | Account has no linked vehicles |
| `invalid_config` | Config or token file is malformed |
| `invalid_input` | User-supplied input is invalid |
| `unknown_error` | Unexpected exception |

### Exit Codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Operational error (`ok: false`) |
| `2` | Usage error (bad arguments) |

## Debugging

Pass `--debug` to enable verbose logs on stderr and print tracebacks on error:

```bash
tyta --debug status
tyta --debug auth login
```

Logs go to **stderr**; JSON output always goes to **stdout**.

## Shell Completions

tyta supports tab completion for commands, subcommands, and flags in bash, zsh, and fish.

### Install completions

**bash:**

```bash
tyta --install-completion bash
```

**zsh:**

```bash
tyta --install-completion zsh
```

**fish:**

```bash
tyta --install-completion fish
```

After installing, restart your shell (or `source` the relevant config file) for completions to take effect.

### Show the completion script without installing

```bash
tyta --show-completion bash
tyta --show-completion zsh
tyta --show-completion fish
```

## MCP Server

![Screenshot of Claude Desktop application showing user asking Claude to find their car and Claude responding with a map widget displaying the last parked location](./screenshots/tyta-claude-desktop.png)

tyta includes an MCP (Model Context Protocol) server ([`tyta/mcp/`](tyta/mcp/)) that exposes
Toyota Connected Services operations as structured tools for AI assistants such as Claude Desktop.
This lets an AI assistant query vehicle data and send remote commands on your behalf.

### Option 1 — Single-click install (MCPB bundle)

The easiest way to get started. Download the latest `tyta.mcpb` bundle from the
[releases page](https://github.com/Stopa/tyta/releases/latest), open it in Claude Desktop,
and enter your Toyota credentials in the installation dialog. No CLI setup, no config file editing.

See [`mcpb/`](mcpb/) for the bundle source and packaging details.

**What it does:**
- Collects your Toyota email and password via Claude Desktop's installation UI and stores them
  securely — you never edit a JSON file.
- Installs `tyta` automatically on first launch — no Python or pip required.
- All 14 MCP tools are available immediately after installation.

**Requirements:** Claude Desktop with MCPB support.

---

### Option 2 — Manual setup

For AI clients that don't support MCPB, or if you prefer to manage the installation yourself.

**Step 1 — Install tyta:**

```bash
pipx install "tyta[mcp]"
```

**Step 2 — Configure your MCP client.**

Pass your Toyota credentials as environment variables so the server can authenticate
automatically on first use:

```json
{
  "mcpServers": {
    "tyta": {
      "command": "tyta-mcp",
      "env": {
        "TOYOTA_USERNAME": "user@example.com",
        "TOYOTA_PASSWORD": "secret"
      }
    }
  }
}
```

For Claude Desktop, add this to:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

If installed with `pipx`, you may need the full path to `tyta-mcp`
(e.g. `/Users/<you>/.local/bin/tyta-mcp`).

Alternatively, run `tyta auth login` once beforehand and omit the `env` block — the server will
use the cached token.

---

### Available tools

| Tool | Description |
|---|---|
| `auth_status` | Check authentication status and token expiry |
| `vehicles_list` | List all vehicles linked to the account |
| `telemetry` | Fuel level, odometer, 12V battery |
| `location` | GPS coordinates and last-seen timestamp |
| `remote_status` | Door lock status and caution indicator count |
| `health` | Warning lights and health alerts |
| `electric_status` | EV battery level, charging status, and range |
| `climate_status` | Climate on/off state, target temperature, defoggers |
| `trips_list` | Trip history with optional date range filter |
| `trips_show` | Full detail for a single trip by ID |
| `remote_lock` | Lock vehicle doors *(write operation)* |
| `remote_unlock` | Unlock vehicle doors *(write operation)* |
| `remote_horn` | Sound the vehicle horn *(write operation)* |
| `remote_find` | Flash lights and sound horn to locate the vehicle *(write operation)* |

### Safety: write operations require explicit confirmation

The four write-operation tools (`remote_lock`, `remote_unlock`, `remote_horn`, `remote_find`)
will **not execute** unless the AI passes `confirm: true` as a parameter. This prevents an AI
assistant from accidentally triggering physical vehicle commands. When asking Claude to lock your
car, it will confirm with you before sending the command.

---

## Acknowledgements

tyta is built on the shoulders of [pytoyoda](https://github.com/pytoyoda/pytoyoda) — the community Python library for Toyota Connected Services Europe. The API reverse-engineering, authentication flow, and request signing approach in this project are derived directly from pytoyoda's work. Many thanks to [@DurgNomis-drol](https://github.com/DurgNomis-drol) for starting the original project and to the pytoyoda contributors for maintaining it.

## License

MIT
