@lotics/cli 0.318.36 → 0.318.38
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/README.md +1 -0
- package/dist/src/cli.js +247 -191
- package/dist/src/client.d.ts +38 -1
- package/dist/src/client.js +128 -68
- package/docs/cli_reference.md +1 -0
- package/package.json +1 -1
package/dist/src/client.d.ts
CHANGED
|
@@ -75,6 +75,8 @@ export interface LoticsClientOptions {
|
|
|
75
75
|
* instance's key to production (`docs/on_premise.md` section 8). */
|
|
76
76
|
apiUrl: string;
|
|
77
77
|
workspaceId?: string;
|
|
78
|
+
/** Stops waiting for any answer after this many milliseconds; absent, a call waits for the server. */
|
|
79
|
+
timeoutMs?: number;
|
|
78
80
|
}
|
|
79
81
|
export interface WorkspaceInfo {
|
|
80
82
|
id: string;
|
|
@@ -181,6 +183,31 @@ export declare class LoticsRequestError extends Error {
|
|
|
181
183
|
/** What a command's record may say of it: the message only where the envelope marks it the server's own words. */
|
|
182
184
|
telemetryMessage: string);
|
|
183
185
|
}
|
|
186
|
+
/**
|
|
187
|
+
* The CLI stopped waiting for a call's answer, so it cannot say whether the
|
|
188
|
+
* call took effect: a write the server was still running commits regardless.
|
|
189
|
+
* Only a call that may write ends this way; a read with no answer is a
|
|
190
|
+
* `NoAnswerError`.
|
|
191
|
+
*/
|
|
192
|
+
export declare class OutcomeUnknownError extends Error {
|
|
193
|
+
readonly request_id: string;
|
|
194
|
+
readonly error_code = "outcome_unknown";
|
|
195
|
+
constructor(waited: string, request_id: string, cause?: unknown);
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* No answer arrived to a call that only reads, so nothing changed. `request_id`
|
|
199
|
+
* is absent for a download from object storage, which is no request of ours.
|
|
200
|
+
*/
|
|
201
|
+
export declare class NoAnswerError extends Error {
|
|
202
|
+
readonly request_id: string | undefined;
|
|
203
|
+
constructor(waited: string, request_id: string | undefined, cause?: unknown);
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* A fetch from an object-storage signed URL: not a request of ours, so it
|
|
207
|
+
* carries no id and is held to `timeoutMs` alone. `read` runs inside the wait,
|
|
208
|
+
* because the clock covers the body too.
|
|
209
|
+
*/
|
|
210
|
+
export declare function fetchStorage<T>(url: string, timeoutMs: number | undefined, read: (response: Response) => Promise<T>): Promise<T>;
|
|
184
211
|
/**
|
|
185
212
|
* The website: where a person goes when the CLI cannot finish the job. Held
|
|
186
213
|
* beside the API base and overridable for the same reason — a run against a
|
|
@@ -233,6 +260,7 @@ export declare class LoticsClient {
|
|
|
233
260
|
private workspaceId;
|
|
234
261
|
/** The instance this client sends every request to. */
|
|
235
262
|
readonly baseUrl: string;
|
|
263
|
+
private readonly timeoutMs;
|
|
236
264
|
constructor(options: LoticsClientOptions);
|
|
237
265
|
/**
|
|
238
266
|
* The id is appended to the MESSAGE rather than carried on a field, because
|
|
@@ -260,7 +288,17 @@ export declare class LoticsClient {
|
|
|
260
288
|
* `app deploy`, `uploadFiles` and every workflow call unfindable.
|
|
261
289
|
*/
|
|
262
290
|
private buildHeaders;
|
|
291
|
+
/**
|
|
292
|
+
* The one transport for every call to our API. Waits for the server's answer;
|
|
293
|
+
* only the client's `timeoutMs` stops the wait earlier, and a lost connection
|
|
294
|
+
* ends it too. Either way a call that may write could have taken effect, so
|
|
295
|
+
* it gets `OutcomeUnknownError`, never a plain failure; a read gets
|
|
296
|
+
* `NoAnswerError`, because it changed nothing. `read` turns the answer into
|
|
297
|
+
* the result and runs inside the wait.
|
|
298
|
+
*/
|
|
299
|
+
private call;
|
|
263
300
|
private request;
|
|
301
|
+
private requestForm;
|
|
264
302
|
/** `email` is null for a credential no person signs in as; `account_type` is absent from an older server. */
|
|
265
303
|
/** `credential_origin` describes the CREDENTIAL this call carried, not the
|
|
266
304
|
* member above: `sign_in` for a terminal somebody signed in from, `api_key`
|
|
@@ -350,7 +388,6 @@ export declare class LoticsClient {
|
|
|
350
388
|
getTool(name: string): Promise<ToolInfo>;
|
|
351
389
|
execute(tool: string, args: Record<string, unknown>, options?: {
|
|
352
390
|
format?: "json" | "text";
|
|
353
|
-
timeoutMs?: number;
|
|
354
391
|
}): Promise<ToolExecuteResult>;
|
|
355
392
|
/**
|
|
356
393
|
* Fetch one knowledge doc with its hydrated `content` — the single content-read
|
package/dist/src/client.js
CHANGED
|
@@ -160,6 +160,54 @@ var LoticsRequestError = class extends Error {
|
|
|
160
160
|
body;
|
|
161
161
|
telemetryMessage;
|
|
162
162
|
};
|
|
163
|
+
var OutcomeUnknownError = class extends Error {
|
|
164
|
+
constructor(waited, request_id, cause) {
|
|
165
|
+
super(
|
|
166
|
+
`No answer from the server ${waited}, so this call cannot say whether it took effect. Read the records before running it again. Request id: ${request_id}.`,
|
|
167
|
+
{ cause }
|
|
168
|
+
);
|
|
169
|
+
this.request_id = request_id;
|
|
170
|
+
this.name = "OutcomeUnknownError";
|
|
171
|
+
}
|
|
172
|
+
request_id;
|
|
173
|
+
error_code = "outcome_unknown";
|
|
174
|
+
};
|
|
175
|
+
var NoAnswerError = class extends Error {
|
|
176
|
+
constructor(waited, request_id, cause) {
|
|
177
|
+
super(
|
|
178
|
+
`No answer from ${request_id === void 0 ? "storage" : "the server"} ${waited}. This call only reads, so nothing changed.${request_id === void 0 ? "" : ` Request id: ${request_id}.`}`,
|
|
179
|
+
{ cause }
|
|
180
|
+
);
|
|
181
|
+
this.request_id = request_id;
|
|
182
|
+
this.name = "NoAnswerError";
|
|
183
|
+
}
|
|
184
|
+
request_id;
|
|
185
|
+
};
|
|
186
|
+
async function fetchStorage(url, timeoutMs, read) {
|
|
187
|
+
try {
|
|
188
|
+
return await read(await fetch(url, timeoutMs === void 0 ? {} : { signal: AbortSignal.timeout(timeoutMs) }));
|
|
189
|
+
} catch (error) {
|
|
190
|
+
if (error instanceof Error && error.name === "TimeoutError" && timeoutMs !== void 0) {
|
|
191
|
+
throw new NoAnswerError(`within ${timeoutMs / 1e3}s`, void 0, error);
|
|
192
|
+
}
|
|
193
|
+
throw error;
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
var NEVER_SENT_CODES = /* @__PURE__ */ new Set([
|
|
197
|
+
"ENOTFOUND",
|
|
198
|
+
"ECONNREFUSED",
|
|
199
|
+
"EAI_AGAIN",
|
|
200
|
+
"UND_ERR_CONNECT_TIMEOUT",
|
|
201
|
+
"CERT_HAS_EXPIRED",
|
|
202
|
+
"UNABLE_TO_VERIFY_LEAF_SIGNATURE",
|
|
203
|
+
"DEPTH_ZERO_SELF_SIGNED_CERT",
|
|
204
|
+
"SELF_SIGNED_CERT_IN_CHAIN",
|
|
205
|
+
"UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
|
|
206
|
+
"ERR_TLS_CERT_ALTNAME_INVALID"
|
|
207
|
+
]);
|
|
208
|
+
function errorCode(cause) {
|
|
209
|
+
return typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string" ? cause.code : void 0;
|
|
210
|
+
}
|
|
163
211
|
var WEB_APP_URL = process.env.LOTICS_WEB_URL ?? "https://lotics.ai";
|
|
164
212
|
var PUBLIC_FETCH_TIMEOUT_MS = 1e4;
|
|
165
213
|
async function startCliLogin(apiUrl, email) {
|
|
@@ -212,7 +260,9 @@ var LoticsClient = class {
|
|
|
212
260
|
workspaceId;
|
|
213
261
|
/** The instance this client sends every request to. */
|
|
214
262
|
baseUrl;
|
|
263
|
+
timeoutMs;
|
|
215
264
|
constructor(options) {
|
|
265
|
+
this.timeoutMs = options.timeoutMs;
|
|
216
266
|
this.apiKey = options.apiKey;
|
|
217
267
|
this.workspaceId = options.workspaceId;
|
|
218
268
|
this.baseUrl = options.apiUrl;
|
|
@@ -229,7 +279,20 @@ var LoticsClient = class {
|
|
|
229
279
|
* logs. Every call against the API passes the id its own headers carry.
|
|
230
280
|
*/
|
|
231
281
|
async throwResponseError(response, requestId) {
|
|
232
|
-
const
|
|
282
|
+
const trace = requestId === void 0 ? "" : `
|
|
283
|
+
|
|
284
|
+
Request id: ${requestId} \u2014 quote this to Lotics support.`;
|
|
285
|
+
let text;
|
|
286
|
+
try {
|
|
287
|
+
text = await response.text();
|
|
288
|
+
} catch (readError) {
|
|
289
|
+
throw new LoticsRequestError(
|
|
290
|
+
`${response.status}: the server refused with HTTP ${response.status} and its error body could not be read (${readError instanceof Error ? readError.message : String(readError)})${trace}`,
|
|
291
|
+
response.status,
|
|
292
|
+
{},
|
|
293
|
+
`${response.status}: ${telemetryErrorMessage(response.status, {})}${trace}`
|
|
294
|
+
);
|
|
295
|
+
}
|
|
233
296
|
let body = {};
|
|
234
297
|
try {
|
|
235
298
|
const json = JSON.parse(text);
|
|
@@ -240,9 +303,6 @@ var LoticsClient = class {
|
|
|
240
303
|
const message = typeof body.message === "string" ? body.message : unparsedAnswer(text);
|
|
241
304
|
const hint = typeof body.hint === "string" ? `
|
|
242
305
|
${body.hint}` : "";
|
|
243
|
-
const trace = requestId === void 0 ? "" : `
|
|
244
|
-
|
|
245
|
-
Request id: ${requestId} \u2014 quote this to Lotics support.`;
|
|
246
306
|
throw new LoticsRequestError(
|
|
247
307
|
`${response.status}: ${message}${hint}${trace}`,
|
|
248
308
|
response.status,
|
|
@@ -284,17 +344,54 @@ var LoticsClient = class {
|
|
|
284
344
|
headers["x-request-id"] = newRequestId();
|
|
285
345
|
return headers;
|
|
286
346
|
}
|
|
287
|
-
|
|
347
|
+
/**
|
|
348
|
+
* The one transport for every call to our API. Waits for the server's answer;
|
|
349
|
+
* only the client's `timeoutMs` stops the wait earlier, and a lost connection
|
|
350
|
+
* ends it too. Either way a call that may write could have taken effect, so
|
|
351
|
+
* it gets `OutcomeUnknownError`, never a plain failure; a read gets
|
|
352
|
+
* `NoAnswerError`, because it changed nothing. `read` turns the answer into
|
|
353
|
+
* the result and runs inside the wait.
|
|
354
|
+
*/
|
|
355
|
+
async call(method, path2, body, read) {
|
|
288
356
|
const url = `${this.baseUrl}${path2}`;
|
|
289
357
|
const headers = this.buildHeaders();
|
|
358
|
+
const requestId = headers["x-request-id"];
|
|
359
|
+
const timeoutMs = this.timeoutMs;
|
|
360
|
+
const readOnly = method === "GET" || method === "HEAD";
|
|
361
|
+
const noAnswer = (waited, cause) => readOnly ? new NoAnswerError(waited, requestId, cause) : new OutcomeUnknownError(waited, requestId, cause);
|
|
290
362
|
const init = { method, headers };
|
|
291
|
-
if (
|
|
363
|
+
if (timeoutMs !== void 0) init.signal = AbortSignal.timeout(timeoutMs);
|
|
364
|
+
if (body?.kind === "json") {
|
|
292
365
|
headers["Content-Type"] = "application/json";
|
|
293
|
-
init.body = JSON.stringify(body);
|
|
366
|
+
init.body = JSON.stringify(body.value);
|
|
367
|
+
} else if (body?.kind === "form") {
|
|
368
|
+
init.body = body.value;
|
|
369
|
+
}
|
|
370
|
+
try {
|
|
371
|
+
const response = await fetch(url, init);
|
|
372
|
+
if (!response.ok) {
|
|
373
|
+
if (response.status >= 500 && !response.headers.has("x-request-id")) {
|
|
374
|
+
throw noAnswer(`before the gateway in front of it gave up (HTTP ${response.status})`);
|
|
375
|
+
}
|
|
376
|
+
await this.throwResponseError(response, requestId);
|
|
377
|
+
}
|
|
378
|
+
return await read(response);
|
|
379
|
+
} catch (error) {
|
|
380
|
+
if (error instanceof LoticsRequestError || error instanceof OutcomeUnknownError || error instanceof NoAnswerError) throw error;
|
|
381
|
+
if (error instanceof Error && error.name === "TimeoutError" && timeoutMs !== void 0) {
|
|
382
|
+
throw noAnswer(`within ${timeoutMs / 1e3}s`, error);
|
|
383
|
+
}
|
|
384
|
+
if (error instanceof TypeError && error.cause !== void 0 && !NEVER_SENT_CODES.has(errorCode(error.cause))) {
|
|
385
|
+
throw noAnswer("before the connection closed", error.cause);
|
|
386
|
+
}
|
|
387
|
+
throw error;
|
|
294
388
|
}
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
return response.json();
|
|
389
|
+
}
|
|
390
|
+
async request(method, path2, body) {
|
|
391
|
+
return this.call(method, path2, body === void 0 ? void 0 : { kind: "json", value: body }, async (response) => await response.json());
|
|
392
|
+
}
|
|
393
|
+
async requestForm(method, path2, form) {
|
|
394
|
+
return this.call(method, path2, { kind: "form", value: form }, async (response) => await response.json());
|
|
298
395
|
}
|
|
299
396
|
/** `email` is null for a credential no person signs in as; `account_type` is absent from an older server. */
|
|
300
397
|
/** `credential_origin` describes the CREDENTIAL this call carried, not the
|
|
@@ -353,31 +450,7 @@ var LoticsClient = class {
|
|
|
353
450
|
return this.request("GET", `/v1/tools/${encodeURIComponent(name)}`);
|
|
354
451
|
}
|
|
355
452
|
async execute(tool, args, options) {
|
|
356
|
-
|
|
357
|
-
if (options?.timeoutMs) {
|
|
358
|
-
const controller = new AbortController();
|
|
359
|
-
const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
|
|
360
|
-
try {
|
|
361
|
-
const url = `${this.baseUrl}/v1/tools/execute`;
|
|
362
|
-
const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
|
|
363
|
-
const response = await fetch(url, {
|
|
364
|
-
method: "POST",
|
|
365
|
-
headers,
|
|
366
|
-
body: JSON.stringify(body),
|
|
367
|
-
signal: controller.signal
|
|
368
|
-
});
|
|
369
|
-
if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
|
|
370
|
-
return response.json();
|
|
371
|
-
} catch (error) {
|
|
372
|
-
if (error instanceof Error && error.name === "AbortError") {
|
|
373
|
-
throw new Error(`Tool execution timed out after ${options.timeoutMs}ms`);
|
|
374
|
-
}
|
|
375
|
-
throw error;
|
|
376
|
-
} finally {
|
|
377
|
-
clearTimeout(timeout);
|
|
378
|
-
}
|
|
379
|
-
}
|
|
380
|
-
return this.request("POST", "/v1/tools/execute", body);
|
|
453
|
+
return this.request("POST", "/v1/tools/execute", { tool, args, format: options?.format ?? "text" });
|
|
381
454
|
}
|
|
382
455
|
// --- Knowledge docs ---
|
|
383
456
|
/**
|
|
@@ -422,9 +495,10 @@ var LoticsClient = class {
|
|
|
422
495
|
"GET",
|
|
423
496
|
`/v1/apps/${encodeURIComponent(appId)}/versions/${encodeURIComponent(versionId)}/source`
|
|
424
497
|
);
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
498
|
+
return fetchStorage(url, this.timeoutMs, async (response) => {
|
|
499
|
+
if (!response.ok) await this.throwResponseError(response);
|
|
500
|
+
return Buffer.from(await response.arrayBuffer());
|
|
501
|
+
});
|
|
428
502
|
}
|
|
429
503
|
/**
|
|
430
504
|
* Workspace-wide dangling-reference sweep — active app/workflow artifacts
|
|
@@ -465,20 +539,13 @@ var LoticsClient = class {
|
|
|
465
539
|
);
|
|
466
540
|
if (args.prev_version_id) formData.append("prev_version_id", args.prev_version_id);
|
|
467
541
|
if (args.message) formData.append("message", args.message);
|
|
468
|
-
|
|
469
|
-
const headers = this.buildHeaders();
|
|
470
|
-
const response = await fetch(url, { method: "POST", headers, body: formData });
|
|
471
|
-
if (!response.ok) {
|
|
472
|
-
await this.throwResponseError(response, headers["x-request-id"]);
|
|
473
|
-
}
|
|
474
|
-
return response.json();
|
|
542
|
+
return this.requestForm("POST", `/v1/apps/${encodeURIComponent(args.app_id)}/versions`, formData);
|
|
475
543
|
}
|
|
476
544
|
async downloadFile(url, outputPath) {
|
|
477
|
-
const
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
}
|
|
481
|
-
const buffer = Buffer.from(await response.arrayBuffer());
|
|
545
|
+
const buffer = await fetchStorage(url, this.timeoutMs, async (response) => {
|
|
546
|
+
if (!response.ok) throw new Error(`${response.status}: Failed to download file`);
|
|
547
|
+
return Buffer.from(await response.arrayBuffer());
|
|
548
|
+
});
|
|
482
549
|
const absolutePath = path.resolve(outputPath);
|
|
483
550
|
await fs.promises.mkdir(path.dirname(absolutePath), { recursive: true });
|
|
484
551
|
await fs.promises.writeFile(absolutePath, buffer);
|
|
@@ -500,20 +567,12 @@ var LoticsClient = class {
|
|
|
500
567
|
return this.request("GET", `/v1/files${query ? `?${query}` : ""}`);
|
|
501
568
|
}
|
|
502
569
|
async downloadFileById(fileId, destination, options) {
|
|
503
|
-
const
|
|
504
|
-
const
|
|
505
|
-
|
|
506
|
-
{ headers:
|
|
507
|
-
);
|
|
508
|
-
if (!signedUrlRes.ok) {
|
|
509
|
-
await this.throwResponseError(signedUrlRes, signedHeaders["x-request-id"]);
|
|
510
|
-
}
|
|
511
|
-
const { url } = await signedUrlRes.json();
|
|
512
|
-
const response = await fetch(url);
|
|
513
|
-
if (!response.ok) await this.throwResponseError(response);
|
|
514
|
-
const disposition = response.headers.get("content-disposition") ?? "";
|
|
570
|
+
const { url } = await this.request("GET", `/v1/files/${encodeURIComponent(fileId)}/signed_url`);
|
|
571
|
+
const { disposition, buffer } = await fetchStorage(url, this.timeoutMs, async (response) => {
|
|
572
|
+
if (!response.ok) await this.throwResponseError(response);
|
|
573
|
+
return { disposition: response.headers.get("content-disposition") ?? "", buffer: Buffer.from(await response.arrayBuffer()) };
|
|
574
|
+
});
|
|
515
575
|
const originalFilename = parseContentDispositionFilename(disposition) ?? fileId;
|
|
516
|
-
const buffer = Buffer.from(await response.arrayBuffer());
|
|
517
576
|
const { dir, named } = destination === void 0 ? { dir: process.cwd() } : "file" in destination ? {
|
|
518
577
|
dir: path.dirname(path.resolve(destination.file)),
|
|
519
578
|
named: path.basename(destination.file)
|
|
@@ -562,6 +621,7 @@ var LoticsClient = class {
|
|
|
562
621
|
files.push(...result.files);
|
|
563
622
|
errors.push(...result.errors);
|
|
564
623
|
} catch (error) {
|
|
624
|
+
if (error instanceof OutcomeUnknownError) throw error;
|
|
565
625
|
const message = error instanceof Error ? error.message : String(error);
|
|
566
626
|
errors.push(...sent.map((item) => ({ filename: item.filename, error: message })));
|
|
567
627
|
}
|
|
@@ -583,6 +643,7 @@ var LoticsClient = class {
|
|
|
583
643
|
try {
|
|
584
644
|
files.push(await this.uploadLargeFile(item));
|
|
585
645
|
} catch (error) {
|
|
646
|
+
if (error instanceof OutcomeUnknownError) throw error;
|
|
586
647
|
errors.push({
|
|
587
648
|
filename: item.filename,
|
|
588
649
|
error: error instanceof Error ? error.message : String(error)
|
|
@@ -685,17 +746,16 @@ var LoticsClient = class {
|
|
|
685
746
|
const mimeType = item.mimeType ?? getMimeType(item.filename);
|
|
686
747
|
formData.append("file", new Blob([item.bytes], { type: mimeType }), item.filename);
|
|
687
748
|
}
|
|
688
|
-
|
|
689
|
-
const headers = this.buildHeaders();
|
|
690
|
-
const response = await fetch(url, { method: "POST", headers, body: formData });
|
|
691
|
-
if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
|
|
692
|
-
return response.json();
|
|
749
|
+
return this.requestForm("POST", "/v1/files", formData);
|
|
693
750
|
}
|
|
694
751
|
};
|
|
695
752
|
export {
|
|
696
753
|
LoticsClient,
|
|
697
754
|
LoticsRequestError,
|
|
755
|
+
NoAnswerError,
|
|
756
|
+
OutcomeUnknownError,
|
|
698
757
|
WEB_APP_URL,
|
|
758
|
+
fetchStorage,
|
|
699
759
|
findAvailableFilename,
|
|
700
760
|
pollCliLogin,
|
|
701
761
|
startCliLogin
|
package/docs/cli_reference.md
CHANGED
|
@@ -8,6 +8,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
|
|
|
8
8
|
| `lotics auth signup <email>` | Create account + org + API key, sends magic link email. Refused on a private instance, whose people arrive by invitation; prints that creating the account accepts the Terms and Privacy Policy. Registers the new org as a profile; `--local` pins this directory to it (pointer) instead of setting the global default. |
|
|
9
9
|
| `lotics auth login <email>` | Sign in an account that already exists, on a machine holding no key. **Two steps, and it does not wait for the person.** The first prints the page to open — `https://lotics.ai/cli_login/<request_id>`, also mailed — and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code and press Confirm. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential — `docs` among them — claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `email`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |
|
|
10
10
|
| — | **A flag is refused on a verb that does not read it**, naming the verbs that do, before any request or credential: `--check` on `lotics run` would otherwise be parsed and ignored, and the write it was meant to stop would run. `--json`, `--workspace`, `--api-key` and `--timeout` are read by every verb. |
|
|
11
|
+
| — | **Every call a verb makes waits for the server's answer**; `--timeout <ms>` (a whole number of milliseconds from 1 to 2147483647) stops each wait early. The wait ends without an answer when `--timeout` passes or no answer arrives from the server. A read with no answer changed nothing: the command exits non-zero naming the request id. A write with no answer exits non-zero with `error_code: "outcome_unknown"` and the request id under `--json`, because it cannot say whether the call took effect: read before running it again. The one fetch outside this is the download from an object-storage signed URL, which carries no request id and is stopped by `--timeout` alone. Under `--json` every error is one object on stdout: `error`, with `error_code` and `request_id` where the error has them. |
|
|
11
12
|
| `lotics auth api-key [key]` | `whoami` → **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |
|
|
12
13
|
| `lotics auth web` | Send a magic link email to access the web app (requires auth) |
|
|
13
14
|
| `lotics auth whoami` | Print active account name, email, org, resolved workspace, the instance the credential belongs to, which **kind** of credential this machine holds (a sign-in from `auth login`, or an API key — read from the saved profile, and from the server when the profile does not say, which covers `--api-key`/`LOTICS_API_KEY` and a profile saved before the field existed; unknown only when neither can say), and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id`, `api_url`, `credential_kind` + `source`. |
|