@pitcher/cli-scripts 2.18.0 → 2.20.0

package/README.md

@@ -12,7 +12,7 @@ p command --help
 
 ## MCP server
 
-Run `p mcp` to start a stdio [MCP](https://modelcontextprotocol.io) server that exposes this CLI's commands as tools to an MCP-capable host (Claude Desktop, Claude Code, etc). It wraps 123 tools, one per CLI `run*` function: every command above (including `dsr create`/`update`/`delete`/`bind-landing` and the full `ld` surface) except the five local `scaffold` subcommands (which just print/write a starter file and make no request). `dev-sync` is exposed as a one-shot sync only; the continuous `watch` mode is not available as a tool.
+Run `p mcp` to start a stdio [MCP](https://modelcontextprotocol.io) server that exposes this CLI's commands as tools to an MCP-capable host (Claude Desktop, Claude Code, etc). It wraps one tool per CLI `run*` function: every command below (including `dsr create`/`get`/`update`/`delete`/`bind-landing` and the full `ld` surface) except the five local `scaffold` subcommands (which just print/write a starter file and make no request). `dev-sync` is exposed as a one-shot sync only; the continuous `watch` mode is not available as a tool.
 
 ```bash
 p mcp
@@ -26,7 +26,7 @@ Auth and org scope are resolved once at boot from environment variables. They ar
 
 - `NG_API_KEY` (required, secret): the API key the server authenticates as.
 - `NG_ORG` (default `dev`): organization subdomain, or set `NG_URL` directly for a full origin.
-- `NG_ENV` (`prod` or `test`): controls the destructive-hint guard on write tools (see below). Defaults to a guess based on `NG_ORG` when unset.
+- `NG_ENV` (`prod` or `test`): controls the destructive-hint guard on write tools (see below). When unset, anything other than the `dev` org (or, if `NG_URL` is set, anything other than `https://dev.my.pitcher.com`) is treated as production.
 
 One config entry = one org, because the API key is org-specific. To work against multiple orgs, add multiple entries (e.g. `pitcher-dev`, `pitcher-prod`) with different env blocks; do not try to pass org per tool call.
 
@@ -43,7 +43,7 @@ One config entry = one org, because the API key is org-specific. To work against
 ### Tool annotations
 
 - Read commands are marked `readOnlyHint`. `dev-sync` counts as a write (it mutates remote dev-override state).
-- `publish-app` is always marked `destructiveHint` (it creates a live, org-visible release). Other write tools get `destructiveHint` only when the resolved environment is production (`NG_ENV=prod`, or `NG_ORG` other than `dev` with `NG_ENV` unset). This steers hosts toward requiring extra confirmation before mutating a production org.
+- `publish-app` is always marked `destructiveHint` (it creates a live, org-visible release). Other write tools get `destructiveHint` only when the resolved environment is production (`NG_ENV=prod`, or — with `NG_ENV` unset — a target other than `dev` / `dev.my.pitcher.com`). This steers hosts toward requiring extra confirmation before mutating a production org.
 
 ### Desktop Extension (`.mcpb`)
 
@@ -55,7 +55,7 @@ yarn mcpb:pack        # → pitcher.mcpb (validated + packed)
 
 Install by double-clicking `pitcher.mcpb` (or Settings → Extensions → Install Extension). Claude Desktop prompts for the API key (stored in the OS keychain) and organization; both are editable afterward, so switching orgs needs no reinstall.
 
-The bundle reuses the same server as `p mcp` but registers a **content-tool subset (120)** — it omits the developer-only `publish-app` and `dev-sync`/`dev-sync-revert`. The `organization` field accepts a subdomain (`acme`), a bare hostname (`acme.my.pitcher.com`), or a full `https://` URL. Build details (esbuild single-file, version injection) live in `mcpb/` and `CLAUDE.md`.
+The bundle reuses the same server as `p mcp` but registers a **content-tool subset (121)** — it omits the developer-only `publish-app` and `dev-sync`/`dev-sync-revert`. The `organization` field accepts a subdomain (`acme`), a bare hostname (`acme.my.pitcher.com`), or a full `https://` URL. Build details (esbuild single-file, version injection) live in `mcpb/` and `CLAUDE.md`.
 
 This section is a reference only. For app-development conventions (modules, settings, mount points, SFDC), see the `pitcher-apps` skill, not this README.
 
@@ -63,7 +63,7 @@ This section is a reference only. For app-development conventions (modules, sett
 
 ```bash
 # Basic usage
-p publish-app <folder> --url https://pitcher.my.pitcher.com --api-key myapikey
+p publish-app <folder> --org pitcher --api-key myapikey
 
 # Publish to current folder and default org (dev)
 p publish-app --api-key myapikey
@@ -506,7 +506,7 @@ p metadata-template upsert --instance-id 01... --sections-file ./schema.json --a
 
 ## To run the `dsr` command:
 
-Create and share a Digital Sales Room (a canvas share link) and get a link back in one command. Five subcommands: `create` (build + share, with optional landing-page binding), `update` (change or clear the access settings of an existing share), `delete` (revoke a share), `bind-landing` (bind/unbind a landing template on an existing share), and `scaffold` (print a starter `{source,security,landing}` spec for `--config-file`).
+Create and share a Digital Sales Room (a canvas share link) and get a link back in one command. Six subcommands: `create` (build + share, with optional landing-page binding), `get` (read an existing share back), `update` (change or clear the access settings of an existing share), `delete` (revoke a share), `bind-landing` (bind/unbind a landing template on an existing share), and `scaffold` (print a starter `{source,security,landing}` spec for `--config-file`).
 
 The create endpoint is a **get-or-create**: sharing an already-shared canvas returns the existing link and updates only the fields you pass. That is deliberate (it mirrors Admin's "Create link once / Copy link after"), but it means `create` with individual flags can never *remove* a value — omitting a flag leaves the stored value alone. Use `update` for that, and `--clear <field>` to remove one.
 
@@ -519,11 +519,16 @@ p dsr create --instance-id 01... --canvas-id 01... --api-key myapikey
 p dsr create --instance-id 01... --canvas-id 01... --auth-strategy none
 # ShareBox + security + branded landing
 p dsr create --instance-id 01... --sharebox-file-ids 01A,01B --account-id 01... \
-  --auth-strategy specified_domains --allowed-domains acme.com --valid-until 2026-09-01T00:00:00Z \
+  --auth-strategy specified_domains --allowed-domains acme.com --valid-until 2026-12-01T00:00:00Z \
   --landing-template-id 01... --landing-context '{"rep":"Sam"}'
 # bind/unbind a landing template on an existing share
 p dsr bind-landing --id 01... --instance-id 01... --landing-template-id 01...
 p dsr bind-landing --id 01... --instance-id 01... --landing-template-id none
+# merge fields from a FILE instead of inline JSON (the only spelling that works in PowerShell)
+p dsr bind-landing --id 01... --instance-id 01... --landing-template-id 01... --landing-context-file ./ctx.json
+p dsr create --instance-id 01... --canvas-id 01... --landing-template-id 01... --landing-context-file ./ctx.json
+# read an existing share back
+p dsr get --id 01...
 # refuse to reuse an existing share instead of silently returning it
 p dsr create --canvas-id 01... --if-exists error
 # send the download preference explicitly — either direction
@@ -545,7 +550,11 @@ p dsr scaffold --out share.json
 
 `p dsr scaffold` prints the starter. The spec has three blocks — `source`, `security`, `landing` — and the CLI sends `source` and `security` **spread verbatim into the create POST body**, so their keys are the wire (snake_case) names, not flag names. `landing` is not part of that body: it becomes a follow-up PUT to `/{id}/landing-page` after the share exists.
 
-The `source` block picks what is shared:
+The `source` block picks what is shared. The scaffold emits `canvas_id` (an example value) **and** an empty `sharebox_items: []`, so both source keys are visible in the printed JSON; an empty array asks for nothing, so the untouched scaffold shares `canvas_id`. To share files instead, fill `sharebox_items`, delete the `canvas_id` line, and add `instance_id` (or pass `--instance-id`). `p dsr create --help` lists the same field names.
+
+```json
+"source": { "instance_id": "01...", "sharebox_items": [{ "file_id": "01..." }, { "file_id": "01...", "page_index": 2 }] }
+```
 
 | Key | Type | Meaning |
 |-----|------|---------|
@@ -558,7 +567,7 @@ The `source` block picks what is shared:
 
 `canvas_name`, `account_id`, `template_id` and `security.tags` name or shape the canvas the server **mints**, so they only mean anything for a `sharebox_items` source — with `canvas_id` the canvas already exists and there is nothing to name. `tags` is the one the CLI enforces: a non-empty `tags` alongside `canvas_id` is rejected rather than sent to be dropped. The scaffold's empty `tags: []` is accepted, since it asks for nothing.
 
-`security` holds the access settings (`auth_strategy`, `allowed_emails`, `allowed_domains`, `valid_until`, `allow_forward`, `allow_download`, `tags`) and every key in it is spread into the POST body **exactly as written**. The CLI checks three of them and no more: `auth_strategy` against the allowed values, the `allowed_emails`/`allowed_domains` that strategy requires, and `tags` (above). The rest — `allow_download` included — it forwards untouched and makes no claim about, so read the created share back if you need to confirm a value took. Sending the block as written also matters against an already-shared canvas — see the `--if-exists` note above. `landing` holds `landing_page_template_id` (discover ids with `p dsr-landing list`) and `landing_page_context`; left at the scaffold's `null` / `{}` no landing page is bound at all. Binding one — from the spec or from `--landing-template-id` — needs an instance: `--instance-id` or `source.instance_id`. Without it the CLI skips the bind and returns the share with a warning naming the flag.
+`security` holds the access settings (`auth_strategy`, `allowed_emails`, `allowed_domains`, `valid_until`, `allow_forward`, `allow_download`, `tags`) and every key in it is spread into the POST body **exactly as written**. The CLI checks three of them and no more: `auth_strategy` against the allowed values, the `allowed_emails`/`allowed_domains` that strategy requires, and `tags` (above). The rest — `allow_download` included — it forwards untouched and makes no claim about, so read the created share back if you need to confirm a value took. The scaffold deliberately **omits** `allow_download`: it is stored on the canvas (every link on that canvas reads it), and the server writes it only when the key is present — omitted, an existing canvas keeps its current value and a new ShareBox canvas carries none, which the viewer treats as **downloads allowed**. Add `"allow_download": false` to the spec to turn downloads off. Sending the block as written also matters against an already-shared canvas — see the `--if-exists` note above. `landing` holds `landing_page_template_id` (discover ids with `p dsr-landing list`) and `landing_page_context`; left at the scaffold's `null` / `{}` no landing page is bound at all. Binding one — from the spec or from `--landing-template-id` — needs an instance: `--instance-id` or `source.instance_id`. Without it the CLI skips the bind and returns the share with a warning naming the flag.
 
 `update` PATCHes `/core/api/protected/shared-links/{id}`, which distinguishes an **absent** key from an **explicit null** — so omitting `--valid-until` leaves the stored expiry exactly as it is, and `--clear valid-until` is what resets it. `--clear` is repeatable and accepts `valid-until`, `allowed-emails`, `allowed-domains` (the CLI sends `null` for the first and `[]` for the lists, matching what each field's server schema accepts). An empty `--allowed-emails`/`--allowed-domains` is rejected on both `create` and `update`, because `""` from an unset shell variable would otherwise be sent as `[]` and wipe the stored list. `--clear` is a separate flag rather than an in-value sentinel such as `--valid-until ""` because an empty string is something a script can produce by accident from an unset variable, and `none` is already a real `--auth-strategy` value. `tags` and `--allow-download` are **create-time only** — the PATCH surface does not accept them, and `--clear` says so rather than dropping them silently.
 
@@ -573,9 +582,35 @@ p dsr update --id 01... --auth-strategy any_email --clear allowed-emails
 p dsr update --id 01... --allowed-emails new@acme.com
 ```
 
+### `--landing-context` from a file
+
+`--landing-context` takes a JSON object as a single shell argument, which **PowerShell cannot express**: it strips the double quotes a JSON object cannot do without, so on Windows the flag has no usable spelling at all. `--landing-context-file <path>` is the same field read off disk, and it is available on **both** `dsr create` and `dsr bind-landing`:
+
+```bash
+echo '{"rep":"Sam","account":"Acme"}' > ctx.json
+p dsr bind-landing --id 01... --instance-id 01... --landing-template-id 01... --landing-context-file ./ctx.json
+```
+
+Exactly one of the two may be given: passing **both** fails `VALIDATION` (exit 3) before any request, naming the pair. The file must hold a JSON **object** — valid JSON that is an array or a scalar is rejected with the same code, as is malformed JSON. `--landing-context-file` is a landing flag like the rest, so it is mutually exclusive with `--config-file` (whose `landing.landing_page_context` block is that spec's own way of saying the same thing).
+
+### `p dsr get` — read a share back
+
+`p dsr get --id <id>` returns the share's current settings. The protected shared-links surface has **no GET**, so this wraps the public pre-auth config the sharing page itself loads (`GET /core/api/shared-links/{id}/config`) and returns that body **unchanged**. Nothing is reshaped, so the field names are the wire names.
+
+That body is the share's **access config**, and nothing else: `auth_strategy`, `allowed_domains`, `allowed_emails`, `valid_until`, `allow_forward` (plus `allow_forward_raw`, the rep's own toggle before the admin `allow_dsr_forwarding` setting is applied), the landing-page binding as `landing_page_template_id` / `landing_page_template_snapshot` / `landing_page_context`, and `created_at` / `modified_at`. **There is no `canvas` or `file` field** — the endpoint selects neither, so hold on to the `canvas` that `create` returned if you need it.
+
+```bash
+p dsr get --id 01...
+# confirm what a create actually stored
+p dsr create --instance-id 01... --canvas-id 01... --auth-strategy specified_domains --allowed-domains acme.com
+p dsr get --id 01...
+```
+
+Use it to confirm what `create` or `update` stored (`create` is a get-or-create, so what you passed is not always what the share ends up with) and to check a link before changing it. There is **one** id failure mode: any id that matches no share answers `404` → `NOT_FOUND` (exit 5). The endpoint does not validate the id's format — it matches `pitcher_sharedlink.id`, a plain varchar — so a malformed id is a miss like any other and returns `NOT_FOUND` too, not `VALIDATION`.
+
 `create` returns the share as `{ id, type, file, canvas, instance, organization, status, url, short_url }` — **`url` is the full link; there is no `full_url` field.**
 
-Creating, updating and deleting need a share-capable key (`canvas.share` on the link's own instance when `enable_granular_permissions` is on); **binding a landing page** needs `--instance-id`, and an admin or editor key to bind any share in the org — a member key can bind only the shares that member created (PIT-7525). On `create`, a denied bind returns the link with a warning. Discover landing template IDs via `p dsr-landing list`.
+`get` reads a public, pre-auth endpoint, so it needs no special permission beyond a valid key. Creating, updating and deleting need a share-capable key (`canvas.share` on the link's own instance when `enable_granular_permissions` is on); **binding a landing page** needs `--instance-id`, and an admin or editor key to bind any share in the org — a member key can bind only the shares that member created (PIT-7525). On `create`, a denied bind returns the link with a warning. Sending `--allow-download` / `--no-allow-download` (or `allow_download` in a spec) with an existing `--canvas-id` needs you to own that canvas or hold `canvas.update` on it — the setting is stored on the canvas — otherwise the create is refused as `AUTH` and nothing is written; a ShareBox source is always yours, so it never hits this. Discover landing template IDs via `p dsr-landing list`.
 
 ## To run the `ld` command:
 

package/dist/src/commands/analytics.d.ts

@@ -22,7 +22,9 @@ export interface AnalyticsKpiOpts extends CommonOpts {
  * org/instance rollups (Django), this hits `clickhouse.pitcher.com` with the
  * org api-key; the caller inherits the key user's real role. Dates are required
  * by the server for activity-metric types (inventory counts like
- * `total-members` need none) — that validation stays server-side.
+ * `total-members` need none) — that validation stays server-side, as does the
+ * set of valid `type` values (a bad one comes back as a 400 listing them). There
+ * is no aggregate `all` type, so `--type` is required.
  */
 export declare function runAnalyticsKpi(opts: AnalyticsKpiOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
 export interface AnalyticsEngagementOpts extends CommonOpts {

package/dist/src/commands/analytics.js

@@ -32,16 +32,20 @@ export async function runAnalyticsInstance(opts, deps = {}) {
  * org/instance rollups (Django), this hits `clickhouse.pitcher.com` with the
  * org api-key; the caller inherits the key user's real role. Dates are required
  * by the server for activity-metric types (inventory counts like
- * `total-members` need none) — that validation stays server-side.
+ * `total-members` need none) — that validation stays server-side, as does the
+ * set of valid `type` values (a bad one comes back as a 400 listing them). There
+ * is no aggregate `all` type, so `--type` is required.
  */
 export async function runAnalyticsKpi(opts, deps = {}) {
     try {
         if (!opts.instanceId)
             throw createCliError('VALIDATION', '--instance-id is required for analytics kpi');
+        if (!opts.type)
+            throw createCliError('VALIDATION', '--type is required for analytics kpi');
         const client = clickhouseClientFor(opts, deps);
         const params = {
             instance_id: opts.instanceId,
-            type: opts.type || 'all',
+            type: opts.type,
         };
         if (opts.startDate)
             params.start_date = opts.startDate;
@@ -376,7 +380,7 @@ export function createAnalyticsCommand() {
     });
     withAuthFlags(cmd.command('kpi'))
         .option('--instance-id <id>', 'Instance ID (required)')
-        .option('--type <type>', "KPI type, e.g. total-members, total-active-users (default 'all')")
+        .option('--type <type>', 'KPI type, e.g. total-members, total-active-users (required)')
         .option('--start-date <iso>', 'Window start (ISO date; required by the server for activity metrics)')
         .option('--end-date <iso>', 'Window end (ISO date; required by the server for activity metrics)')
         .option('--group-ids <csv>', 'Comma-separated distribution-group IDs to scope by')

package/dist/src/commands/devSync.d.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import type { AxiosInstance } from 'axios';
+import { type Credential } from '../core/credential.js';
 import { type Envelope } from '../core/envelope.js';
 interface AppJson {
     name: string;
@@ -17,6 +18,7 @@ interface SyncResponse {
 interface DevSyncOptions {
     fileId: string;
     apiKey?: string;
+    credential?: Credential;
     org?: string;
     quiet?: boolean;
     output?: string;

package/dist/src/commands/devSync.js

@@ -3,7 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import FormData from 'form-data';
 import chokidar from 'chokidar';
-import { resolveApiKey } from '../core/auth.js';
+import { credentialOf } from '../core/credential.js';
 import { resolveBaseUrl } from '../core/baseUrl.js';
 import { makeClient, toCliError } from '../core/http.js';
 import { zipDirectoryToBuffer } from '../core/archive.js';
@@ -32,11 +32,11 @@ export function readAppJson(distPath) {
 }
 export async function runDevSync(opts, deps = {}) {
     try {
-        const apiKey = resolveApiKey(opts);
+        const cred = credentialOf(opts);
         const baseUrl = resolveBaseUrl(opts);
         const distPath = findDistPath(deps.cwd);
         const appJson = readAppJson(distPath);
-        const client = deps.client ?? makeClient(baseUrl, apiKey);
+        const client = deps.client ?? makeClient(baseUrl, cred);
         log(`Syncing ${appJson.name} from ${distPath}...`, { quiet: opts.quiet });
         const zip = await zipDirectoryToBuffer(distPath);
         log(`Zip created: ${(zip.length / 1024).toFixed(2)} KB`, { quiet: opts.quiet });
@@ -57,9 +57,9 @@ export async function runDevSync(opts, deps = {}) {
 }
 export async function runRevert(opts, deps = {}) {
     try {
-        const apiKey = resolveApiKey(opts);
+        const cred = credentialOf(opts);
         const baseUrl = resolveBaseUrl(opts);
-        const client = deps.client ?? makeClient(baseUrl, apiKey);
+        const client = deps.client ?? makeClient(baseUrl, cred);
         const res = await client.delete(SYNC_ENDPOINT, {
             headers: { 'Content-Type': 'application/json' },
             data: { file_id: opts.fileId },

package/dist/src/commands/dsr.d.ts

@@ -12,6 +12,7 @@ export declare function runDsrBindLanding(opts: CommonOpts & {
     id?: string;
     landingTemplateId?: string;
     landingContext?: string;
+    landingContextFile?: string;
     instanceId?: string;
 }, deps?: DsrDeps): Promise<Envelope<unknown>>;
 export interface DsrCreateOpts extends CommonOpts {
@@ -30,6 +31,7 @@ export interface DsrCreateOpts extends CommonOpts {
     tags?: string[];
     landingTemplateId?: string;
     landingContext?: string;
+    landingContextFile?: string;
     configFile?: string;
     ifExists?: string;
 }
@@ -48,6 +50,9 @@ export interface DsrUpdateOpts extends CommonOpts {
     allowForward?: boolean;
     clear?: string[];
 }
+export declare function runDsrGet(opts: CommonOpts & {
+    id?: string;
+}, deps?: DsrDeps): Promise<Envelope<unknown>>;
 export declare function assembleUpdateBody(opts: DsrUpdateOpts): Record<string, unknown>;
 export declare function runDsrUpdate(opts: DsrUpdateOpts, deps?: DsrDeps): Promise<Envelope<unknown>>;
 export declare function runDsrDelete(opts: CommonOpts & {

package/dist/src/commands/dsr.js

@@ -4,7 +4,7 @@ import { ok, fail } from '../core/envelope.js';
 import { createCliError } from '../core/errors.js';
 import { emitEnvelope } from '../core/output.js';
 import { parseJsonObject, parseTags, isPlainObject } from '../schema/content.js';
-import { readTextFile } from '../core/readInput.js';
+import { readTextFile, parseJsonInput } from '../core/readInput.js';
 import { withAuthFlags } from './withAuth.js';
 import { emitScaffold, DSR_SHARE_SCAFFOLD_JSON } from './scaffolds.js';
 const ENDPOINT = '/core/api/protected/shared-links';
@@ -19,6 +19,46 @@ function resolveTemplateId(raw) {
         return null;
     return raw;
 }
+// ── landing context: inline OR file (PIT-7521 QA Q2) ────────────────────────
+// `--landing-context` is a JSON object passed as a shell argument, which PowerShell mangles — it
+// eats the double quotes a JSON object cannot do without, so on Windows the flag has no usable
+// spelling at all. `--landing-context-file` is the way in: same field, read off disk, no quoting.
+//
+// The exclusion check is PRESENCE-based (`!== undefined`), not truthiness, and it runs BEFORE
+// `parseJsonInput`: that helper's own XOR (`resolveTextInput`) is truthy-based, so it would let
+// `--landing-context '' --landing-context-file ctx.json` through and silently read the file. Same
+// reasoning as `metadata-template`'s `--sections` / `--sections-file` pair.
+function resolveLandingContext(inline, file) {
+    if (inline !== undefined && file !== undefined)
+        throw createCliError('VALIDATION', 'pass exactly one of --landing-context or --landing-context-file');
+    if (inline === undefined && file === undefined)
+        return undefined;
+    // Exactly one flag is present from here on. An EMPTY string for either flag still short-circuits
+    // inside `resolveTextInput`, whose XOR is truthy-based, so `parseJsonInput` would answer `provide
+    // --landing-context (inline JSON) or --landing-context-file` -- naming the flag the caller just
+    // passed. That is the wrong advice for the accident this command family documents: `--flag "$MAYBE_UNSET"`
+    // expanding to an empty string is why `--clear` exists. Name the real problem instead. The
+    // genuinely-neither case is returned above and never reaches here, so it keeps that message.
+    if (inline === '')
+        throw createCliError('VALIDATION', '--landing-context must be valid JSON');
+    if (file === '')
+        throw createCliError('VALIDATION', '--landing-context-file requires a file path');
+    const parsed = parseJsonInput(inline, file, 'landing-context');
+    if (!isPlainObject(parsed))
+        throw createCliError('VALIDATION', '--landing-context must be a JSON object');
+    return parsed;
+}
+// The protected shared-links surface has NO GET — the only readback the platform offers is the
+// PUBLIC pre-auth config the sharing page itself reads. Both callers go through this one function
+// so the URL, the encoding and the error mapping have a single definition: `dsr get`, which returns
+// the body as-is, and `dsr update`'s stored-strategy lookup, which swallows the failure.
+function shareConfigUrl(id) {
+    return `/core/api/shared-links/${encodeURIComponent(id)}/config`;
+}
+async function fetchShareConfig(client, id) {
+    const res = await client.get(shareConfigUrl(id));
+    return res.data;
+}
 // The landing-page PUT is guarded by next-core's `withAtLeastInstanceAdmin`, which resolves the
 // instance from the URL path, then the request body, then the `instance_id` query param. This route
 // has no instance in its path and the body the CLI sends carries only the landing fields, so the
@@ -45,8 +85,9 @@ export async function runDsrBindLanding(opts, deps = {}) {
         if (!opts.instanceId)
             throw createCliError('VALIDATION', LANDING_INSTANCE_REQUIRED);
         const body = { landing_page_template_id: templateId };
-        if (opts.landingContext !== undefined)
-            body.landing_page_context = parseJsonObject(opts.landingContext, 'landing-context');
+        const context = resolveLandingContext(opts.landingContext, opts.landingContextFile);
+        if (context !== undefined)
+            body.landing_page_context = context;
         const client = clientFor(opts, deps);
         const data = await bindLandingRequest(client, opts.id, body, opts.instanceId);
         return ok(data);
@@ -61,6 +102,7 @@ const AUTH_STRATEGIES = [
 const SPEC_FLAG_KEYS = [
     'canvasId', 'shareboxFileIds', 'canvasName', 'accountId', 'templateId', 'authStrategy', 'allowedEmails',
     'allowedDomains', 'validUntil', 'allowForward', 'allowDownload', 'tags', 'landingTemplateId', 'landingContext',
+    'landingContextFile',
 ];
 // config-file blocks must be JSON objects — a bare cast would silently spread a string/array into the request body
 function requirePlainObjectField(v, field) {
@@ -118,9 +160,9 @@ function assertCreateBody(body, instanceId) {
     const items = body.sharebox_items;
     const hasSharebox = Array.isArray(items) && items.length > 0;
     if (hasCanvas === hasSharebox)
-        throw createCliError('VALIDATION', 'pass exactly one source: --canvas-id or --sharebox-file-ids');
+        throw createCliError('VALIDATION', 'pass exactly one source: --canvas-id or --sharebox-file-ids (in a --config-file spec: source.canvas_id or a non-empty source.sharebox_items)');
     if (hasSharebox && !instanceId && body.instance_id === undefined)
-        throw createCliError('VALIDATION', '--instance-id is required for --sharebox-file-ids');
+        throw createCliError('VALIDATION', '--instance-id is required for --sharebox-file-ids (in a --config-file spec: --instance-id or source.instance_id)');
     const tags = body.tags;
     // SHAPE first: a hand-written spec can put anything under `security.tags`. The server would refuse a
     // malformed value too (its ZodError catch answers `400 Invalid request data`), so this is not closing
@@ -181,11 +223,14 @@ function resolveLandingBody(opts, cfgLanding) {
         }
         return b;
     }
-    if (opts.landingTemplateId === undefined && opts.landingContext === undefined)
+    // resolved FIRST so `--landing-context X --landing-context-file Y` names the real mistake
+    // rather than being masked by the missing-template-id error below
+    const context = resolveLandingContext(opts.landingContext, opts.landingContextFile);
+    if (opts.landingTemplateId === undefined && context === undefined)
         return null;
     const b = { landing_page_template_id: requireCreateTemplateId(opts.landingTemplateId) };
-    if (opts.landingContext !== undefined)
-        b.landing_page_context = parseJsonObject(opts.landingContext, 'landing-context');
+    if (context !== undefined)
+        b.landing_page_context = context;
     return b;
 }
 // ── create collision policy (PIT-7521) ──────────────────────────────────────
@@ -369,14 +414,37 @@ function clearedListFields(body) {
 // that is a warning here and a hard failure in the --if-exists preflight.
 async function readStoredAuthStrategy(client, id) {
     try {
-        const res = await client.get(`/core/api/shared-links/${encodeURIComponent(id)}/config`);
-        const strategy = res.data?.auth_strategy;
+        const data = (await fetchShareConfig(client, id));
+        const strategy = data?.auth_strategy;
         return typeof strategy === 'string' ? strategy : null;
     }
     catch {
         return null;
     }
 }
+// ── read a share back (PIT-7521 QA Q5) ──────────────────────────────────────
+// The only readback the platform offers. The body is returned verbatim — the CLI reshapes nothing,
+// so what the caller sees is exactly what the sharing page is served: the ACCESS CONFIG only —
+// auth_strategy, allowed_emails / allowed_domains, valid_until, allow_forward (+ allow_forward_raw,
+// the rep's own toggle before the admin setting is applied), the landing binding
+// (landing_page_template_id / _snapshot / landing_page_context) and created_at / modified_at.
+// There is NO canvas or file field: the route selects none (see next-core
+// `src/app/api/shared-links/[id]/config/route.ts`), so use the id from `dsr create` for those.
+//
+// ONE id failure mode, not two. The route has no id validation and no 400 path: it matches
+// `pitcher_sharedlink.id` (a varchar) and answers 404 on zero rows, so ANY id that does not match
+// a share — malformed or merely unknown — comes back 404 → NOT_FOUND via `toCliError`.
+export async function runDsrGet(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required for dsr get');
+        const client = clientFor(opts, deps);
+        return ok(await fetchShareConfig(client, opts.id));
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
 export function assembleUpdateBody(opts) {
     const cleared = normalizeClearFields(opts.clear);
     assertNoEmptyLists(opts);
@@ -449,8 +517,40 @@ export async function runDsrDelete(opts, deps = {}) {
         return fail(toCliError(e));
     }
 }
+// PIT-7521 QA Q8: the spec's field names were documented only in the README, so a user reading
+// `--help` had to guess the ShareBox source keys. The keys are the wire (snake_case) names.
+const CREATE_HELP = `
+--config-file spec (start from \`p dsr scaffold\`). Keys are the wire (snake_case)
+names; source and security are spread into the create body as written.
+  source    exactly one of:
+              canvas_id        existing canvas ULID
+              sharebox_items   [{ "file_id": "<ULID>", "page_index"?: 0 }] — builds a
+                               new ShareBox canvas; page_index is optional (omit it
+                               to share the whole file)
+            ShareBox-only extras: instance_id (required unless --instance-id),
+            canvas_name, account_id, template_id
+  security  auth_strategy, allowed_emails [], allowed_domains [], valid_until,
+            allow_forward, allow_download, tags [] (tags: ShareBox only)
+            allow_download is stored on the CANVAS: omit it (the scaffold does) to
+            leave the canvas unchanged; unset, the viewer offers downloads
+  landing   landing_page_template_id, landing_page_context {}
+Example ShareBox source:
+  "source": { "instance_id": "01...", "sharebox_items": [{ "file_id": "01..." }] }`;
+const GET_HELP = `
+Reads the share back through the same public pre-auth config the sharing page
+itself loads (the protected shared-links surface has no GET). The body is
+returned unchanged, and it is the ACCESS CONFIG only: auth_strategy,
+allowed_emails / allowed_domains, valid_until, allow_forward (plus
+allow_forward_raw, the rep's own toggle), the landing-page binding
+(landing_page_template_id, landing_page_template_snapshot,
+landing_page_context) and created_at / modified_at. The endpoint returns NO
+canvas or file — keep the id \`dsr create\` handed back for those.
+  --id   the shared link ID (required)
+Any id that matches no share answers 404 -> NOT_FOUND (exit 5). That is the
+only id failure mode: the route does not validate the id's format, so a
+malformed id is a miss like any other, not a 400.`;
 export function createDsrCommand() {
-    const cmd = new Command('dsr').description('create and share a Digital Sales Room (a canvas share link)');
+    const cmd = new Command('dsr').description('create, read and share a Digital Sales Room (a canvas share link)');
     withAuthFlags(cmd.command('scaffold'))
         .description('print a {source,security,landing} share spec to fill in and pass to `dsr create --config-file`')
         .option('--out <path>', 'Write the scaffold to a file instead of stdout')
@@ -472,17 +572,20 @@ export function createDsrCommand() {
         .option('--valid-until <iso>', 'Expiry (ISO datetime)')
         .option('--allow-forward', 'Allow recipients to forward')
         .option('--no-allow-forward', 'Disallow forwarding')
-        .option('--allow-download', 'Allow download')
-        .option('--no-allow-download', 'Disallow download')
+        .option('--allow-download', 'Allow download (with --canvas-id you must own the canvas or hold canvas.update on it, else AUTH)')
+        .option('--no-allow-download', 'Disallow download (same ownership rule as --allow-download)')
         .option('--tags <csv>', 'Tags for the ShareBox-built canvas (rejected with --canvas-id, which ignores them)', parseTags)
         .option('--landing-template-id <id>', 'Landing template to bind (optional)')
         .option('--landing-context <json>', 'Landing personalization merge fields (JSON object)')
-        .option('--config-file <path>', 'Full {source,security,landing} spec JSON (mutually exclusive with the flags above)')
+        .option('--landing-context-file <path>', 'Path to a JSON file with the landing merge fields — the Windows-safe alternative to --landing-context (exactly one of the two)')
+        .option('--config-file <path>', 'Full {source,security,landing} spec JSON — source is {canvas_id} or {sharebox_items: [{file_id, page_index?}], ' +
+        'instance_id}; field list below (mutually exclusive with the flags above)')
         .option('--if-exists <mode>', 'return|error. What to do when the canvas is already shared: `return` hands back the existing link (default ' +
         'with individual flags), `error` refuses and points at `dsr update` (default with --config-file, whose ' +
         'security block is sent as-is and would overwrite the existing share). The check is a preflight lookup, so ' +
         'it is advisory rather than atomic — a link created between the check and the share is still returned. ' +
         'Never applies to a ShareBox source, which always mints a new canvas.')
+        .addHelpText('after', CREATE_HELP)
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runDsrCreate({ ...options, quiet: globals.quiet }), globals);
@@ -492,11 +595,20 @@ export function createDsrCommand() {
         .option('--id <id>', 'Shared link ID (required)')
         .option('--landing-template-id <id>', "Landing template ID, or 'none' to unbind (required)")
         .option('--landing-context <json>', 'Personalization merge fields (JSON object)')
+        .option('--landing-context-file <path>', 'Path to a JSON file with the merge fields — the Windows-safe alternative to --landing-context (exactly one of the two)')
         .option('--instance-id <id>', 'Instance ID (required — the endpoint resolves the instance from it)')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runDsrBindLanding({ ...options, quiet: globals.quiet }), globals);
     });
+    withAuthFlags(cmd.command('get'))
+        .description('read an existing share back: gating, allow-lists, expiry, forwarding and the bound landing page')
+        .option('--id <id>', 'Shared link ID (required)')
+        .addHelpText('after', GET_HELP)
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runDsrGet({ ...options, quiet: globals.quiet }), globals);
+    });
     // Every --x is declared BEFORE its --no-x on purpose: commander takes a boolean's default
     // from whichever of the pair it sees first, so the reverse order would make the option
     // default to `true` and every call would ship it. For allow_forward that clobbers a rep's

package/dist/src/commands/publishApp.d.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import type { AxiosInstance } from 'axios';
+import { type Credential } from '../core/credential.js';
 import { type Envelope } from '../core/envelope.js';
 interface PublishResult {
     app?: {
@@ -14,6 +15,7 @@ interface PublishResult {
 interface PublishOptions {
     folder?: string;
     apiKey?: string;
+    credential?: Credential;
     org?: string;
     url?: string;
     incrementVersion?: boolean;

package/dist/src/commands/publishApp.js

@@ -4,7 +4,7 @@ import os from 'os';
 import path from 'path';
 import { randomUUID } from 'crypto';
 import FormData from 'form-data';
-import { resolveApiKey } from '../core/auth.js';
+import { credentialOf } from '../core/credential.js';
 import { resolveBaseUrl } from '../core/baseUrl.js';
 import { makeClient, toCliError } from '../core/http.js';
 import { zipDirectoryToFile } from '../core/archive.js';
@@ -92,7 +92,7 @@ async function installToInstances(client, appName, instances, quiet) {
 }
 export async function runPublishApp(opts, deps = {}) {
     try {
-        const apiKey = resolveApiKey(opts);
+        const cred = credentialOf(opts);
         const baseUrl = resolveBaseUrl({ org: opts.org, url: opts.url });
         const folderPath = path.resolve(opts.folder ?? '.');
         const appJsonPath = path.join(folderPath, 'app.json');
@@ -124,7 +124,7 @@ export async function runPublishApp(opts, deps = {}) {
             fs.writeFileSync(appJsonPath, JSON.stringify(existingAppJson, null, 2));
             log(`Updated app.json version to ${nextVersion}`, { quiet: opts.quiet });
         }
-        const client = deps.client ?? makeClient(baseUrl, apiKey);
+        const client = deps.client ?? makeClient(baseUrl, cred);
         const zipPath = path.join(deps.tmpDir ?? os.tmpdir(), `cli-publish-${process.pid}-${randomUUID()}.zip`);
         try {
             log(`Zipping ${folderPath}...`, { quiet: opts.quiet });

package/dist/src/commands/scaffolds.js

@@ -272,9 +272,14 @@ const METADATA_TEMPLATE_SCAFFOLD_DATA = [
 export const METADATA_TEMPLATE_SCAFFOLD_JSON = JSON.stringify(METADATA_TEMPLATE_SCAFFOLD_DATA, null, 2);
 const DSR_SHARE_SCAFFOLD_DATA = {
     source: {
-        // provide ONE of the following:
+        // provide ONE source: canvas_id (share an existing canvas) OR a non-empty sharebox_items (build a
+        // new ShareBox canvas from files) — delete the canvas_id line when you fill sharebox_items.
+        // Emitted as a real key, not a comment, because comments never reach the printed JSON (PIT-7521 QA Q8);
+        // an EMPTY array asks for nothing, so the untouched scaffold still shares canvas_id.
         canvas_id: '01EXAMPLECANVASID000000000',
-        // sharebox_items: [{ file_id: '01EXAMPLEFILEID0000000000', page_index: 0 }],
+        sharebox_items: [], // [{ "file_id": "<file ULID>", "page_index"?: 0 }] — page_index optional (one page, not the whole file)
+        // ShareBox-only, and NOT emitted because the server refuses null for them — add them when needed:
+        // instance_id: '01EXAMPLEINSTANCEID0000000', (required for sharebox_items unless --instance-id is passed)
         // canvas_name: 'Acme QBR',
         // account_id: '01EXAMPLEACCOUNTID00000000',
         // template_id: '01EXAMPLECANVASTEMPLATE0000',
@@ -285,7 +290,10 @@ const DSR_SHARE_SCAFFOLD_DATA = {
         allowed_domains: [],
         valid_until: null,
         allow_forward: true,
-        allow_download: false,
+        // allow_download: false, — NOT emitted. It is stored on the CANVAS (read by every link on it), and
+        // the server writes it only when present: omitted, an existing canvas keeps its value and a new
+        // ShareBox canvas carries none, which the viewer treats as downloads allowed. Emitting a default
+        // here would silently flip an existing canvas's setting on every untouched run (PIT-7521 review).
         tags: [],
     },
     landing: {

package/dist/src/core/archive.js

@@ -1,9 +1,9 @@
-import archiver from 'archiver';
+import { ZipArchive } from 'archiver';
 import fs from 'fs';
 export async function zipDirectoryToBuffer(dir) {
     return new Promise((resolve, reject) => {
         const chunks = [];
-        const archive = archiver('zip', { zlib: { level: 9 } });
+        const archive = new ZipArchive({ zlib: { level: 9 } });
         archive.on('data', (chunk) => chunks.push(chunk));
         archive.on('end', () => resolve(Buffer.concat(chunks)));
         archive.on('error', reject);
@@ -14,7 +14,7 @@ export async function zipDirectoryToBuffer(dir) {
 export async function zipDirectoryToFile(dir, outPath) {
     return new Promise((resolve, reject) => {
         const output = fs.createWriteStream(outPath);
-        const archive = archiver('zip', { zlib: { level: 9 } });
+        const archive = new ZipArchive({ zlib: { level: 9 } });
         output.on('close', () => resolve(archive.pointer()));
         output.on('error', reject);
         archive.on('error', reject);

package/dist/src/core/credential.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The credential a request is sent with. `apiKey` is the Knox key the CLI (and stdio `p mcp`) has
+ * always used; `bearer` is a user's Auth0 access token, used by the hosted MCP server (PIT-8912).
+ */
+export type Credential = {
+    kind: 'bearer';
+    token: string;
+} | {
+    kind: 'apiKey';
+    key: string;
+};
+/** The auth header(s) for a credential. Exactly one header, never both. */
+export declare function authHeaders(c: Credential): Record<string, string>;
+/**
+ * The ONE credential resolver every call site uses.
+ *
+ * An explicit `credential` always wins and never falls through: a bearer context must fail CLOSED,
+ * so it can never pick up `--api-key` or `NG_API_KEY` from the process env (the hosted server
+ * would otherwise act as whoever minted that key). Only when no credential is given (CLI / stdio)
+ * does this reach `resolveApiKey`, which reads `--api-key` then `NG_API_KEY`.
+ */
+export declare function credentialOf(opts: {
+    apiKey?: string;
+    credential?: Credential;
+}): Credential;