tesla-cli-cn

Tesla Fleet API 命令行工具 — 为 Agent 调用而生。

• 默认 JSON 输出,stderr 仅日志,退出码语义化
• 标准 OAuth 2.0 + PKCE,虚拟钥匙 EC P-256 签名
• 支持北美 / 欧洲 / 中国大陆三个区域(CN 端点已实测打通)
• 单二进制分发,冷启动 < 20ms

tesla
├── auth          login / logout / status / token / refresh / partner
├── key           generate / publish / pubkey / pair-url
├── config        init / set / get / path / show
├── vehicle       list / info / data / wake / lock / unlock / honk / flash
├── charge        start / stop / limit
├── energy        list / info / live
├── docs          离线长文档 (auth-flow / virtual-key / cn-notes / agent-recipes / errors)
├── examples      命令示例
├── completion    bash / zsh / fish / powershell
└── man           生成 man pages

完整命令树见 tesla --help。每条命令都有 --help,自带 scopes、退出码、3+ 示例。

安装

通过 npm(推荐 — 单条命令)

npm install -g tesla-cli-cn
tesla --help

postinstall 自动从 GitHub Releases 下你机器对应平台的二进制。 国内用户网络差时设镜像(任选其一):

TESLA_CLI_MIRROR=https://ghfast.top  npm install -g tesla-cli-cn
TESLA_CLI_MIRROR=https://gh-proxy.com npm install -g tesla-cli-cn

下载失败会自动重试 3 次(2s / 4s / 8s 退避)。

从源码编译

git clone [email protected]:MiniBotFactory/tesla-cli.git
cd tesla-cli
make build                       # 产物 bin/tesla
make install                     # 安装到 ~/.local/bin/tesla

依赖:Go 1.21+,标准库 + cobra + viper + yaml.v3,无 cgo。

快速上手(5 步,从 0 到调通真车)

前置条件:已在 developer.tesla.com(全球)或 developer.tesla.cn(中国)创建 App,拿到 client_id / client_secret。

1. 生成虚拟钥匙

tesla key generate
# → ~/.config/tesla/keys/{private,public}-key.pem (mode 0600 / 0644)

2. 把公钥部署到你的域名

tesla key pubkey --quiet > public-key.pem
# 部署到:https://<your-domain>/.well-known/appspecific/com.tesla.3p.public-key.pem
# 必须 HTTPS 有效证书,自签名不被 Tesla 接受

3. 写配置

tesla config init \
  --client-id     '<YOUR-CLIENT-ID>' \
  --client-secret '<YOUR-CLIENT-SECRET>' \
  --domain        'your.example.com' \
  --region-init   'na' \
  --redirect-uri  'http://localhost:8765/callback' \
  --scopes        'openid offline_access vehicle_device_data vehicle_cmds vehicle_charging_cmds'

文件落到 ~/.config/tesla/config.toml,mode 0600。

4. 注册域名 + 车主授权

tesla auth partner token                                # client_credentials,拿 partner JWT
tesla auth partner register --domain your.example.com   # Tesla 入账你的公钥

tesla auth login                                        # 浏览器跳转 → token 落到 profiles/default.json
tesla auth status                                       # 看 token 元数据(脱敏)

5. 调用 Fleet API

tesla vehicle list
# {"ok":true,"data":{"count":1,"vehicles":[{"vin":"LRW0000000000000","display_name":"My Car","state":"online",...}]}}

tesla vehicle data --vin LRW0000000000000 --jq '.charge_state.battery_level'
tesla energy list

Agent 调用契约

| 项 | 规则 | |---|---| | stdout | 仅业务数据(JSON / 一行 ID / NDJSON 流) | | stderr | 日志、提示、警告 | | 输出格式 | --output json 默认,可选 yaml / table / text | | 退出码 | 语义化(见下) | | 失败信封 | {ok:false, code:"AUTH", message, hint, retryable} | | 输入优先级 | flag > TESLA_* env > ~/.config/tesla/config.toml > 内置默认 | | stdin | --json-input 从 stdin 读 JSON 当入参 |

退出码语义

| 码 | 含义 | 字符串 code | |----|---|---| | 0 | 成功 | OK | | 1 | 通用错误 | GENERIC | | 2 | 参数 / 用法错误 | USAGE | | 3 | 配置错误 | CONFIG | | 4 | 鉴权失败 / token 过期 | AUTH | | 5 | OAuth scope 不足 | SCOPE | | 6 | 虚拟钥匙未配对 / 签名失败 | VIRTUAL_KEY | | 7 | 车辆离线 / 唤醒失败 | VEHICLE_STATE | | 8 | Tesla 5xx | UPSTREAM_5XX | | 9 | 超时 | TIMEOUT | | 10 | 触发限流(已重试耗尽) | RATE_LIMIT |

三个 Agent 调用范式

# A. 链式 + jq 提取
tesla charge limit --percent 80 \
  && tesla charge start \
  && tesla vehicle data --jq '.charge_state.battery_level'

# B. stdin 注入 JSON 参数
echo '{"address":"1 Hacker Way, Menlo Park"}' \
  | tesla drive nav --json-input

# C. 流式 NDJSON(M5)
timeout 30 tesla telemetry stream --vin <VIN> \
  --fields location,speed --hz 1 --ndjson \
  | jq -c '{t:.timestamp, lat:.location.lat, lon:.location.lon}'

文件布局

~/.config/tesla/
├── config.toml                 客户端配置(0600)
├── profiles/
│   ├── default.json            车主 token(0600,原子写入)
│   └── default-partner.json    Partner Token
├── keys/
│   ├── private-key.pem         EC P-256(0600)
│   └── public-key.pem          (0644)
└── cache/                      M3+ 只读 API 缓存

XDG_CONFIG_HOME 受尊重;CI 用 --token-file <path> 跳过 keyring。

Tesla 中国大陆账号特别说明

跑 tesla docs cn-notes 看完整差异(简版):

• 注册在 developer.tesla.cn(单独账号,需 +86 手机号),与全球账号不互通
• 端点:auth.tesla.cn + fleet-api.prd.cn.vn.cloud.tesla.cn(本 CLI 已配好,--region cn 即可)
• auth.tesla.cn 由 Akamai WAF 守护,UA 含 (+https://...) 会 403 — 本 CLI 已规避
• redirect_uri 通常是你的生产域名(非 localhost),CLI 自动切 manual paste 模式

测试与覆盖率

go test -race -cover ./...

| 包 | 覆盖率 | |---|---| | internal/meta | 100% | | internal/tesla | 100% | | internal/config | 97% | | internal/errs | 96% | | internal/output | 87% | | internal/keys | 81% | | internal/client | 65% | | internal/auth | 70% |

业务核心 6 包平均 ~94%。auth 包剩余未覆盖行集中在 Login 的 net.Listen + http.Server loopback 路径与 RegisterPartner/Refresh 的真实远端调用 — 需要集成测试覆盖。manual-paste 路径与 parsePastedCallback 已通过 manual_test.go 全覆盖。

Fixture 来自真实 Tesla CN 响应(脱敏),回放在 internal/{auth,client}/testdata/。TestFixturesDoNotLeakSecrets 静态扫描守住 fixture 永不退化回真车。

项目结构

.
├── cmd/tesla/main.go                CLI 入口(11 行)
├── internal/
│   ├── meta/                        版本元数据(ldflags 注入)
│   ├── errs/                        退出码契约 + Error 类型
│   ├── output/                      Envelope + JSON/YAML/Table/Text
│   ├── config/                      viper 包装 + XDG 路径
│   ├── tesla/                       区域端点表 + HTTP client
│   ├── auth/                        OAuth + PKCE + Token + Partner
│   ├── keys/                        EC P-256 PEM + Tesla App 配对深链
│   ├── client/                      Fleet API REST 封装
│   └── cli/                         cobra 根 + 全部子命令
├── go.mod / go.sum
├── Makefile
└── .gitignore

go vet ./... 干净,gofmt 自动应用。

开发流程

make build         # 编译
make test          # go test ./...
make lint          # go vet + gofmt 校验
make completions   # 生成 bash/zsh/fish/powershell 补全
make manpages      # 生成 man pages

提交规范:type: short description(feat/fix/refactor/test/docs/chore/perf/ci)。

License

MIT — 详见 LICENSE。