@pitcher/cli-scripts 2.17.1 → 2.19.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,13 +519,21 @@ 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... --landing-template-id 01...
-p dsr bind-landing --id 01... --landing-template-id none
+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
+p dsr create --canvas-id 01... --allow-download
+p dsr create --canvas-id 01... --no-allow-download
 # change an existing share — only the flags you pass are sent
 p dsr update --id 01... --valid-until 2026-12-01T00:00:00Z
 p dsr update --id 01... --auth-strategy specified_domains --allowed-domains acme.com
@@ -538,8 +546,33 @@ p dsr delete --id 01...
 p dsr scaffold --out share.json
 ```
 
+### The `--config-file` spec
+
+`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 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 |
+|-----|------|---------|
+| `canvas_id` | ULID string | Share an **existing** canvas. Exactly one of `canvas_id` / `sharebox_items`. |
+| `sharebox_items` | `[{ file_id, page_index? }]` | Build a **new** ShareBox canvas from these files and share that. `file_id` is a ULID; an integer `page_index` shares that single page of the file instead of the whole file (`--sharebox-file-ids` can only send whole files, so a per-page share needs the spec). Exactly one of `canvas_id` / `sharebox_items`. |
+| `canvas_name` | string | Name of the ShareBox-built canvas. Server default is `ShareBox <timestamp>`. |
+| `account_id` | ULID string | Account attached to the ShareBox-built canvas. **Required** when the instance is configured to require an account on canvas creation. |
+| `template_id` | ULID string | Canvas template the ShareBox-built canvas is built from. Omitted, the server looks for the instance's `share`-tagged template. |
+| `instance_id` | ULID string | The instance to create in. `--instance-id` overrides it when both are given, and it is also what the landing-page PUT is scoped to. |
+
+`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. 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.
 
+`--allow-download` has a `--no-allow-download` twin, so **both** directions are sendable (PIT-7521). Without it commander could only ever produce `true` or nothing: passing the flag said “allow”, and there was no way to say “do not allow” — the OFF state could not be expressed at all, only left out. Declaration order is load-bearing: the positive flag of each pair is declared first, because commander takes a boolean's default from whichever it sees first. ⚠️ The value records the sharer's **intent** and drives the viewer's UI; it is not a server-side download block — the file URL is already in the payload the browser receives.
+
 **Clearing an allow-list is refused while a strategy that needs it is in force**, because an empty allow-list denies every recipient rather than admitting them — the clear would brick the link, not open it. `specified_emails`/`verified_emails` need `allowed-emails`; `specified_domains`/`verified_domains` need `allowed-domains`. The check covers a strategy passed in the same call **and** the one already stored on the share (read from the public `GET /core/api/shared-links/{id}/config`, since the PATCH surface has no GET). If that read fails the update still goes through, with a warning saying the check did not run. Two ways out:
 
 ```bash
@@ -549,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 currently needs an editor key** (PIT-7525 will open it to reps for their own DSRs) — 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/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,9 +19,60 @@ 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
+// query param is the ONLY source there is: without it the server answers 400 "Instance ID is
+// required" before it ever looks at the share. Catching it here names the missing flag instead of
+// handing back that opaque server error.
+const LANDING_INSTANCE_REQUIRED = '--instance-id is required to bind a landing page: the landing-page endpoint resolves the instance from that query param and refuses the call without it';
+// `instanceId` is REQUIRED, not optional-with-a-ternary: both call sites now refuse an empty one
+// before they get here (`runDsrBindLanding` throws, `runDsrCreate` returns the share with a warning),
+// so a params-less PUT is unreachable — and it was never anything but the guaranteed 400 above.
+// Typing it away is what stops a future caller from quietly reintroducing that call.
 async function bindLandingRequest(client, id, body, instanceId) {
     const url = `${ENDPOINT}/${encodeURIComponent(id)}/landing-page`;
-    const res = await client.put(url, body, instanceId ? { params: { instance_id: instanceId } } : undefined);
+    const res = await client.put(url, body, { params: { instance_id: instanceId } });
     return res.data;
 }
 export async function runDsrBindLanding(opts, deps = {}) {
@@ -31,9 +82,12 @@ export async function runDsrBindLanding(opts, deps = {}) {
         const templateId = resolveTemplateId(opts.landingTemplateId);
         if (templateId === undefined)
             throw createCliError('VALIDATION', '--landing-template-id is required (use "none" to unbind)');
+        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);
@@ -48,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) {
@@ -105,9 +160,28 @@ 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
+    // a hole — it fails before any request, with a message that names the field. This guard already owns
+    // the key, so it owns the shape too — and shape means the ELEMENTS as well: the server field is
+    // `z.array(z.string())`, so `tags: [1]` clears `Array.isArray` and still has to be refused. An EMPTY
+    // array passes both checks, by design.
+    if (tags !== undefined && (!Array.isArray(tags) || tags.some((t) => typeof t !== 'string')))
+        throw createCliError('VALIDATION', 'tags must be an array of strings');
+    // SOURCE second: `tags` is read by exactly one branch of the server route — the ShareBox branch,
+    // where it names the canvas the server MINTS from sharebox_items. With an existing canvas there is
+    // nothing to name: the POST schema still accepts the key and then drops it on the floor, so the
+    // tags vanish with no error at all. Refuse the combination instead of shipping a silent no-op.
+    // An EMPTY array is NOT a request to tag anything: `dsr scaffold` emits `tags: []` in its starter
+    // security block, so rejecting that would break every untouched `--config-file` create.
+    if (hasCanvas && Array.isArray(tags) && tags.length > 0)
+        throw createCliError('VALIDATION', 'tags apply only to a ShareBox-built canvas — they name the canvas the server creates from ' +
+            '--sharebox-file-ids, and with --canvas-id the server ignores them. Drop the tags, or share the ' +
+            'files with --sharebox-file-ids.');
     const strat = body.auth_strategy;
     if (strat !== undefined) {
         if (!AUTH_STRATEGIES.includes(strat))
@@ -149,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) ──────────────────────────────────────
@@ -223,6 +300,16 @@ export async function runDsrCreate(opts, deps = {}) {
         const shareId = share?.id;
         if (!shareId)
             return ok({ ...share, landing: null }, ['landing not attached: no share id in create response']);
+        // Same missing-instance failure as `dsr bind-landing`, reached from the other call site. It stays
+        // a WARNING rather than a hard failure because the share itself was created successfully and is
+        // the caller's primary output — dropping it would strand a live link with nothing referencing it.
+        // What changes is that the PUT is not attempted at all (it cannot succeed) and the warning names
+        // the flag plus the exact follow-up command, instead of echoing an opaque 400 from the server.
+        if (!effectiveInstanceId)
+            return ok({ ...share, landing: null }, [
+                `landing not attached: ${LANDING_INSTANCE_REQUIRED}. The share itself was created — bind the ` +
+                    `landing page with \`p dsr bind-landing --id ${shareId} --landing-template-id <template-id> --instance-id <instance-id>\``,
+            ]);
         try {
             const landing = await bindLandingRequest(client, shareId, landingBody, effectiveInstanceId);
             return ok({ ...share, landing });
@@ -327,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);
@@ -407,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')
@@ -418,7 +560,7 @@ export function createDsrCommand() {
     });
     withAuthFlags(cmd.command('create'))
         .description('create + share a DSR (canvas share link) and return the link (id, url, short_url, canvas)')
-        .option('--instance-id <id>', 'Instance ID (required for --sharebox-file-ids)')
+        .option('--instance-id <id>', 'Instance ID (required for --sharebox-file-ids, and to bind a landing page)')
         .option('--canvas-id <id>', 'Existing canvas to share (one source required)')
         .option('--sharebox-file-ids <csv>', 'Build a canvas from these file IDs (one source required)', parseTags)
         .option('--canvas-name <name>', 'Name for the ShareBox-built canvas')
@@ -430,16 +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('--tags <csv>', 'Tags', parseTags)
+        .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);
@@ -449,15 +595,25 @@ 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('--instance-id <id>', 'Instance ID (optional)')
+        .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);
     });
-    // --allow-forward is declared BEFORE --no-allow-forward on purpose: commander takes a
-    // boolean's default from whichever of the pair it sees first, so the reverse order would
-    // make `allowForward` default to `true` and every update would ship allow_forward: true,
-    // clobbering a rep's opt-out. `create` above relies on the same ordering.
+    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
+    // opt-out; for allow_download it would turn an unpassed flag into an active grant.
+    // `create` above relies on the same ordering for BOTH pairs.
     withAuthFlags(cmd.command('update'))
         .description('update an existing share: only the flags you pass are sent; --clear removes a value')
         .option('--id <id>', 'Shared link ID (required)')

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: {