needle-cloud 3.2.0 → 3.2.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/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [3.2.1] - 2026-10-23
|
|
10
|
+
### Changed
|
|
11
|
+
- Shortened the README, highlighted core commands, and linked detailed CLI and optimization workflow documentation.
|
|
12
|
+
|
|
9
13
|
## [3.2.0] - 2026-10-23
|
|
10
14
|
### Added
|
|
11
15
|
- Browser SDK chat tool policies to select eligible providers, match application capabilities, and exclude specific tools when starting a chat.
|
package/README.md
CHANGED
|
@@ -1,334 +1,90 @@
|
|
|
1
1
|
# Needle Cloud CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Deploy websites, optimize 3D assets, and manage your [Needle Cloud](https://cloud.needle.tools) content from the terminal.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[Documentation](https://engine.needle.tools/docs/cloud/) ? [CLI reference](https://engine.needle.tools/docs/cloud/cli) ? [MCP setup](https://engine.needle.tools/docs/ai/needle-mcp-server)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Getting started
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
npx needle-cloud deploy ./dist --name my-project
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
Or install globally:
|
|
14
|
-
|
|
15
|
-
```bash
|
|
16
|
-
npm install -g needle-cloud
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
**Requirements:** Node.js 18 or later.
|
|
20
|
-
|
|
21
|
-
## Commands
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
npx needle-cloud help # List all commands
|
|
25
|
-
npx needle-cloud help <command> # Help for a specific command
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
### Output and automation
|
|
29
|
-
|
|
30
|
-
Cloud and account commands support `--output cli|json`. The default `cli` output
|
|
31
|
-
is readable in a terminal. JSON mode writes one JSON value to stdout; progress,
|
|
32
|
-
warnings and diagnostics go to stderr. Errors exit nonzero. Existing JSON result
|
|
33
|
-
shapes are preserved, including arrays from list commands.
|
|
34
|
-
|
|
35
|
-
Use `--non-interactive` in scripts to prohibit prompts and browser launches.
|
|
36
|
-
Authentication uses `--token <value>`, `NEEDLE_CLOUD_TOKEN`, or valid saved
|
|
37
|
-
credentials; missing credentials fail. Token-authenticated commands do not require
|
|
38
|
-
a prior browser login. Non-interactive deployments do not open the deployed site.
|
|
39
|
-
|
|
40
|
-
```bash
|
|
41
|
-
needle-cloud list --non-interactive --output json
|
|
42
|
-
needle-cloud upload ./model.glb --non-interactive --output json
|
|
43
|
-
needle-cloud download <identifier> ./assets --format glb --non-interactive --output json
|
|
44
|
-
needle-cloud deploy ./dist --non-interactive --output json
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
These examples use `NEEDLE_CLOUD_TOKEN` or saved credentials. Access tokens retain
|
|
48
|
-
their team scope. `login --non-interactive --output json` checks saved browser
|
|
49
|
-
authentication; it cannot establish a fresh login from an access token.
|
|
50
|
-
`me --output json` returns account identity fields and team memberships from the
|
|
51
|
-
saved login, without credentials.
|
|
52
|
-
|
|
53
|
-
Upload/optimize, label commands and `list-deployments` retain their older
|
|
54
|
-
`--format json` output option. If supplied together, `--output` and an output
|
|
55
|
-
`--format` must agree. Upload's `--format source-url` and `--format edit-url`
|
|
56
|
-
remain available. For `list` and `download`, `--format` selects an asset format;
|
|
57
|
-
use `--output json` to select JSON.
|
|
58
|
-
|
|
59
|
-
`delete` returns its Trash receipt as JSON; `download` returns `success` and saved
|
|
60
|
-
`paths`; `deploy` returns the successful SDK upload receipt; generation commands
|
|
61
|
-
return `success` and the job `identifier`. Login returns `authenticated`, logout
|
|
62
|
-
returns `success`, and `me` returns selected identity fields. An unauthenticated
|
|
63
|
-
account check reports `authenticated: false` and exits nonzero.
|
|
64
|
-
|
|
65
|
-
### Chat
|
|
66
|
-
|
|
67
|
-
`ask` starts an interactive conversation, optionally with an initial message.
|
|
68
|
-
Use `--once` for a single answer or `--non-interactive` for a single answer with
|
|
69
|
-
no authentication prompts or browser launches. Both require a message.
|
|
70
|
-
|
|
71
|
-
```bash
|
|
72
|
-
needle-cloud ask
|
|
73
|
-
needle-cloud ask "Explain progressive loading" --once
|
|
74
|
-
needle-cloud ask "Summarize my assets" --non-interactive --output json
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
`--output json` returns one complete chat response and exits. `--no-stream`
|
|
78
|
-
prints the full answer as text; by itself it keeps the interactive session.
|
|
79
|
-
|
|
80
|
-
### Guided content browser
|
|
81
|
-
|
|
82
|
-
In CLI v3, listing automatically opens the guided browser when both input and
|
|
83
|
-
output are terminals. Browse with numbered selection and inline guidance:
|
|
84
|
-
|
|
85
|
-
```bash
|
|
86
|
-
needle-cloud list-content --team "My Team"
|
|
87
|
-
# The shorter command works too
|
|
88
|
-
needle-cloud list --search wood --format glb
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
Type a number and Enter to inspect an item. Use `/wood` to search, `/` to clear
|
|
92
|
-
search, `n` / `p` for pages, `t` to switch Trash, `r` to refresh, and `?` for help.
|
|
93
|
-
Inside an item, `o` opens its viewer, `e` opens its editor, and `b` goes back.
|
|
94
|
-
The browser shows commands for downloading, updating or restoring an item;
|
|
95
|
-
browsing itself does not change content. Trash shows listing metadata; restore
|
|
96
|
-
an item to inspect its versions. Type `q` to leave, or use Ctrl+C at a prompt.
|
|
97
|
-
|
|
98
|
-
Both input and output must be terminals for browsing. `--interactive true` forces
|
|
99
|
-
that mode and cannot be combined with `--output json` or `--non-interactive`.
|
|
100
|
-
Use `--interactive false` for a one-shot human-readable list in a terminal;
|
|
101
|
-
`--non-interactive` also prohibits authentication prompts and browser launches.
|
|
102
|
-
JSON and redirected streams automatically keep one-shot output. Colors respect
|
|
103
|
-
`NO_COLOR`; the browser keeps its navigation in terminal scrollback.
|
|
104
|
-
|
|
105
|
-
CLI v3 is distributed on the `version-3` channel. Existing integrations can stay on
|
|
106
|
-
`version-2` while migrating. Publish v3 on its own channel before shipping updated
|
|
107
|
-
integrations that request `needle-cloud@version-3`.
|
|
108
|
-
|
|
109
|
-
**Core commands:**
|
|
110
|
-
- `deploy` — Deploy a website to Needle Cloud
|
|
111
|
-
- `optimize` — Optimize 3D files (glTF, GLB, VRM, FBX, USD) with Draco, KTX2, and Progressive Loading
|
|
112
|
-
- `list` — List content stored in Needle Cloud
|
|
113
|
-
- `download` — Download a content item
|
|
114
|
-
- `info` / `versions` — Inspect metadata, URLs, processing state and version history
|
|
115
|
-
- `update` — Change content metadata or its thumbnail
|
|
116
|
-
- `delete` — Move a content item to Trash
|
|
117
|
-
- `restore` — Restore a content item from Trash
|
|
118
|
-
- `login` / `logout` — Authenticate with Needle Cloud
|
|
119
|
-
- `start` — Start the local server for licensing, editor integrations, and MCP tools
|
|
120
|
-
- `settings` — View CLI settings, including [local tool access for Needle Cloud AI](#local-tools-in-needle-cloud-ai)
|
|
121
|
-
|
|
122
|
-
## Stop the local license server
|
|
123
|
-
|
|
124
|
-
Close Unity or other integrations that may automatically start the server, then run:
|
|
125
|
-
|
|
126
|
-
```bash
|
|
127
|
-
npx needle-cloud stop
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
`quit` is an alias. The command authenticates with the local server token, requests
|
|
131
|
-
shutdown, and exits. It does not sign you out, remove settings, or kill unrelated
|
|
132
|
-
Node.js processes. The shared licensing/MCP server disconnects from Cloud and
|
|
133
|
-
closes its HTTP and WebSocket connections, allowing up to three seconds to drain.
|
|
134
|
-
|
|
135
|
-
If the server is not running, the command exits successfully. Older running
|
|
136
|
-
versions without the stop endpoint must be closed manually once; this command
|
|
137
|
-
cannot add shutdown support to an already-running old server. After that, start
|
|
138
|
-
the updated CLI or reopen your project. `needle-cloud status` shows the running
|
|
139
|
-
server's port and PID.
|
|
140
|
-
|
|
141
|
-
## Upload assets
|
|
142
|
-
|
|
143
|
-
```bash
|
|
144
|
-
# Upload the source; processing continues in the background
|
|
145
|
-
npx needle-cloud upload ./model.glb --team "My Team"
|
|
146
|
-
|
|
147
|
-
# Print only the URL for this exact uploaded source file
|
|
148
|
-
npx needle-cloud upload ./model.glb --format source-url
|
|
149
|
-
|
|
150
|
-
# Return source identity and links as JSON
|
|
151
|
-
npx needle-cloud upload ./models --format json
|
|
152
|
-
|
|
153
|
-
# Wait for optimization and download the result
|
|
154
|
-
npx needle-cloud upload ./model.glb --wait --outdir ./optimized
|
|
155
|
-
|
|
156
|
-
# Existing scripts continue to work
|
|
157
|
-
npx needle-cloud optimize ./model.glb --outdir ./optimized
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
Use `--no-optimize` to upload without requesting processing. `--wait` selects the
|
|
161
|
-
optimized variant with `--progressive true|false` and `--usecase product|world`.
|
|
162
|
-
The latter options and `--outdir` require waiting. `optimize` always waits.
|
|
163
|
-
|
|
164
|
-
Both commands support `--format cli` (default), `json`, `source-url`, and
|
|
165
|
-
`edit-url`. Progress and diagnostics, including `--verbose` output, go to stderr;
|
|
166
|
-
stdout contains only the selected result. Errors produce a nonzero exit code.
|
|
167
|
-
Authentication supports saved login, `--token`, or `NEEDLE_CLOUD_TOKEN`; `--team`
|
|
168
|
-
selects the team for saved-login uploads. Access tokens retain their team scope.
|
|
169
|
-
|
|
170
|
-
JSON contains `assetId`, `versionId`, `editUrl`, `sourceUrl`, `optimizedUrl`,
|
|
171
|
-
`processingStatus`, and `files`. Source URLs are pinned to the uploaded version;
|
|
172
|
-
optimization never changes `versionId` or the source links. After waiting,
|
|
173
|
-
`optimizedUrl` is pinned to the selected optimization and `optimization` describes
|
|
174
|
-
its version, progressive setting and use case.
|
|
175
|
-
|
|
176
|
-
Folders are collected recursively into one grouped upload, preserving current
|
|
177
|
-
behavior. The JSON `files` array contains a path and source URL for every uploaded
|
|
178
|
-
file. `sourceUrl` is null for a multi-file upload; `--format source-url` refuses
|
|
179
|
-
multiple files before uploading. `edit-url` returns the group's management URL.
|
|
180
|
-
|
|
181
|
-
Without waiting, `processingStatus` is `unknown`: background processing is not
|
|
182
|
-
queried. `--no-optimize` reports `not_requested` for this invocation; it does not
|
|
183
|
-
cancel processing from earlier uploads. Waiting reports `completed` for the
|
|
184
|
-
requested variant, which can differ from other background processing jobs.
|
|
185
|
-
|
|
186
|
-
Manage stored content by using the identifier shown by `list`:
|
|
9
|
+
Requires **Node.js 18+**. Run directly with `npx`, or install with `npm install -g needle-cloud`:
|
|
187
10
|
|
|
188
11
|
```bash
|
|
189
|
-
npx needle-cloud
|
|
190
|
-
npx needle-cloud
|
|
191
|
-
npx needle-cloud delete <identifier>
|
|
12
|
+
npx needle-cloud login
|
|
13
|
+
npx needle-cloud deploy ./dist --name my-project
|
|
192
14
|
```
|
|
193
15
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
```bash
|
|
197
|
-
npx needle-cloud info <identifier>
|
|
198
|
-
npx needle-cloud info <identifier> --output json
|
|
199
|
-
npx needle-cloud versions <identifier> --output json
|
|
200
|
-
npx needle-cloud update <identifier> --title "Wooden Crate" --tags "wood,crate"
|
|
201
|
-
npx needle-cloud update <identifier> --thumbnail ./preview.png
|
|
202
|
-
npx needle-cloud list --trash
|
|
203
|
-
npx needle-cloud restore <identifier>
|
|
204
|
-
```
|
|
16
|
+
## Core commands
|
|
205
17
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
18
|
+
| Task | Command |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| Deploy a website | `needle-cloud deploy ./dist --name my-project` |
|
|
21
|
+
| Upload and optimize a model | `needle-cloud upload ./model.glb --wait` |
|
|
22
|
+
| Optimize and download | `needle-cloud optimize ./model.glb --outdir ./optimized` |
|
|
23
|
+
| Browse or search assets | `needle-cloud list --search wood` |
|
|
24
|
+
| Inspect an asset / its versions | `needle-cloud info <id>` / `needle-cloud versions <id>` |
|
|
25
|
+
| Download an asset | `needle-cloud download <id> ./assets` |
|
|
26
|
+
| Update metadata | `needle-cloud update <id> --title "Wooden Crate"` |
|
|
27
|
+
| Manage version labels | `needle-cloud label list <id>` / `needle-cloud label set <id> main --from latest` |
|
|
28
|
+
| Move to Trash / restore | `needle-cloud delete <id>` / `needle-cloud restore <id>` |
|
|
29
|
+
| Ask Cloud AI | `needle-cloud ask "Summarize my assets" --once` |
|
|
30
|
+
| Sign in / out | `needle-cloud login` / `needle-cloud logout` |
|
|
31
|
+
| Inspect / stop the local server | `needle-cloud status` / `needle-cloud stop` |
|
|
213
32
|
|
|
214
|
-
|
|
33
|
+
Use `--team "My Team"` to select a team. Run `needle-cloud help` or
|
|
34
|
+
`needle-cloud help <command>` for all commands and options.
|
|
215
35
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
npx needle-cloud download <identifier> ./assets --label main --format glb
|
|
219
|
-
```
|
|
36
|
+
In a terminal, `list` opens guided browsing; scripts and JSON output use one-shot
|
|
37
|
+
listing. Use `--interactive false` for a plain terminal list.
|
|
220
38
|
|
|
221
|
-
|
|
222
|
-
matching output from that version and its derived outputs. With a label, it
|
|
223
|
-
selects a matching output carrying that label. Without either selector, download
|
|
224
|
-
keeps its existing behavior: the newest source, or the newest matching format.
|
|
225
|
-
Failed lookups and downloads exit with a nonzero code.
|
|
39
|
+
## Deploy with optimized models
|
|
226
40
|
|
|
227
|
-
|
|
228
|
-
|
|
41
|
+
**Needle Engine project:** With `needlePlugins()` configured, the build pipeline
|
|
42
|
+
enabled, and `NEEDLE_CLOUD_TOKEN` set in the build environment:
|
|
229
43
|
|
|
230
44
|
```bash
|
|
231
|
-
npx
|
|
45
|
+
npx vite build -- --production
|
|
46
|
+
npx needle-cloud deploy ./dist --non-interactive
|
|
232
47
|
```
|
|
233
48
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
Deleting content immediately frees total storage capacity, but it does not refund
|
|
238
|
-
the current month's upload usage. Deleted content can be restored from Trash for
|
|
239
|
-
31 days when the account has enough total storage available for it.
|
|
240
|
-
|
|
241
|
-
## Content labels
|
|
242
|
-
|
|
243
|
-
Labels keep a stable URL while you change the version it serves:
|
|
244
|
-
|
|
245
|
-
```bash
|
|
246
|
-
npx needle-cloud label list <content-id> --team "My Team"
|
|
247
|
-
|
|
248
|
-
# Promote the source version currently served by latest
|
|
249
|
-
npx needle-cloud label set <content-id> main --from latest
|
|
250
|
-
|
|
251
|
-
# Move a label to an explicit completed version, including an older version
|
|
252
|
-
npx needle-cloud label set <content-id> main --version <version-id>
|
|
253
|
-
|
|
254
|
-
# Create or move a custom label and return the result as JSON
|
|
255
|
-
npx needle-cloud label set <content-id> staging --from latest --format json
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
`label set` requires exactly one of `--version` or `--from`. The selected version
|
|
259
|
-
must belong to this content item and have completed processing. The server also
|
|
260
|
-
moves the label for related completed outputs. `latest` updates automatically;
|
|
261
|
-
it can be used with `--from` but cannot be assigned manually. New label names use
|
|
262
|
-
lowercase letters, numbers, hyphens or underscores.
|
|
263
|
-
|
|
264
|
-
Both commands support `--token`, `NEEDLE_CLOUD_TOKEN`, saved login, `--team`, and
|
|
265
|
-
`--format cli|json`. Listing requires read access; setting also requires write
|
|
266
|
-
access. Use the content ID and version ID returned by upload, or the IDs shown by
|
|
267
|
-
`list` and `label list`.
|
|
268
|
-
|
|
269
|
-
JSON lists each label's `sourceVersionIds` and `targets`. Each target includes
|
|
270
|
-
`versionId`, `sourceVersionId`, `displayName` and `url`, so source and derived
|
|
271
|
-
outputs remain distinguishable. A null or hidden URL is retained as returned by
|
|
272
|
-
Cloud. Setting returns `contentId`, `label`, the selected `versionId`, observed
|
|
273
|
-
`previousVersionIds`, and the confirmed `targets`. The previous state is a
|
|
274
|
-
snapshot; concurrent updates are not locked. If the update succeeds but cannot
|
|
275
|
-
be confirmed afterward, the command reports that explicitly and exits nonzero.
|
|
276
|
-
|
|
277
|
-
Diagnostics go to stderr; stdout contains only the requested result.
|
|
278
|
-
|
|
279
|
-
## Local tools in Needle Cloud AI
|
|
280
|
-
|
|
281
|
-
[Needle Cloud AI](https://cloud.needle.tools/team#ai) can use local tools provided by this CLI to read project files, search your code, and inspect logs. You can enable or disable local tools in an individual chat. See the [Needle Cloud AI documentation](https://engine.needle.tools/docs/cloud/#needle-cloud-ai) for how this works with your Unity or Blender project.
|
|
282
|
-
|
|
283
|
-
Tools that access files on your machine use `local_files_*`; commands that create, install, build, start a dev server, or deploy a local project use `local_project_*`. Cloud chat asks for approval before running project commands or changing files. After creating a project, the CLI adds it to the local project list and selects it for file tools. The AI can use `local_project_list` and `local_project_select` to return to any registered web project; selecting one does not approve edits. An explicit path to another project for a command requires fresh approval. A running dev server opens its local URL in your default browser and can be stopped with `local_project_cancel`.
|
|
284
|
-
|
|
285
|
-
`local_files_resolve_url` accepts a localhost HTTP URL such as `http://127.0.0.1:8765/preview.html` and returns the working directory of the process listening on that port. The server can have been started by any application. The URL path is returned for context; it is not treated as a file path. If the listener is absent or the OS does not allow inspection, the tool reports that instead of guessing a directory. A proxy or port forward can make the reported directory belong to the proxy rather than the app behind it.
|
|
286
|
-
|
|
287
|
-
The `local_files_check_project` tool checks the connected web project's TypeScript configuration using its locally installed TypeScript compiler. It returns structured errors with file names and line numbers, without emitting build files or applying fixes. It does not run package scripts or install dependencies. Checks stop after 10 seconds and retain up to 100 diagnostics; an unavailable or interrupted check is never reported as passing. This checks current TypeScript errors, not lint rules, Unity/Blender code, or whether an error existed before an AI edit. Referenced projects are not built.
|
|
49
|
+
The production build optimizes models through Cloud and copies the results into
|
|
50
|
+
`dist`. The deploy command uploads that existing output. Plain `vite build` skips
|
|
51
|
+
Needle's production optimization step. See [build configuration](https://engine.needle.tools/docs/reference/needle-vite-plugin#build-pipeline).
|
|
288
52
|
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
Use local tools only with trusted projects and dependencies: the installed TypeScript compiler runs on your machine. This is not an execution sandbox. The existing local-tool controls also govern `local_files_check_project`.
|
|
292
|
-
|
|
293
|
-
To block Needle Cloud AI from calling tools on this machine across all chats, run:
|
|
294
|
-
|
|
295
|
-
```bash
|
|
296
|
-
npx needle-cloud settings remote-ai-tools false
|
|
297
|
-
```
|
|
298
|
-
|
|
299
|
-
To re-enable access (the default):
|
|
53
|
+
**Standalone models:** Upload, wait for optimization, and use the returned
|
|
54
|
+
`optimizedUrl` in your application:
|
|
300
55
|
|
|
301
56
|
```bash
|
|
302
|
-
npx needle-cloud
|
|
57
|
+
npx needle-cloud upload ./model.glb --wait --output json
|
|
303
58
|
```
|
|
304
59
|
|
|
305
|
-
|
|
60
|
+
Use Needle Engine or [gltf-progressive](https://engine.needle.tools/docs/gltf-progressive/)
|
|
61
|
+
for progressive assets, or select `--progressive false` for a loader without
|
|
62
|
+
progressive support. Add `--outdir ./optimized` to download the result instead.
|
|
306
63
|
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
64
|
+
**Safe to repeat:** Cloud reuses unchanged files within the same team and matching
|
|
65
|
+
stored optimization results, avoiding redundant transfers and compression. Use
|
|
66
|
+
`--name <id>` to update an existing asset. See [optimization workflows and reuse](https://engine.needle.tools/docs/cloud/#cli-for-batch-processing).
|
|
310
67
|
|
|
311
|
-
|
|
68
|
+
## Automation
|
|
312
69
|
|
|
313
|
-
|
|
70
|
+
Set `NEEDLE_CLOUD_TOKEN` to a team's read/write access token, then use:
|
|
314
71
|
|
|
315
72
|
```bash
|
|
316
|
-
npx needle-cloud
|
|
317
|
-
npx needle-cloud
|
|
73
|
+
npx needle-cloud upload ./model.glb --wait --non-interactive --output json
|
|
74
|
+
npx needle-cloud deploy ./dist --name my-project --non-interactive --output json
|
|
318
75
|
```
|
|
319
76
|
|
|
320
|
-
|
|
77
|
+
- `--non-interactive` prevents prompts and browser launches; missing credentials fail.
|
|
78
|
+
- `--output json` writes one JSON result to stdout; progress and diagnostics go to stderr.
|
|
79
|
+
- Failed commands exit nonzero. Access tokens retain their team scope.
|
|
321
80
|
|
|
322
|
-
|
|
81
|
+
See [automation and output details](https://engine.needle.tools/docs/cloud/cli#output-and-automation)
|
|
82
|
+
and the [GitHub deployment action](https://github.com/marketplace/actions/deploy-to-needle-cloud).
|
|
83
|
+
CLI v3 is available on the `version-3` channel; integrations can pin `needle-cloud@version-3`.
|
|
323
84
|
|
|
324
|
-
|
|
325
|
-
npx needle-cloud status
|
|
326
|
-
```
|
|
85
|
+
## AI and MCP
|
|
327
86
|
|
|
328
|
-
|
|
329
|
-
servers, a PID read from the local server record is labeled `recorded`.
|
|
330
|
-
|
|
331
|
-
For AI clients that support stdio, use:
|
|
87
|
+
Connect an AI client using stdio:
|
|
332
88
|
|
|
333
89
|
```toml
|
|
334
90
|
[mcp_servers.needle]
|
|
@@ -336,71 +92,22 @@ command = "npx"
|
|
|
336
92
|
args = ["-y", "needle-cloud", "mcp"]
|
|
337
93
|
```
|
|
338
94
|
|
|
339
|
-
On Windows, use `npx.cmd` if your client cannot resolve `npx`.
|
|
340
|
-
|
|
341
|
-
and reconnects if that server restarts. Inspector and Unity tools appear as
|
|
342
|
-
those apps connect. Closing the AI client stops its stdio process; the shared
|
|
343
|
-
local server stays available to other apps. Cloud access follows your
|
|
344
|
-
`remote-ai-tools` setting and requires a signed-in account.
|
|
345
|
-
|
|
346
|
-
While connected to Cloud, MCP also exposes read-only cloud tools with the
|
|
347
|
-
`needle_cloud_` prefix, using your default team (or personal account). For example,
|
|
348
|
-
`needle_cloud_get_file_info` accepts `metadata: ["animations", "bounds"]` and an
|
|
349
|
-
optional version job identifier. Without a metadata selection it returns a compact
|
|
350
|
-
summary; pass `metadata: []` to omit it.
|
|
351
|
-
|
|
352
|
-
Use `needle_cloud_search_content` with `has_animations`, `has_skinned_mesh`, or
|
|
353
|
-
`has_blendshapes` to filter by animation clips, declared skins, or morph targets.
|
|
354
|
-
Filters combine with AND on the same completed variant. Only worker-verified
|
|
355
|
-
facts match; missing facts do not match `false`. Results include up to three
|
|
356
|
-
matching variants with their job identifiers and summaries. These tools read
|
|
357
|
-
existing data and do not run model generation or modify assets. They require
|
|
358
|
-
compatible CLI and Cloud API versions and disappear when Cloud disconnects.
|
|
95
|
+
On Windows, use `npx.cmd` if your client cannot resolve `npx`. The command starts
|
|
96
|
+
or reuses the shared local server. Editor tools appear as their apps connect.
|
|
359
97
|
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
For automated deployments, use an access token:
|
|
365
|
-
|
|
366
|
-
1. Create a token on [your team page](https://cloud.needle.tools/team) with `read/write` permissions
|
|
367
|
-
2. Pass it via `--token` or the `NEEDLE_CLOUD_TOKEN` environment variable
|
|
98
|
+
[Needle Cloud AI](https://engine.needle.tools/docs/cloud/#needle-cloud-ai) can use
|
|
99
|
+
local project tools with approval for file changes and project commands.
|
|
100
|
+
To disable Cloud AI access on this machine:
|
|
368
101
|
|
|
369
102
|
```bash
|
|
370
|
-
npx needle-cloud
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
Or use the official [GitHub Action](https://github.com/marketplace/actions/deploy-to-needle-cloud):
|
|
374
|
-
|
|
375
|
-
```yml
|
|
376
|
-
- uses: needle-tools/deploy-to-needle-cloud-action@v1
|
|
377
|
-
with:
|
|
378
|
-
token: ${{ secrets.NEEDLE_CLOUD_TOKEN }}
|
|
379
|
-
dir: ./dist
|
|
380
|
-
name: my-project
|
|
381
|
-
```
|
|
382
|
-
|
|
383
|
-
## AI evaluation images and quota actions
|
|
384
|
-
|
|
385
|
-
The web API accepts PNG/JPEG image parts in evaluation state:
|
|
386
|
-
|
|
387
|
-
```js
|
|
388
|
-
import { aiEvaluate } from "needle-cloud";
|
|
389
|
-
|
|
390
|
-
const result = await aiEvaluate(
|
|
391
|
-
["Current viewport", { type: "image_url", image_url: { url: pngDataUrl } }],
|
|
392
|
-
{ visible: { type: "boolean", instructions: "Is the selected object visible?" } },
|
|
393
|
-
undefined,
|
|
394
|
-
{ org: teamId },
|
|
395
|
-
);
|
|
103
|
+
npx needle-cloud settings remote-ai-tools false
|
|
396
104
|
```
|
|
397
105
|
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
Chat quota failures expose `details` on HTTP `AIChatError` objects and streamed `error` events. Evaluation errors also expose `details`. The quota metadata contains `code: "ai_allowance_exhausted"`, `account_id`, a readable `message`, and `actions` with `kind`, `label`, and `url` fields. Render these as links: `top_up` opens the team's top-up control; `view_usage` opens its usage section. Opening a link does not automatically purchase credits. Older servers may return text-only errors without `details`.
|
|
106
|
+
See [MCP tools and setup](https://engine.needle.tools/docs/ai/needle-mcp-server)
|
|
107
|
+
and [local tool controls](https://engine.needle.tools/docs/cloud/cli#local-tools-in-needle-cloud-ai).
|
|
401
108
|
|
|
402
|
-
##
|
|
109
|
+
## More information
|
|
403
110
|
|
|
404
|
-
- [
|
|
405
|
-
- [
|
|
406
|
-
- [Pricing](https://needle.tools/pricing)
|
|
111
|
+
- [CLI reference](https://engine.needle.tools/docs/cloud/cli): command options, output formats, versions, labels, local tools, and browser SDK notes.
|
|
112
|
+
- [Cloud documentation](https://engine.needle.tools/docs/cloud/): hosting, asset optimization, teams, and workflows.
|
|
113
|
+
- [Changelog](./CHANGELOG.md) ? [Pricing](https://needle.tools/pricing)
|