@layoutplatforms/cli 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Layout CLI
 
-Sign in to your Layout developer account and build against the sandbox from your terminal. It never touches production.
+Sign in to your Layout developer account, build against the sandbox, and read production from your terminal. It never changes production or moves money.
 
 ```
 npm i -g @layoutplatforms/cli
@@ -13,24 +13,27 @@ Or run it once without installing: `npx @layoutplatforms/cli login`. Node 20 or
 
 | Command | What it does |
 |---|---|
-| `layout login` | Sign in with a code you approve in the console. |
+| `layout login [--live]` | Sign in with a code you approve in the console. `--live` adds 12 hours of production reads. |
 | `layout logout` | Revoke this CLI session and forget it here. |
 | `layout whoami` | Your developer account and this CLI session. |
 | `layout apps list`, `layout apps create` | Your applications. |
 | `layout keys list`, `layout keys create`, `layout keys revoke` | Your sandbox secret key. |
 | `layout webhooks list` | Your webhook endpoints. Add them in the console. |
-| `layout listen --forward-to <url>` | Forward sandbox events to your machine, signed like real webhooks. |
+| `layout listen --forward-to <url>` | Forward events to your machine, signed like real webhooks. |
 | `layout trigger <event>` | Send a test event to your endpoints. |
+| `layout api get /v1/places?query=coffee` | Call any REST endpoint and print the answer. |
 | `layout test-order` | Run a whole order against a sandbox test restaurant. |
 | `layout usage` | Your limits and what you have used today. |
-| `layout deliveries` | Recent sandbox webhook deliveries. |
+| `layout deliveries` | Recent webhook deliveries. |
 | `layout request-live-access` | Ask Layout to review production access. |
 | `layout docs` | Open the docs. |
 
-Every command takes `--json`, so a coding agent can drive it.
+Every command takes `--json`, so a coding agent can drive it. `listen`, `deliveries`, `keys list` and `webhooks list` take `--live`.
+
+In CI, set `LAYOUT_SECRET_KEY` to a sandbox key and `layout api` and `layout test-order` run without signing in.
 
 ## What a CLI session can do
 
-A CLI session works in sandbox only. It cannot create or read live keys, change live settings, or place a real order. Live access is requested from the CLI and approved by a person in the console.
+In sandbox, everything you need to build. In production, with `layout login --live` approved from a fresh console sign-in, it reads live events, deliveries and key details for 12 hours. It never creates or shows live keys, changes production settings or places an order.
 
 Full reference: https://developer.layout.link/reference/cli

package/dist/args.js

@@ -11,8 +11,12 @@ export function parseArgs(argv, specs) {
         all.set(s.name, s);
     const positionals = [];
     const flags = {};
+    const shorts = new Map();
+    for (const s of all.values())
+        if (s.short)
+            shorts.set(`-${s.short}`, `--${s.name}`);
     for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
+        const arg = shorts.get(argv[i]) ?? argv[i];
         if (arg === "--") {
             positionals.push(...argv.slice(i + 1));
             break;
@@ -40,7 +44,10 @@ export function parseArgs(argv, specs) {
         const value = eq !== -1 ? arg.slice(eq + 1) : argv[++i];
         if (value === undefined || (eq === -1 && value.startsWith("--")))
             throw usageError(`--${name} needs a value.`);
-        flags[spec.name] = value;
+        if (spec.type === "list")
+            flags[spec.name] = [...(flags[spec.name] ?? []), value];
+        else
+            flags[spec.name] = value;
     }
     return { positionals, flags };
 }
@@ -48,6 +55,10 @@ export function str(p, name) {
     const v = p.flags[name];
     return typeof v === "string" ? v : undefined;
 }
+export function list(p, name) {
+    const v = p.flags[name];
+    return Array.isArray(v) ? v : [];
+}
 export function bool(p, name) {
     return p.flags[name] === true;
 }

package/dist/commands/api.js

@@ -0,0 +1,127 @@
+import { readFileSync } from "node:fs";
+import { bool, list, str } from "../args.js";
+import { CliError, EXIT, exitForStatus, usageError } from "../errors.js";
+import { dropSandboxSecret, envSecret, pickApp, sandboxSecret, SECRET_ENV } from "../context.js";
+const METHODS = new Set(["GET", "POST", "DELETE"]);
+export function apiPath(raw) {
+    if (!raw)
+        throw usageError("Name a path: layout api get /v1/places?query=coffee.");
+    const p = raw.startsWith("/") ? raw : `/${raw}`;
+    const withV1 = p.startsWith("/v1/") || p === "/v1" ? p : `/v1${p}`;
+    const pathPart = withV1.split("?")[0];
+    if (/\/\/|[\s\\%]|\/\.\.?(?:\/|$)|:/.test(pathPart) || /\s/.test(withV1))
+        throw usageError("The path must be a Layout API path such as /v1/carts/<id>.");
+    if (/^\/v1\/cli(?:\/|$)/.test(pathPart))
+        throw usageError("The /v1/cli routes are the CLI's own; use the commands instead.");
+    return withV1;
+}
+function fieldValue(v) {
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        return v;
+    }
+}
+export function apiBody(data, fields) {
+    let body;
+    if (data !== undefined) {
+        let text = data;
+        if (data.startsWith("@")) {
+            try {
+                text = readFileSync(data.slice(1), "utf8");
+            }
+            catch {
+                throw usageError(`Could not read ${data.slice(1)}.`);
+            }
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw usageError("--data must be a JSON object, or @file holding one.");
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw usageError("--data must be a JSON object.");
+        body = parsed;
+    }
+    for (const f of fields) {
+        const eq = f.indexOf("=");
+        if (eq < 1)
+            throw usageError(`-d takes name=value, not ${f}.`);
+        body = { ...(body ?? {}), [f.slice(0, eq)]: fieldValue(f.slice(eq + 1)) };
+    }
+    return body;
+}
+async function credential(ctx, live) {
+    const token = str(ctx.args, "token")?.trim();
+    if (token)
+        return { bearer: token, source: "token", app: null };
+    const key = envSecret(ctx);
+    if (key) {
+        if (key.startsWith("sk_live_") && !live)
+            throw usageError(`${SECRET_ENV} is a live secret. Add --live to read production.`);
+        if (key.startsWith("sk_test_") && live)
+            throw usageError(`${SECRET_ENV} is a sandbox secret, so --live cannot use it.`);
+        return { bearer: key, source: "env", app: null };
+    }
+    if (live)
+        throw usageError(`Production requests use your own live secret: set ${SECRET_ENV}=sk_live_... The CLI never reads live secrets.`);
+    const app = await pickApp(ctx);
+    return { bearer: await sandboxSecret(ctx, app), source: "cli", app };
+}
+/**
+ * THE CLI NEVER CHANGES PRODUCTION. A write runs only after Layout says, for this very credential, that it
+ * is sandbox; a credential Layout cannot place is refused rather than trusted.
+ */
+async function assertSandbox(ctx, bearer) {
+    const res = await ctx.api.request("/v1/whoami", { auth: bearer, anyStatus: true });
+    if (res.status === 200 && res.data?.environment === "sandbox")
+        return;
+    if (res.status === 200 && res.data?.environment === "live") {
+        throw new CliError("live_write_refused", "This credential is for production. The CLI reads production but never changes it.", EXIT.refused);
+    }
+    throw new CliError("environment_unknown", `Layout could not say this credential is sandbox (${res.status}), so nothing was sent.`, res.status === 401 ? EXIT.auth : EXIT.refused);
+}
+export async function api(ctx) {
+    const { out } = ctx;
+    const method = (ctx.args.positionals[1] ?? "").toUpperCase();
+    if (!METHODS.has(method))
+        throw usageError("Name a method and a path: layout api get /v1/places?query=coffee. Methods: get, post, delete.");
+    const path = apiPath(ctx.args.positionals[2]);
+    if (ctx.args.positionals.length > 3)
+        throw usageError(`Unexpected argument: ${ctx.args.positionals[3]}. Quote a path that holds & or ?.`);
+    const live = bool(ctx.args, "live");
+    const body = apiBody(str(ctx.args, "data"), list(ctx.args, "field"));
+    if (body !== undefined && method !== "POST")
+        throw usageError("Only a POST takes a body.");
+    if (live && method !== "GET")
+        throw new CliError("live_write_refused", "The CLI reads production but never changes it. Only get works with --live.", EXIT.refused);
+    let cred = await credential(ctx, live);
+    if (method !== "GET")
+        await assertSandbox(ctx, cred.bearer);
+    const send = (bearer) => ctx.api.request(path, {
+        method: method,
+        auth: bearer,
+        ...(body === undefined ? (method === "POST" ? { body: {} } : {}) : { body }),
+        anyStatus: true,
+        retry: method === "GET" || method === "POST",
+        ...(method === "POST" ? { idempotencyKey: str(ctx.args, "idempotency-key") ?? undefined, idempotent: true } : {}),
+    });
+    let res = await send(cred.bearer);
+    if (res.status === 401 && cred.source === "cli" && cred.app) {
+        dropSandboxSecret(ctx, cred.app);
+        cred = { ...cred, bearer: await sandboxSecret(ctx, cred.app, true) };
+        res = await send(cred.bearer);
+    }
+    const requestId = res.headers.get("x-request-id");
+    if (out.json) {
+        out.data({ status: res.status, requestId, replayed: res.headers.get("idempotent-replayed") === "true", body: res.data });
+    }
+    else {
+        out.note(`${res.status}${requestId ? `  ${requestId}` : ""}${res.headers.get("idempotent-replayed") === "true" ? "  replayed" : ""}`);
+        ctx.p.streams.out.write(`${JSON.stringify(res.data, null, 2)}\n`);
+    }
+    return res.status >= 200 && res.status < 300 ? EXIT.ok : exitForStatus(res.status);
+}

package/dist/commands/listen.js

@@ -3,12 +3,13 @@ import { bool, str } from "../args.js";
 import { configDir, hostKey, readJson, writePrivateJson } from "../config.js";
 import { EXIT, usageError } from "../errors.js";
 import { authed, pickApp } from "../context.js";
-import { WEBHOOKS_PAGE } from "./resources.js";
+import { isLive, WEBHOOKS_PAGE } from "./resources.js";
 import { mintLocalSecret, runListener } from "../listen.js";
-export function cursorFile(env, base, app) {
-    return join(configDir(env), "listen", hostKey(base).replace(/[^A-Za-z0-9.-]/g, "_"), `${app.replace(/[^A-Za-z0-9_]/g, "_")}.json`);
+export function cursorFile(env, base, app, live = false) {
+    return join(configDir(env), "listen", hostKey(base).replace(/[^A-Za-z0-9.-]/g, "_"), `${app.replace(/[^A-Za-z0-9_]/g, "_")}${live ? ".live" : ""}.json`);
 }
-function forwardUrl(raw) {
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+function forwardUrl(raw, live = false) {
     if (!raw)
         throw usageError("Give --forward-to, for example --forward-to http://localhost:3000/webhooks/layout.");
     let url;
@@ -20,16 +21,20 @@ function forwardUrl(raw) {
     }
     if (url.protocol !== "http:" && url.protocol !== "https:")
         throw usageError("--forward-to must be an http or https URL.");
+    if (live && url.protocol === "http:" && !LOOPBACK.has(url.hostname))
+        throw usageError("With --live, --forward-to must be https or this computer (localhost), so production data is never sent in the clear.");
     return url.toString();
 }
 export async function listen(ctx) {
     const { out, p } = ctx;
-    const forwardTo = forwardUrl(str(ctx.args, "forward-to"));
+    const forwardTo = forwardUrl(str(ctx.args, "forward-to"), isLive(ctx));
     const filter = str(ctx.args, "events");
     const events = filter ? new Set(filter.split(",").map((s) => s.trim()).filter(Boolean)) : null;
     const app = await pickApp(ctx);
+    const live = isLive(ctx);
     const enc = encodeURIComponent(app);
-    const stateFile = cursorFile(ctx.env, ctx.base, app);
+    const envq = live ? "environment=live" : "";
+    const stateFile = cursorFile(ctx.env, ctx.base, app, live);
     const saved = readJson(stateFile)?.cursor ?? null;
     let start;
     if (bool(ctx.args, "from-start"))
@@ -37,13 +42,13 @@ export async function listen(ctx) {
     else if (saved)
         start = saved;
     else
-        start = (await authed(ctx, `/v1/cli/apps/${enc}/events/cursor`)).cursor;
-    const hooks = await authed(ctx, `/v1/cli/apps/${enc}/webhooks`);
+        start = (await authed(ctx, `/v1/cli/apps/${enc}/events/cursor${envq ? `?${envq}` : ""}`)).cursor;
+    const hooks = await authed(ctx, `/v1/cli/apps/${enc}/webhooks${envq ? `?${envq}` : ""}`);
     const secret = mintLocalSecret();
     if (out.json)
-        out.data({ event: "listening", app, forwardTo, secret, resumed: Boolean(saved) && !bool(ctx.args, "from-start") });
+        out.data({ event: "listening", app, environment: live ? "live" : "sandbox", forwardTo, secret, resumed: Boolean(saved) && !bool(ctx.args, "from-start") });
     else {
-        out.line(`Forwarding sandbox events for ${app} to ${forwardTo}`);
+        out.line(`Forwarding ${live ? out.accent("production") : "sandbox"} events for ${app} to ${forwardTo}`);
         out.line(`Signing secret for this run  ${out.accent(secret)}`);
         out.line(saved && !bool(ctx.args, "from-start") ? "Resuming after the last event forwarded." : "Starting from now. Press Ctrl-C to stop.");
     }
@@ -70,8 +75,8 @@ export async function listen(ctx) {
         }
     };
     try {
-        await runListener(start, { forwardTo, secret, events, pollMs: 2_000, maxBackoffMs: 30_000 }, {
-            fetchPage: (cursor) => authed(ctx, `/v1/cli/apps/${enc}/events?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`, { retry: false }),
+        await runListener(start, { forwardTo, secret, events, pollMs: 2_000, maxBackoffMs: 30_000, environment: live ? "live" : "sandbox" }, {
+            fetchPage: (cursor) => authed(ctx, `/v1/cli/apps/${enc}/events?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}${envq ? `&${envq}` : ""}`, { retry: false }),
             forward: async (url, body, headers) => {
                 const res = await p.http.fetch(url, { method: "POST", headers, body, signal: AbortSignal.timeout(10_000), redirect: "manual" });
                 await res.arrayBuffer().catch(() => undefined);

package/dist/commands/resources.js

@@ -1,7 +1,10 @@
 import { bool, str } from "../args.js";
 import { DOCS_BASE } from "../config.js";
 import { CliError, EXIT, usageError } from "../errors.js";
-import { authed, pickApp } from "../context.js";
+import { authed, dropSandboxSecret, pickApp } from "../context.js";
+export const isLive = (ctx) => bool(ctx.args, "live");
+const envName = (ctx) => (isLive(ctx) ? "production" : "sandbox");
+const withEnv = (ctx, path) => (isLive(ctx) ? `${path}${path.includes("?") ? "&" : "?"}environment=live` : path);
 export const WEBHOOKS_PAGE = `${DOCS_BASE}/console/webhooks/subscriptions`;
 const SHOWN_ONCE = "Shown once. Store it in your secret manager, never in source control.";
 export async function appsList(ctx) {
@@ -30,11 +33,11 @@ export async function appsCreate(ctx) {
 }
 export async function keysList(ctx) {
     const app = await pickApp(ctx);
-    const data = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/keys`);
+    const data = await authed(ctx, withEnv(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/keys`));
     ctx.out.result({ app, ...data }, () => {
         if (data.keys.length === 0)
-            return ctx.out.line("No sandbox key. Create one with layout keys create.");
-        ctx.out.table(data.keys.map((k) => [k.clientId, `sk_test_...${k.last4}`, k.createdAt.slice(0, 10), k.lastUsedAt ? k.lastUsedAt.slice(0, 10) : "never"]), ["CLIENT ID", "SECRET", "CREATED", "LAST USED"]);
+            return ctx.out.line(isLive(ctx) ? "No production key." : "No sandbox key. Create one with layout keys create.");
+        ctx.out.table(data.keys.map((k) => [k.clientId, `${isLive(ctx) ? "sk_live_" : "sk_test_"}...${k.last4}`, k.createdAt.slice(0, 10), k.lastUsedAt ? k.lastUsedAt.slice(0, 10) : "never"]), ["CLIENT ID", "SECRET", "CREATED", "LAST USED"]);
     });
     return EXIT.ok;
 }
@@ -48,6 +51,7 @@ export async function keysCreate(ctx) {
         }
         throw err;
     });
+    dropSandboxSecret(ctx, app);
     ctx.out.result({ app, ...data }, () => {
         ctx.out.line(data.replaced ? "New sandbox key. The old one no longer works." : "New sandbox key.");
         ctx.out.line(`Client id  ${data.clientId}`);
@@ -64,6 +68,7 @@ export async function keysRevoke(ctx) {
     const data = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/keys/revoke`, {
         method: "POST", body: {}, idempotent: true, retry: true,
     });
+    dropSandboxSecret(ctx, app);
     ctx.out.result({ app, ...data }, () => {
         ctx.out.line(data.revoked > 0 ? "Sandbox key revoked." : "There was no sandbox key to revoke.");
     });
@@ -71,7 +76,7 @@ export async function keysRevoke(ctx) {
 }
 export async function webhooksList(ctx) {
     const app = await pickApp(ctx);
-    const data = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/webhooks`);
+    const data = await authed(ctx, withEnv(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/webhooks`));
     ctx.out.result({ app, ...data }, () => {
         if (data.subscriptions.length === 0)
             ctx.out.line(`No webhook endpoints. Add one once in the console: ${WEBHOOKS_PAGE}`);
@@ -79,6 +84,8 @@ export async function webhooksList(ctx) {
             ctx.out.table(data.subscriptions.map((s) => [s.id, s.enabled ? "on" : "off", s.url, s.events.join(",")]), ["ID", "STATE", "URL", "EVENTS"]);
         if (data.signingSecret)
             ctx.out.line(`Sandbox signing secret  ${data.signingSecret}`);
+        else if (isLive(ctx))
+            ctx.out.line(`The production signing secret is shown only in the console.`);
         ctx.out.line(`Endpoints are managed in the console: ${WEBHOOKS_PAGE}`);
     });
     return EXIT.ok;
@@ -116,10 +123,10 @@ export async function deliveries(ctx) {
     const limit = Number(str(ctx.args, "limit") ?? "20");
     if (!Number.isInteger(limit) || limit < 1 || limit > 100)
         throw usageError("--limit is a whole number from 1 to 100.");
-    const data = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/deliveries?limit=${limit}`);
+    const data = await authed(ctx, withEnv(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/deliveries?limit=${limit}`));
     ctx.out.result({ app, ...data }, () => {
         if (data.deliveries.length === 0)
-            return ctx.out.line("No sandbox deliveries yet.");
+            return ctx.out.line(`No ${envName(ctx)} deliveries yet.`);
         ctx.out.table(data.deliveries.map((d) => [d.createdAt.replace("T", " ").slice(0, 19), d.event, d.status, d.responseStatus === null ? "" : String(d.responseStatus), d.url]), ["WHEN", "EVENT", "STATUS", "HTTP", "URL"]);
     });
     return EXIT.ok;

package/dist/commands/session.js

@@ -4,19 +4,23 @@ import { chooseStore, fileStore, storeOfKind } from "../credentials.js";
 import { CliError, EXIT } from "../errors.js";
 import { authed, forget } from "../context.js";
 const GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+function localTime(iso) {
+    const d = new Date(iso);
+    return Number.isNaN(d.getTime()) ? iso : d.toLocaleString(undefined, { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
+}
 export async function login(ctx) {
     const { out, api, p } = ctx;
-    const existing = readSession(ctx.env, ctx.base);
-    if (existing)
-        forget(ctx, existing);
+    const live = bool(ctx.args, "live");
     const deviceName = str(ctx.args, "device-name") ?? p.hostname() ?? null;
-    const code = (await api.request("/v1/cli/device/code", { method: "POST", body: { device_name: deviceName || null }, retry: true })).data;
+    const code = (await api.request("/v1/cli/device/code", { method: "POST", body: { device_name: deviceName || null, ...(live ? { live: true } : {}) }, retry: true })).data;
     if (out.json) {
-        out.data({ event: "code", userCode: code.user_code, verificationUri: code.verification_uri, verificationUriComplete: code.verification_uri_complete, expiresIn: code.expires_in });
+        out.data({ event: "code", userCode: code.user_code, verificationUri: code.verification_uri, verificationUriComplete: code.verification_uri_complete, expiresIn: code.expires_in, live });
     }
     else {
         out.line(out.wordmark());
         out.line();
+        if (live)
+            out.line(`This sign-in asks for ${out.accent("production read access")} for 12 hours. The console asks you to sign in again first.`);
         out.line(`Your sign-in code is ${out.accent(code.user_code)}`);
         out.line(`Approve it at ${code.verification_uri_complete}`);
         out.line("Check the code matches before you approve.");
@@ -75,6 +79,10 @@ export async function login(ctx) {
 }
 async function finishLogin(ctx, tok) {
     const { out } = ctx;
+    const previous = readSession(ctx.env, ctx.base);
+    const previousToken = previous ? storeOfKind(previous.store, ctx.env, ctx.p.run).get(hostKey(ctx.base)) : null;
+    if (previous)
+        forget(ctx, previous);
     const choice = chooseStore(ctx.env, ctx.p.platform, ctx.p.run);
     let store = choice.store;
     let warning = choice.warning;
@@ -86,13 +94,18 @@ async function finishLogin(ctx, tok) {
         warning = `The ${choice.store.kind} store refused the CLI token, so it is stored in ${file.path} (readable only by you).`;
     }
     const expiresAt = new Date(ctx.p.now() + tok.expires_in * 1000).toISOString();
-    writeSession(ctx.env, ctx.base, { sessionId: tok.session_id, accountId: "", accountName: null, store: store.kind, expiresAt });
+    writeSession(ctx.env, ctx.base, { sessionId: tok.session_id, accountId: "", accountName: null, store: store.kind, expiresAt, liveUntil: tok.live_until ?? null });
     if (warning)
         out.note(warning);
+    if (previousToken?.startsWith("lcli_") && previous?.sessionId !== tok.session_id) {
+        await ctx.api.request("/v1/cli/logout", { method: "POST", body: {}, auth: previousToken, retry: false }).catch(() => undefined);
+    }
     const who = await authed(ctx, "/v1/cli/whoami");
-    writeSession(ctx.env, ctx.base, { sessionId: tok.session_id, accountId: who.account.id, accountName: who.account.name, store: store.kind, expiresAt: who.session.expiresAt });
+    const liveUntil = who.session.liveUntil ?? null;
+    writeSession(ctx.env, ctx.base, { sessionId: tok.session_id, accountId: who.account.id, accountName: who.account.name, store: store.kind, expiresAt: who.session.expiresAt, liveUntil });
     out.result({ event: "signed_in", account: who.account, session: who.session }, () => {
-        out.line(`Signed in to ${who.account.name ?? "your developer account"}. This CLI works in sandbox only.`);
+        out.line(`Signed in to ${who.account.name ?? "your developer account"}.`);
+        out.line(liveUntil ? `Production read access until ${localTime(liveUntil)}. Add --live to a command to use it.` : "Sandbox. Run layout login --live to read production.");
     });
     return EXIT.ok;
 }
@@ -123,7 +136,7 @@ export async function whoami(ctx) {
     ctx.out.result(who, () => {
         ctx.out.line(`${who.account.name ?? "Developer account"} (${who.account.id})`);
         ctx.out.line(`Session ${who.session.deviceName ? `on ${who.session.deviceName}, ` : ""}expires ${who.session.expiresAt.slice(0, 10)}`);
-        ctx.out.line("Sandbox only.");
+        ctx.out.line(who.session.liveUntil ? `Production read access until ${localTime(who.session.liveUntil)}` : "Sandbox. Run layout login --live to read production.");
     });
     return EXIT.ok;
 }

package/dist/commands/test-order.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { str } from "../args.js";
 import { CliError, EXIT, usageError } from "../errors.js";
-import { authed, pickApp } from "../context.js";
+import { dropSandboxSecret, envSecret, pickApp, sandboxSecret, SECRET_ENV } from "../context.js";
 export const EXPECTED = {
     test_place_carted: "placed",
     test_place_placed: "placed",
@@ -26,7 +26,11 @@ export async function testOrder(ctx) {
     const expected = EXPECTED[place];
     if (!expected)
         throw usageError(`test-order runs a test restaurant that builds a cart on its own: ${Object.keys(EXPECTED).join(", ")}.`);
-    const app = await pickApp(ctx);
+    const fromEnv = envSecret(ctx);
+    if (fromEnv?.startsWith("sk_live_"))
+        throw usageError(`test-order runs in sandbox only, and ${SECRET_ENV} is a live secret.`);
+    const app = fromEnv ? null : await pickApp(ctx);
+    const seed = app ?? createHash("sha256").update(fromEnv).digest("hex").slice(0, 16);
     const steps = [];
     const run = `cli-${randomUUID()}`;
     let current = out.spinner("Reading the sandbox key");
@@ -58,15 +62,20 @@ export async function testOrder(ctx) {
             await p.sleep(1_500);
         }
     };
-    const key = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/keys/reveal`, { method: "POST", body: {}, retry: true })
-        .catch((err) => fail("Read the sandbox key", err));
-    done("Read the sandbox key", `${key.clientId}, held in memory for this run`);
-    const sk = key.secret;
+    let sk = fromEnv ?? await sandboxSecret(ctx, app).catch((err) => fail("Read the sandbox key", err));
+    done("Read the sandbox key", fromEnv ? `from ${SECRET_ENV}` : "from this computer's credential store");
     next("Provisioning a sandbox test user");
-    const phone = testPhone(app);
-    const user = await api.request("/v1/users", {
+    const phone = testPhone(seed);
+    const provision = () => api.request("/v1/users", {
         method: "POST", auth: sk, idempotent: true, retry: true, body: { firstName: "Layout", lastName: "CLI test", phone },
-    }).then((r) => r.data).catch((err) => fail("Provision a test user", err));
+    }).then((r) => r.data);
+    const user = await provision().catch(async (err) => {
+        if (!(err instanceof CliError) || err.exit !== EXIT.auth || !app)
+            throw err;
+        dropSandboxSecret(ctx, app);
+        sk = await sandboxSecret(ctx, app, true);
+        return provision();
+    }).catch((err) => fail("Provision a test user", err));
     done("Provision a test user", `${user.id} on ${phone}`);
     if (user.next === "verify") {
         next("Verifying with the sandbox code");

package/dist/context.js

@@ -30,15 +30,57 @@ export function signedIn(ctx) {
     if (!record)
         throw new CliError("not_signed_in", "Not signed in. Run layout login.", EXIT.auth);
     const token = storeOfKind(record.store, ctx.env, ctx.p.run).get(hostKey(ctx.base));
-    if (!token)
+    if (!token?.startsWith("lcli_"))
         throw new CliError("not_signed_in", "Not signed in. Run layout login.", EXIT.auth);
     return { token, record };
 }
 export function forget(ctx, record) {
-    if (record)
-        storeOfKind(record.store, ctx.env, ctx.p.run).remove(hostKey(ctx.base));
+    if (record) {
+        const store = storeOfKind(record.store, ctx.env, ctx.p.run);
+        store.remove(hostKey(ctx.base));
+        for (const app of record.keys ?? [])
+            store.remove(keyAccount(ctx.base, app));
+    }
     writeSession(ctx.env, ctx.base, null);
 }
+const APP_ID = /^lyt_app_[A-Za-z0-9]{1,64}$/;
+function keyAccount(base, app) {
+    return `${hostKey(base)}:sandbox-key:${app}`;
+}
+/** The application's sandbox secret, from this computer's credential store or read once from Layout and kept there. Never a live secret. */
+export async function sandboxSecret(ctx, app, fresh = false) {
+    const s = signedIn(ctx);
+    const store = storeOfKind(s.record.store, ctx.env, ctx.p.run);
+    const cacheable = APP_ID.test(app);
+    if (cacheable && !fresh) {
+        const cached = store.get(keyAccount(ctx.base, app));
+        if (cached?.startsWith("sk_test_"))
+            return cached;
+    }
+    const key = await authed(ctx, `/v1/cli/apps/${encodeURIComponent(app)}/keys/reveal`, { method: "POST", body: {}, retry: true });
+    if (!key.secret?.startsWith("sk_test_"))
+        throw new CliError("unexpected_key", "Layout returned something other than a sandbox key, so it was not used.", EXIT.error);
+    if (cacheable && store.set(keyAccount(ctx.base, app), key.secret)) {
+        const record = readSession(ctx.env, ctx.base);
+        if (record && !(record.keys ?? []).includes(app))
+            writeSession(ctx.env, ctx.base, { ...record, keys: [...(record.keys ?? []), app] });
+    }
+    return key.secret;
+}
+export function dropSandboxSecret(ctx, app) {
+    const record = readSession(ctx.env, ctx.base);
+    if (record)
+        storeOfKind(record.store, ctx.env, ctx.p.run).remove(keyAccount(ctx.base, app));
+}
+export const SECRET_ENV = "LAYOUT_SECRET_KEY";
+export function envSecret(ctx) {
+    const v = ctx.env[SECRET_ENV]?.trim();
+    if (!v)
+        return null;
+    if (!/^sk_(?:test|live)_[A-Za-z0-9_-]{20,128}$/.test(v))
+        throw usageError(`${SECRET_ENV} is not a Layout secret key (sk_test_... or sk_live_...).`);
+    return v;
+}
 export async function authed(ctx, path, opts = {}) {
     const s = signedIn(ctx);
     try {

package/dist/credentials.js

@@ -8,7 +8,7 @@ export const spawnRunner = (cmd, args, input) => {
 };
 const SERVICE = "layout-cli";
 const SAFE = /^[A-Za-z0-9_.:\-[\]]+$/;
-const TOKEN = /^lcli_[A-Za-z0-9_-]{43}$/;
+const TOKEN = /^(?:lcli_[A-Za-z0-9_-]{43}|sk_test_[A-Za-z0-9_-]{20,128})$/;
 export function keychainStore(run) {
     return {
         kind: "keychain",

package/dist/http.js

@@ -34,7 +34,7 @@ export class Api {
     async request(path, opts = {}) {
         const method = opts.method ?? "GET";
         const retry = opts.retry ?? method === "GET";
-        const idemKey = method === "POST" && opts.idempotent ? randomUUID() : null;
+        const idemKey = method === "POST" && (opts.idempotent || opts.idempotencyKey) ? (opts.idempotencyKey ?? randomUUID()) : null;
         const headers = { accept: "application/json", "user-agent": userAgent() };
         if (opts.auth)
             headers.authorization = `Bearer ${opts.auth}`;
@@ -69,6 +69,9 @@ export class Api {
             catch {
                 data = null;
             }
+            const transientStatus = res.status === 503 || res.status === 502 || res.status === 504 || (res.status === 429 && method === "GET");
+            if (opts.anyStatus && !(transientStatus && retry && attempt + 1 < attempts))
+                return { status: res.status, data: data, headers: res.headers };
             if (res.ok || opts.okStatuses?.includes(res.status))
                 return { status: res.status, data: data, headers: res.headers };
             last = errorFrom(res.status, data);

package/dist/listen.js

@@ -13,14 +13,14 @@ function field(payload, key) {
     const v = payload && typeof payload === "object" ? payload[key] : undefined;
     return typeof v === "string" ? v : null;
 }
-export function forwardHeaders(secret, ev, body, nowSec) {
+export function forwardHeaders(secret, ev, body, nowSec, environment = "sandbox") {
     return {
         "content-type": "application/json",
         "user-agent": "Layout-Webhooks/1 (layout-cli)",
         "x-layout-signature": signatureHeader(secret, nowSec, body),
         "x-layout-event": ev.event,
         "x-layout-delivery": field(ev.payload, "delivery_id") ?? ev.cursor,
-        "x-layout-environment": "sandbox",
+        "x-layout-environment": environment,
         "x-layout-forwarded-by": "layout-cli",
     };
 }
@@ -65,7 +65,7 @@ export async function runListener(start, opts, deps) {
                 attempts++;
                 let res;
                 try {
-                    res = await deps.forward(opts.forwardTo, body, forwardHeaders(opts.secret, ev, body, deps.nowSec()));
+                    res = await deps.forward(opts.forwardTo, body, forwardHeaders(opts.secret, ev, body, deps.nowSec(), opts.environment));
                 }
                 catch {
                     res = { ok: false, status: 0 };

package/dist/main.js

@@ -7,26 +7,39 @@ import { login, logout, whoami } from "./commands/session.js";
 import { appsCreate, appsList, deliveries, docs, keysCreate, keysList, keysRevoke, requestLiveAccess, trigger, usage, webhooksList, } from "./commands/resources.js";
 import { listen } from "./commands/listen.js";
 import { testOrder } from "./commands/test-order.js";
+import { api } from "./commands/api.js";
+import { checkForUpdate } from "./update.js";
 const s = (name) => ({ name, type: "string" });
 const b = (name) => ({ name, type: "boolean" });
+const LIVE = ["--live", "Production instead of sandbox. Needs layout login --live; read-only."];
 export const COMMANDS = [
-    { path: ["login"], usage: "layout login [--device-name <name>] [--no-browser]", summary: "Sign in with a code you approve in the console.", flags: [s("device-name"), b("no-browser")],
-        flagHelp: [["--device-name <name>", "What the console shows as the computer asking. Default: this computer's name."], ["--no-browser", "Print the link without opening a browser."]], run: login },
+    { path: ["login"], usage: "layout login [--live] [--device-name <name>] [--no-browser]", summary: "Sign in with a code you approve in the console.", flags: [s("device-name"), b("no-browser"), b("live")],
+        flagHelp: [["--live", "Also read production for 12 hours. The console asks you to sign in again first."], ["--device-name <name>", "What the console shows as the computer asking. Default: this computer's name."], ["--no-browser", "Print the link without opening a browser."]], run: login },
     { path: ["logout"], usage: "layout logout", summary: "Revoke this CLI session and forget it here.", flags: [], run: logout },
     { path: ["whoami"], usage: "layout whoami", summary: "The developer account and this CLI session.", flags: [], run: whoami },
     { path: ["apps", "list"], usage: "layout apps list", summary: "Your applications.", flags: [], run: appsList },
     { path: ["apps", "create"], usage: "layout apps create <name>", summary: "A new application. Prints its sandbox key once.", flags: [], run: appsCreate },
-    { path: ["keys", "list"], usage: "layout keys list", summary: "The application's sandbox key.", flags: [], run: keysList },
+    { path: ["keys", "list"], usage: "layout keys list [--live]", summary: "The application's key: client id and last four.", flags: [b("live")], flagHelp: [LIVE], run: keysList },
     { path: ["keys", "create"], usage: "layout keys create [--replace]", summary: "A new sandbox key, printed once.", flags: [b("replace")],
         flagHelp: [["--replace", "Retire the current sandbox key and make another."]], run: keysCreate },
     { path: ["keys", "revoke"], usage: "layout keys revoke --yes", summary: "Revoke the sandbox key and its sandbox build grants.", flags: [b("yes")],
         flagHelp: [["--yes", "Confirm. Nothing is revoked without it."]], run: keysRevoke },
-    { path: ["webhooks", "list"], usage: "layout webhooks list", summary: "Endpoints (managed in the console) and the sandbox signing secret.", flags: [], run: webhooksList },
-    { path: ["listen"], usage: "layout listen --forward-to <url> [--events <a,b>] [--from-start]", summary: "Forward sandbox events to a local URL.", flags: [s("forward-to"), s("events"), b("from-start")],
-        flagHelp: [["--forward-to <url>", "Where to POST each event, signed with a secret made for this run."], ["--events <a,b>", "Only these events."], ["--from-start", "Forward the whole feed, not only what happens from now."]], run: listen },
+    { path: ["webhooks", "list"], usage: "layout webhooks list [--live]", summary: "Endpoints (managed in the console) and the sandbox signing secret.", flags: [b("live")], flagHelp: [LIVE], run: webhooksList },
+    { path: ["listen"], usage: "layout listen --forward-to <url> [--events <a,b>] [--from-start] [--live]", summary: "Forward events to a local URL.", flags: [s("forward-to"), s("events"), b("from-start"), b("live")],
+        flagHelp: [["--forward-to <url>", "Where to POST each event, signed with a secret made for this run."], ["--events <a,b>", "Only these events."], ["--from-start", "Forward the whole feed, not only what happens from now."], LIVE], run: listen },
     { path: ["trigger"], usage: "layout trigger <event> [--order <ord_id>]", summary: "Fire a signed test event at your endpoints.", flags: [s("order")], run: trigger },
     { path: ["usage"], usage: "layout usage", summary: "Today's allowances and counts.", flags: [], run: usage },
-    { path: ["deliveries"], usage: "layout deliveries [--limit <n>]", summary: "Recent sandbox webhook deliveries.", flags: [s("limit")], run: deliveries },
+    { path: ["deliveries"], usage: "layout deliveries [--limit <n>] [--live]", summary: "Recent webhook deliveries.", flags: [s("limit"), b("live")],
+        flagHelp: [["--limit <n>", "1 to 100. Default 20."], LIVE], run: deliveries },
+    { path: ["api"], usage: "layout api <get|post|delete> <path> [-d name=value]... [--data <json|@file>] [--live]", summary: "Call any REST endpoint with your key and print the answer.",
+        flags: [{ name: "field", type: "list", short: "d" }, s("data"), s("token"), s("idempotency-key"), b("live")],
+        flagHelp: [
+            ["-d name=value", "A body field; repeat it. JSON values (numbers, true, arrays) are kept as JSON."],
+            ["--data <json|@file>", "The whole body as a JSON object."],
+            ["--token <token>", "Send this bearer instead, such as a build grant (lgb_) or an OAuth access token."],
+            ["--idempotency-key <key>", "Default: a new one for each POST."],
+            ["--live", `Production, GET only, with your own sk_live_ in LAYOUT_SECRET_KEY.`],
+        ], run: api },
     { path: ["test-order"], usage: "layout test-order [--place <test_place_id>]", summary: "Run a whole sandbox order and print each step.", flags: [s("place")],
         flagHelp: [["--place <id>", "A sandbox test restaurant. Default: test_place_placed."]], run: testOrder },
     { path: ["request-live-access"], usage: "layout request-live-access [--note <text>]", summary: "Ask Layout to review production access.", flags: [s("note")], run: requestLiveAccess },
@@ -75,7 +88,7 @@ function help(o, cmd, sub) {
     const list = sub.length ? sub : COMMANDS;
     o.line(o.wordmark());
     o.line();
-    o.line("Sign in, then build against the Layout sandbox. Never touches production.");
+    o.line("Build against the Layout sandbox, and read production with --live. The CLI never changes production or moves money.");
     o.line();
     o.line("Commands:");
     for (const l of pad(list.map((c) => [c.path.join(" "), c.summary])))
@@ -85,11 +98,26 @@ function help(o, cmd, sub) {
     for (const l of pad([...GLOBAL_HELP]))
         o.line(l);
     o.line();
+    o.line("Environment:");
+    for (const l of pad([["LAYOUT_SECRET_KEY", "A key for api and test-order without signing in, as in CI."], ["LAYOUT_APP", "The application, instead of --app."], ["NO_COLOR", "No colour."]]))
+        o.line(l);
+    o.line();
     o.line("Docs: https://developer.layout.link/reference/cli");
 }
 export async function main(argv, p) {
     const json = argv.includes("--json");
     const fallback = new Output(p.streams, json);
+    const update = json ? null : checkForUpdate(p);
+    try {
+        return await dispatch(argv, p, json, fallback);
+    }
+    finally {
+        const notice = update ? await update : null;
+        if (notice)
+            fallback.note(notice);
+    }
+}
+async function dispatch(argv, p, json, fallback) {
     try {
         const loose = parseArgs(argv, COMMANDS.flatMap((c) => c.flags));
         const positionals = loose.positionals;
@@ -113,7 +141,7 @@ export async function main(argv, p) {
             return EXIT.ok;
         }
         const extra = args.positionals.slice(cmd.path.length);
-        const takesArgs = ["apps create", "trigger", "docs"].includes(cmd.path.join(" "));
+        const takesArgs = ["apps create", "trigger", "docs", "api"].includes(cmd.path.join(" "));
         if (!takesArgs && extra.length > 0)
             throw usageError(`Unexpected argument: ${extra[0]}. Run layout ${cmd.path.join(" ")} --help.`);
         return await cmd.run(makeCtx(p, args));

package/dist/update.js

@@ -0,0 +1,38 @@
+import { join } from "node:path";
+import { configDir, readJson, writePrivateJson } from "./config.js";
+import { VERSION } from "./version.js";
+const REGISTRY = "https://registry.npmjs.org/@layoutplatforms/cli/latest";
+const EVERY_MS = 24 * 60 * 60 * 1000;
+const WAIT_MS = 1_500;
+export function newer(latest, current) {
+    const parse = (v) => v.split("-")[0].split(".").map((n) => Number(n));
+    const a = parse(latest);
+    const b = parse(current);
+    if (a.length !== 3 || b.length !== 3 || [...a, ...b].some((n) => !Number.isInteger(n) || n < 0))
+        return false;
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    return false;
+}
+/** One quiet look a day at npm for a newer CLI, on a terminal only. Never delays a command by more than its own wait, and never fails one. */
+export async function checkForUpdate(p) {
+    try {
+        const env = p.streams.env;
+        if (!p.streams.err.isTTY || env.CI || env.LAYOUT_NO_UPDATE_CHECK)
+            return null;
+        const file = join(configDir(env), "update-check.json");
+        const cached = readJson(file);
+        let latest = cached?.latest ?? null;
+        if (!cached?.checkedAt || p.now() - cached.checkedAt > EVERY_MS) {
+            const res = await p.http.fetch(REGISTRY, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(WAIT_MS), redirect: "error" });
+            const body = res.ok ? (await res.json()) : null;
+            latest = typeof body?.version === "string" ? body.version : latest;
+            writePrivateJson(file, { checkedAt: p.now(), latest });
+        }
+        return latest && newer(latest, VERSION) ? `Layout CLI ${latest} is out (you have ${VERSION}). Update: npm i -g @layoutplatforms/cli` : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.1";
+export const VERSION = "0.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layoutplatforms/cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": false,
   "description": "The Layout developer CLI: sign in, sandbox apps and keys, forward webhooks, run test orders.",
   "type": "module",