Skip to content

CLI 命令行工具 (@habitaxx/cli) ​

HabitaXX 官方提供了命令行工具 @habitaxx/cli,支持通过安全设备授权流程(RFC 8628 Device Authorization Flow)连接开放平台。开发者无需将 API Key 直接暴露在配置中,即可通过终端或自动化脚本直接调用平台各项 AI 能力。


1. 安装与运行 ​

全局安装 ​

bash
npm install -g @habitaxx/cli

免安装即用 (npx) ​

bash
npx @habitaxx/cli --help

在本地仓库开发调试时,也可直接运行源码:

bash
node sdk/cli/bin/habitaxx.js --help

环境要求:Node.js 18.17 或更高版本。


2. 设备授权登录 ​

运行以下命令发起设备登录流程:

bash
habitaxx auth init

执行流程:

  1. CLI 向控制面申请一次性的设备授权码(有效时长 10 分钟);
  2. 终端打印并在默认浏览器中自动打开授权页面(例如 https://platform.habitaxx.com/auth?code=ABCD-EFGH);
  3. 开发者在浏览器中确认待绑定的项目、权限范围及能力标识;
  4. 批准后,CLI 自动获取该域专属的访问凭证,并安全存储至本地 ~/.habitaxx/auth.json。

限制申请权限与能力 ​

bash
# 仅申请指定能力标识与最小调用权限
habitaxx auth init \
  --scope capabilities:read,tasks:write \
  --ability imu_behavior_recognition

3. 授权状态管理 ​

bash
# 查看本地当前域的授权状态(脱敏显示)
habitaxx auth status

# 在线校验本地保存的凭据是否在网关端有效
habitaxx auth status --check

# 以脱敏的 JSON 格式输出状态(供脚本或 CI/CD 解析)
habitaxx auth status --json

# 登出并清理当前域在本地的凭据
habitaxx auth logout

# 清理本机所有域的本地凭据
habitaxx auth logout --all

安全提示:auth logout 仅清理本地存储的凭据文件,若需永久作废该 API Key,请登录开放平台控制台进行吊销操作。


4. 能力调用命令 ​

CLI 内部自动在内存中完成 API Key 到短效 Access Token 的置换,并自动携带 X-Client-Type: open_platform 请求头。

4.1 鸟类多模态识别 (habitaxx bird detect) ​

bash
habitaxx bird detect --file /path/to/bird.jpg

支持参数:

  • --file <path>:必填,待检测图片的本地绝对或相对路径。
  • --domain <origin>:可选,指定特定的网关域名。
  • --output <file>:可选,将识别结果保存至指定 JSON 文件。

4.2 智能项圈 IMU 行为预测 (habitaxx imu predict) ​

bash
# 从 JSON 文件中读取时序样本预测
habitaxx imu predict --data @samples.json --top-k 5

# 指定目标设备标识
habitaxx imu predict --data @samples.json --device 001

支持参数:

  • --data <json|@file>:必填,包含 6 轴时序数据数组的 JSON 字符串或 @文件路径。
  • --device <device_id>:可选,按特定设备逻辑单元路由。
  • --top-k <num>:可选,返回置信度最高的前 K 种行为,默认 5。

4.3 通用 API 请求 (habitaxx request) ​

支持通过安全网关调用开放平台的任意能力接口:

bash
# 查看开放平台可用能力清单
habitaxx request GET /capabilities

# 发起智能宠物问诊会话
habitaxx request POST /ms-ai-fast/session-records/sessions \
  --data '{"module_type":1,"pet_profile_id":78,"content":"狗狗食欲不振并且嗜睡"}'

# 提交带文件的表单请求
habitaxx request POST /bird/detect \
  --form file=@/path/to/bird.jpg

支持参数:

  • --data '<json>' 或 --data @file.json:设置 JSON 请求体。
  • --form 'key=value' 或 --form 'file=@/path':设置 Multipart 表单字段。
  • --header 'Key: value':追加自定义 HTTP 请求头(不可覆盖认证相关的敏感请求头)。
  • --output <file>:将响应内容直接持久化到指定本地文件。

5. 安全设计规范 ​

  1. 凭证隔离:本地凭据保存于 ~/.habitaxx/auth.json,目录权限为 0700,文件权限为 0600。
  2. 短效置换:长效 API Key 仅用于向网关换取 24 小时有效的短效 Access Token,Token 仅留存于进程内存中,不落盘。
  3. 敏感信息过滤:CLI 输出自动脱敏,禁止在 URL、命令日志或标准输出中输出原始 API Key 或完整 JWT。
最近更新

栖界开放平台 · API Documentation