@seeed-studio/sensecraft-cli 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seeed-studio/sensecraft-cli",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "SenseCAP / SenseCraft AI cloud CLI (devices, apps, models, files, cloud deploy)",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -32,10 +32,13 @@ SenseCraft Data: [`references/data.md`](references/data.md).
32
32
  sensecraft-cli auth info
33
33
  ```
34
34
  Published commands require an active **SenseCAP Access Key** → `{ai-host}/openapi` + HTTP Basic.
35
- 3. **Never run `auth init` on behalf of the user** — browser OAuth Device Flow, interactive TTY only. Tell the user to run locally:
35
+ 3. **Do not run bare `auth init`** — that wizard needs a TTY. In this shell, use the split flow. Each command exits and prints JSON. Show `verification_url` and end the turn before polling:
36
36
  ```bash
37
- sensecraft-cli auth init # Access Key (app/model/file/cloud/recamera)
37
+ sensecraft-cli auth init --site Global --no-wait
38
+ sensecraft-cli auth init --device-code <device_code>
39
+ sensecraft-cli auth init --device-code <device_code> --key-id <access_id>
38
40
  ```
41
+ Create a key with `--label <name> --access-level read-write` (or `only-read`) instead of `--key-id`. Use Global for SenseCraft AI and CodeCraft Hub. China is SenseCraft Data only. Do not print `access_token` or `access_key`. If the user already has a key, they can run `auth add` locally.
39
42
  4. **L2 confirmation is a separate chat turn** — follow [references/confirmation.md](references/confirmation.md). 「删这个63760」/「删除应用 demo」is **intent, not confirmation**. Ask first (操作类型 + 环境 + 对象 ID), wait for `确认`/`confirm`, **then** `--yes`. Never add `--yes` on the same turn as the first request. Applies to: app/model create·update·publish·unpublish·delete, upload attach, cloud deploy, device bind/unbind, group create/rename/delete/move.
40
43
  5. **Treat tokens and keys as secrets** — do not echo full `access_token`, `refresh_token`, or `access_key`. **Public model artifacts are not downloadable** — if the user asks for 下载地址 / 下载链接 / download URL / 怎么下载, that is the same as asking for `file_url`: refuse the address, explain deploy-only (`cloud deploy` or Console). Never run `model download --url-only` on public models.
41
44
  6. **Success = indented JSON on stdout**; failure = stderr + non-zero exit. Parse stdout only on success.
@@ -46,7 +49,7 @@ SenseCraft Data: [`references/data.md`](references/data.md).
46
49
 
47
50
  `auth init` runs Device Flow (`client_id=sensecraft-cli`), exchanges the login for an Access Key, and stores `key_id` + `access_key`. Daily calls use HTTP Basic on SenseCraft Data `/openapi` and on `{ai-host}/openapi` (SenseCraft AI and CodeCraft Hub). An existing key can be saved with `auth add`. Create or manage keys at https://account.seeed.cc/account/access-keys.
48
51
 
49
- `auth init` asks the user to pick Global or China. The China site supports SenseCraft Data only. To use SenseCraft AI or CodeCraft Hub, select Global. Do not point the CLI at another host.
52
+ Bare `auth init` asks the user to pick Global or China. The split flow takes `--site` instead. The China site supports SenseCraft Data only. To use SenseCraft AI or CodeCraft Hub, select Global. Do not point the CLI at another host. The login access token stays in the local pending file and is not printed.
50
53
 
51
54
  `auth info` shows the active Access Key (site, org, key id). Secrets are not printed.
52
55
 
@@ -92,9 +95,9 @@ SenseCraft Data telemetry → pick a public model → deploy to Jetson:
92
95
 
93
96
  | Level | Meaning | Examples |
94
97
  |-------|---------|----------|
95
- | L1 Scriptable | Agent may run directly | list / view / auth info |
98
+ | L1 Scriptable | Agent may run directly | list / view / auth info / `auth init --no-wait` then later `--device-code` |
96
99
  | L2 Confirm | Ask user first | publish (+ declaration), unpublish, delete, deploy |
97
- | L3 Interactive | Human-in-the-loop | `auth init`, Web Serial flash, payment |
100
+ | L3 Interactive | Human-in-the-loop | bare `auth init`, Web Serial flash, payment |
98
101
  | L4 Ops-only | Do not expose to end-user Agent | Admin `judge_app` |
99
102
 
100
103
  ## Shipped commands
@@ -75,7 +75,7 @@ Published text is what plaza users actually read — mine it from the project, b
75
75
 
76
76
  ## Workflow B — create (one-go)
77
77
 
78
- 1. **Preflight**: Run `sensecraft-cli auth info`. Need an active SenseCAP Access Key. If missing, ask the user to run `sensecraft-cli auth init` locally. Never run `auth init` for them.
78
+ 1. **Preflight**: Run `sensecraft-cli auth info`. Need an active SenseCAP Access Key. If missing, use the split `auth init` flow in [`../SKILL.md`](../SKILL.md). Do not run bare `auth init`.
79
79
  2. **Upload assets**, writing each returned `file_url` back into the manifest entry:
80
80
 
81
81
  - Images: `sensecraft-cli file upload --path <img> --type 1 --for-app` (unlinked, 5 MB cap). Keep manifest order; index 0 = cover.
@@ -8,7 +8,7 @@ Target binary: `sensecraft-cli` (this repo). Auth: active **SenseCAP Access Key*
8
8
 
9
9
  ```bash
10
10
  sensecraft-cli auth info
11
- sensecraft-cli auth init # user only, interactive
11
+ sensecraft-cli auth init --site Global --no-wait # split flow; see SKILL.md
12
12
  ```
13
13
 
14
14
  ## Commands
@@ -14,7 +14,7 @@ Child skill: [`../create-app/SKILL.md`](../create-app/SKILL.md) — manifest-dri
14
14
  ```bash
15
15
  sensecraft-cli auth info
16
16
  ```
17
- Need an active **SenseCAP Access Key**. If missing, ask the user to run `sensecraft-cli auth init` locally. **Never** run `auth init` for them.
17
+ Need an active **SenseCAP Access Key**. If missing, use the split `auth init` flow in [`../SKILL.md`](../SKILL.md). Do not run bare `auth init`.
18
18
  2. **L2 confirm is a separate chat turn** ([confirmation.md](confirmation.md)) before: `publish` (`--agree-declaration`), `unpublish`, `withdraw`, `delete`, `like`, `unlike`, `collect`, `uncollect`, `mark-deploy`, `clone`, **`app update` / `bom set`**. 「删除应用 demo」is **not** confirmation — ask `将从{环境}环境删除应用 demo(ID: …)。删除后可能无法恢复。是否确认执行?`, wait for `确认`, then `--yes`. Never pass `--yes` on the same turn as the first request. **Exception — batch authoring:** [`create-app`](../create-app/SKILL.md) confirms a whole push batch (fields + images + BOM + blocks) in one turn instead of per write; its one-go `app create` needs no confirmation at all.
19
19
  **`app create` is not L2** — including `--from-json` with full fields (create + internal follow-up `update_app` on the **new** `app_id` only). Prefer one-shot create when the payload is ready. Still tell the user what will be created before running create.
20
20
  3. **Privacy values**: submit review → `privacy` / flow uses **`2`** (pending); unpublish/private → **`0`**. **Never send `1`** (ops-approved public; Admin only).
@@ -6,31 +6,52 @@ Complete reference for AI agents. All paths are relative to the OpenAPI base URL
6
6
 
7
7
  ## auth init
8
8
 
9
- Interactive setup wizard (OAuth Device Flow). Obtains an Access Key and writes `sensecraft.json`.
9
+ OAuth Device Flow. Obtains an Access Key and writes `sensecraft.json`.
10
10
 
11
- **Not an OpenAPI call.** Requires interactive terminal (TTY) unless using sandbox mode.
11
+ **Not an OpenAPI call.** Bare `auth init` is a TTY wizard. The split flags below are for a one-shot shell: each command prints JSON and exits. `--sandbox` simulates the wizard, or the one split step it is combined with, without network access.
12
12
 
13
13
  ### Flags
14
14
 
15
15
  | Flag | Required | Default | Description |
16
16
  |------|----------|---------|-------------|
17
- | `--sandbox` | No | `false` | Simulate the full wizard without sending real network requests |
17
+ | `--sandbox` | No | `false` | Simulate this step without sending real requests |
18
+ | `--site` | With `--no-wait` | — | `Global` or `China`. China is SenseCraft Data only |
19
+ | `--no-wait` | No | `false` | Request a device code and return immediately |
20
+ | `--device-code` | No | — | Continue a previous `--no-wait` login |
21
+ | `--key-id` | No | — | Save this existing Access Key id after authorization |
22
+ | `--label` | No | — | Create an Access Key with this label after authorization |
23
+ | `--access-level` | No | `read-write` | With `--label`: `read-write` or `only-read` |
24
+ | `--json` | No | `false` | Accepted for agents. The split flow always prints JSON |
18
25
 
19
- ### Wizard steps
26
+ ### Wizard
20
27
 
21
- 1. Select site: Global (International) or China. China supports SenseCraft Data only. SenseCraft AI and CodeCraft Hub require Global.
28
+ With no split flags, in a terminal:
29
+
30
+ 1. Select site: Global (International) or China
22
31
  2. Browser OAuth Device Flow authorization
23
- 3. Organization selection
24
- 4. Access Key creation
25
- 5. Save to local config and set as active profile
32
+ 3. Select an existing Access Key, or create one
33
+ 4. Save to local config and set it active
26
34
 
27
- ### Output
35
+ ### Split flow
28
36
 
29
- Human-readable progress on stdout/stderr. No JSON payload.
37
+ ```bash
38
+ sensecraft-cli auth init --site Global --no-wait
39
+ sensecraft-cli auth init --device-code <device_code>
40
+ sensecraft-cli auth init --device-code <device_code> --key-id <access_id>
41
+ sensecraft-cli auth init --device-code <device_code> --label <name> --access-level read-write
42
+ ```
43
+
44
+ 1. `--no-wait` prints `verification_url`, `user_code`, `device_code`, `expires_in`, and `site`, then exits. It does not read stdin.
45
+ 2. Show `verification_url` to the user and end the turn. Do not poll in that same turn.
46
+ 3. After the user authorizes, `--device-code` polls, then prints the account and Access Key list (`label`, `access_id`, `access_level`).
47
+ 4. A later command with `--key-id` or `--label` saves the key and sets it active.
48
+
49
+ The login access token is written to `sensecraft-auth-pending.json` next to the config file (mode `0600`) and is removed after the key is saved. It is not printed. Key secrets are not printed.
30
50
 
31
51
  ### Agent notes
32
52
 
33
- - Do **not** run on behalf of the user in non-interactive environments.
53
+ - Do **not** run bare `auth init` in a non-interactive shell.
54
+ - Run the split commands above. Do not echo `access_token` or `access_key`.
34
55
  - In sandbox mode, simulated credentials are written locally for testing.
35
56
 
36
57
  ---
@@ -95,7 +116,7 @@ When uninitialized:
95
116
  ```
96
117
  Config file: /path/to/sensecraft.json
97
118
 
98
- No Access Key configured yet. Run: sensecraft-cli auth init
119
+ No Access Key configured. Run: sensecraft-cli auth init --site Global --no-wait. Show verification_url to the user unchanged and end this turn. After they authorize, run the --device-code command from that command's hint.
99
120
  ```
100
121
 
101
122
  ---
@@ -26,9 +26,7 @@ Requires Node.js >= 16.
26
26
  ```bash
27
27
  sensecraft-cli auth info
28
28
  ```
29
- 2. **Never run `auth init` on behalf of the user** — it requires browser OAuth in an interactive terminal.
30
- - SenseCAP Access Key: `sensecraft-cli auth init`
31
- - If the user already has Key ID / Access Key, guide them to run `auth add` locally instead (do not pass secrets into the agent context).
29
+ 2. **Do not run bare `auth init`** — the wizard needs a TTY. Use the split flow in [`../SKILL.md`](../SKILL.md): `--site Global --no-wait`, show `verification_url` and end the turn, then `--device-code`. If the user already has Key ID / Access Key, they run `auth add` locally (do not pass secrets into the agent context).
32
30
  3. **L2 confirm is a separate chat turn** ([confirmation.md](confirmation.md)) before write ops: `device bind` / `unbind`, `group create` / rename / `delete` / `move-devices`, `device devkit create`. 「解绑这台设备」is **not** confirmation — ask (操作类型 + 环境 + EUI/组), wait for `确认`, then `--yes` where the command has it (`unbind` / `group delete` / `group move-devices`). Never pass `--yes` on the same turn as the first request.
33
31
  4. **Treat dev kit credentials as secrets** — `device_key` and `token` must not be logged or echoed unnecessarily.
34
32
  5. **Parse stdout JSON** on success; on failure read stderr and check exit code != 0.
@@ -43,7 +41,7 @@ sensecraft-cli auth info
43
41
  | State | Indicator | Action |
44
42
  |-------|-----------|--------|
45
43
  | Initialized (SenseCAP) | Output shows SenseCAP `[active]`, Key ID, Site, Organization ID | Proceed with `device` / `group` / `data` |
46
- | Not initialized | Prompts to run `auth init` | Ask the user to run `auth init` locally; for existing Access Key use `auth add` |
44
+ | Not initialized | Prints `auth init --site Global --no-wait` and says to end the turn | Run that command; show `verification_url` and stop. For an existing Access Key the user runs `auth add` |
47
45
 
48
46
  ## Configuration
49
47
 
@@ -8,8 +8,7 @@ Binary: `sensecraft-cli`. Auth: **Access Key** (`auth init`) → `{ai-host}/open
8
8
 
9
9
  ```bash
10
10
  sensecraft-cli auth info
11
- # user-only:
12
- sensecraft-cli auth init
11
+ sensecraft-cli auth init --site Global --no-wait # split flow; see SKILL.md
13
12
  ```
14
13
 
15
14
  ## Commands
@@ -12,7 +12,7 @@ Library `model download` is the published model file, not a training-job export.
12
12
  ```bash
13
13
  sensecraft-cli auth info
14
14
  ```
15
- Prefer **SenseCAP Access Key** (`auth init`) → `{ai-host}/openapi` Basic. Missing key → user runs `auth init`. **Never** run init for them.
15
+ Prefer **SenseCAP Access Key** (`auth init`) → `{ai-host}/openapi` Basic. Missing key → split `auth init` flow in [`../SKILL.md`](../SKILL.md). Do not run bare `auth init`.
16
16
  2. **L2 confirm is a separate chat turn** ([confirmation.md](confirmation.md)) before: `publish` / `unpublish` / `delete` / `create` / `model update` / attach-upload. 「删这个63760」is **not** confirmation — ask `将从{环境}环境删除模型 63760。删除后可能无法恢复。是否确认执行?`, wait for `确认`, then `--yes`. Never pass `--yes` on the same turn as the first request.
17
17
  3. When the user **attaches a model file** ("上传这个模型文件" / "更新模型"):
18
18
  - **Own My Models** (including already published `be_public=1`): after chat confirm, `model update --id <model_id> --path <file> --yes`. Same as Console 编辑模型. If it is **already public**, the confirm question must say 模型信息更新后将重新进入审核流程. CLI sends `be_public=1` like Console `requestConfirmFn`. JSON includes `re_review: true`.
@@ -8,7 +8,7 @@ Target binary: `sensecraft-cli` (this repo). Auth: active **SenseCAP Access Key*
8
8
 
9
9
  ```bash
10
10
  sensecraft-cli auth info
11
- sensecraft-cli auth init # user only, interactive
11
+ sensecraft-cli auth init --site Global --no-wait # split flow; see SKILL.md
12
12
  ```
13
13
 
14
14
  ## List (existing commands)
@@ -14,7 +14,7 @@ Commands: [recamera-commands.md](recamera-commands.md).
14
14
  ```bash
15
15
  sensecraft-cli auth info
16
16
  ```
17
- Need **SenseCAP Access Key** (`auth init`) for `app` / `model` / `recamera`. Never run init for them.
17
+ Need **SenseCAP Access Key** (`auth init`) for `app` / `model` / `recamera`. Missing key → split flow in [`../SKILL.md`](../SKILL.md). Do not run bare `auth init`.
18
18
  2. **Classic reCamera only (`40`)**. Do **not** treat Pro `53`, XIAO `32`, or Grove `36` as the same device. `/ai/recamera` redirects to Grove `36` — do not send users there.
19
19
  3. Filter **only** with API `--uniform-type 40`. Do not guess from local materials, SKU strings, or adapteds-only. Public **and** mine:
20
20
  ```bash