@pitcher/cli-scripts

Pitcher CLI Tools provide a suite of command-line utilities to streamline your workflow. For the best experience, we recommend installing the tools globally using npm install -g @pitcher/cli-scripts.

Help

p --help
# or for specific command help:
p command --help

To run the publish-app command:

# Basic usage
p publish-app <folder> --url https://pitcher.my.pitcher.com --api-key myapikey

# Publish to current folder and default org (dev)
p publish-app --api-key myapikey

# Publish to a specific organization subdomain (e.g., pitcher.my.pitcher.com)
p publish-app --api-key myapikey --org pitcher

# Dry run with version increment
p publish-app --api-key myapikey --org pitcher --dry-run --increment-version

# Publish and install to specific instances
p publish-app --api-key myapikey --org pitcher --increment-version --install-to 01JB8KQRM3XYZ2P4N5W7T9VHFA,01JB8KR0P6QS4T8X1M9Y3C7ZBE

# Publish and install to all instances with a specific environment name (case-insensitive)
p publish-app --api-key myapikey --org pitcher --increment-version --install-to-env-name Demo

# Combine both: install to specific instances AND all instances in an environment
p publish-app --api-key myapikey --org pitcher --increment-version --install-to 01JB8KS5F2WH9V6D8R3N7JXMQK --install-to-env-name Demo

# Alternative: Set API key via environment variable
export NG_API_KEY=myapikey
p publish-app --org pitcher --increment-version --install-to-env-name Production

Options

• --api-key <apiKey>: API Key for authentication (can also use NG_API_KEY env variable)
• --org <organization>: Organization subdomain (e.g., "pitcher" for pitcher.my.pitcher.com, default: "dev")
• --increment-version: Increment version in app.json with timestamp
• --dry-run: Perform a dry run without publishing
• --publish-url <url>: Explicit publish URL
• --install-to <instanceIds>: Comma-separated list of instance IDs to install the app to after publishing
• --install-to-env-name <envName>: Environment name to filter instances and install the app to after publishing (case-insensitive)

To run the dev-sync command:

Sync a marketplace app directly to S3 for live development testing without publishing. This is useful for testing app changes in a pre-production environment.

# One-time sync from dist folder
p dev-sync sync --file-id <pitcher_file_id> --api-key myapikey

# Sync to a specific organization (default: dev)
p dev-sync sync --file-id <pitcher_file_id> --org pitcher

# Watch mode - auto-sync on file changes (reverts on Ctrl+C)
p dev-sync watch --file-id <pitcher_file_id> --api-key myapikey

# Watch with custom debounce (default: 2500ms)
p dev-sync watch --file-id <pitcher_file_id> --debounce 5000

# Manually revert dev override to restore original version
p dev-sync revert --file-id <pitcher_file_id> --api-key myapikey

# Alternative: Set API key via environment variable
export NG_API_KEY=myapikey
p dev-sync watch --file-id <pitcher_file_id> --org pitcher

Options

• --file-id <id>: (Required) File ID of the installed app (pitcher_file.id) - copy this from the installed apps view
• --api-key <apiKey>: API Key for authentication (can also use NG_API_KEY env variable)
• --org <organization>: Organization subdomain (default: "dev")
• --debounce <ms>: Debounce time in milliseconds for watch mode (default: 2500)

Notes

• Run from your app's project root (with dist/ folder) or directly from the dist/ folder
• The watch command automatically reverts changes on graceful shutdown (Ctrl+C)
• Apps with dev override show a badge in the installed apps view

To run the files command:

Manage Pitcher content files — list within an instance, fetch by id, create (upload or link), or update.

# List files in an instance (paginated)
p files list --instance-id 01... --api-key myapikey

# Filter by tags or specific IDs
p files list --instance-id 01... --tags brochure,demo --api-key myapikey

# Get a single file by id
p files get 01FILEID... --api-key myapikey

# Create a file from a local upload
p files create --instance-id 01... --name "Q3 Deck" --file ./deck.pdf --api-key myapikey

# Create a link/WEB file from a source URL
p files create --instance-id 01... --name "Product Page" --source-url https://example.com --api-key myapikey

# Update a file's tags or metadata (metadata/app-metadata are deep-merged, not replaced)
p files update 01FILEID... --tags updated,reviewed --api-key myapikey

To run the folders command:

Manage Pitcher content folders — list, fetch (or the instance root), create, and update smart-folder rules.

# List folders in an instance (paginated)
p folders list --instance-id 01... --api-key myapikey

# Get a folder by id
p folders get 01FOLDERID... --api-key myapikey

# Get the instance root folder
p folders get --root --instance-id 01... --api-key myapikey

# Create a folder under a parent
p folders create --name "Marketing" --parent-folder-id 01PARENTID... --api-key myapikey

# Update a folder's name or access type
p folders update 01FOLDERID... --name "Sales Enablement" --access-type restricted --api-key myapikey

To run the search command:

# Ranked cross-type search (files, canvases, users, apps) within an instance
p search --instance-id 01... --query "quarterly deck" --api-key myapikey

To run the instances command:

Discover Pitcher instances — resolve names to instance IDs before running other commands.

# List instances (optionally filter by region/storage-region/environment)
p instances list --api-key myapikey

p instances list --environment Demo --api-key myapikey

# Get a single instance by id
p instances info 01INSTANCEID... --api-key myapikey

To run the canvases command:

Read Pitcher canvases — presentations, sections, and blocks.

# List canvases in an instance (paginated)
p canvases list --instance-id 01... --api-key myapikey

# Only templates or only sections
p canvases list --instance-id 01... --is-template --api-key myapikey
p canvases list --instance-id 01... --is-section --api-key myapikey

# Only blocks (blocks are hidden unless --is-block is passed)
p canvases list --instance-id 01... --is-block --api-key myapikey

# Get a single canvas by id
p canvases get 01CANVASID... --api-key myapikey

To run the shared-links command:

Create and read share links for canvases or files (returns the short_url).

# Create a share link for a canvas
p shared-links create --canvas-id 01CANVASID... --api-key myapikey

# Create a share link for a file
p shared-links create --file-id 01FILEID... --api-key myapikey

# Fetch the existing share link for a canvas
p shared-links get --canvas-id 01CANVASID... --api-key myapikey

To run the tags command:

List tags in an instance (the server requires a search term of at least 3 characters).

# List tags matching a search term
p tags list --instance-id 01... --search "demo" --api-key myapikey

# Filter by type
p tags list --instance-id 01... --search "demo" --type canvases --api-key myapikey

To run the email-template command:

Create/list/get HTML email templates for the emails app. create, list, and get require --instance-id (scaffold does not).

# Create a template from an HTML file (inline CSS)
p email-template create --instance-id 01... --name "Welcome" --body-file ./welcome.html --api-key myapikey

# List templates (optionally filter by name/status/category/target)
p email-template list --instance-id 01... --api-key myapikey

# Get a template by id
p email-template get --instance-id 01... --id 01TEMPLATEID... --api-key myapikey

# Generate a starter HTML file with tokens in context
p email-template scaffold --out ./welcome.html --api-key myapikey

Run p email-template create --help for the full token/marker reference.

scaffold returns the starter HTML in the envelope data (never printed raw to stdout); pass --out <path> to write it to a file instead.

To run the dsr-landing command:

Create/list DSR (Digital Sales Room) landing-page templates, and set one as the instance-scope default. create, list, and set-default require --instance-id (scaffold does not).

# Create a landing template from an HTML file (must contain the email-gate marker)
p dsr-landing create --instance-id 01... --name "Default" --html-file ./landing.html --api-key myapikey

# Create and set as default in one call
p dsr-landing create --instance-id 01... --name "Default" --html-file ./landing.html --default --api-key myapikey

# Set an existing template as the default
p dsr-landing set-default --instance-id 01... --id 01TEMPLATEID... --api-key myapikey

# List templates in an instance
p dsr-landing list --instance-id 01... --api-key myapikey

# Generate a starter HTML file with the required marker and tokens in context
p dsr-landing scaffold --out ./landing.html --api-key myapikey

--html-file must contain the data-pitcher-email-gate marker verbatim (the platform injects the email-gate form there) — create fails client-side before any request if it's missing.

Run p dsr-landing create --help for the full token/marker reference (editable-region attributes, recipient/customer/org/rep tokens).

scaffold returns the starter HTML in the envelope data; pass --out <path> to write it to a file instead.

To run the announcements command:

Create/list announcement records for the wa-announcements app. create and list require --instance-id (scaffold does not).

# Create from a JSON data file
p announcements create --instance-id 01... --from-file ./announcement.json --api-key myapikey

# Create from convenience flags only
p announcements create --instance-id 01... --title "New feature" --body "<p>Check it out</p>" --api-key myapikey

# List announcements
p announcements list --instance-id 01... --api-key myapikey

# Generate a fully populated starter data.json
p announcements scaffold --out ./announcement.json --api-key myapikey

create requires either --from-file or both --title and --body. --title/--body/--priority override matching keys from --from-file when both are given. Run p announcements create --help for the full data field catalog (media, links, scheduling, target groups, popup overrides) — note start_at/expires_at are naive local dates (YYYY-MM-DD[THH:mm]), not ISO/UTC.

scaffold returns the starter JSON in the envelope data; pass --out <path> to write it to a file instead.

To run the themes command:

Read canvas/branding themes (colors via settings, fonts via typography, plus assets/logo) to reference when authoring email/DSR/canvas content. Read-only.

# List all themes in the org (returns full theme objects)
p themes list --api-key myapikey

# Narrow to one instance; add per-theme canvas usage and canvas ids
p themes list --instance-id 01... --with-usage --with-canvas-ids --api-key myapikey

# Get one theme by id
p themes get --id 01THEMEID... --api-key myapikey

list is server-capped (newest-first) with no --limit/--page; when the cap is hit the envelope carries a truncation warning. --instance-id narrows to themes bound to that instance and excludes org-level (default) themes, so omit it to see everything usable in the org.

To run the org command:

Read the organization the API key belongs to.

p org get --api-key myapikey

To run the analytics command:

Read rollup analytics totals for an organization or instance. Requires an org-admin API key — a non-admin key returns an auth error.

# Organization-wide rollups (org-admin key required)
p analytics org --api-key myapikey

# Instance rollups (instance-admin or org-admin key required)
p analytics instance --instance-id 01... --api-key myapikey

To run the users command:

Read users in the org (read-only). Org scope comes from the API key via the proxy x-org-id header — there is no --org-id flag.

# List users in the org (paginated)
p users list --api-key myapikey

# Filter by instance membership, roles, active status, or content-distribution group
p users list --instance-id 01... --api-key myapikey
p users list --instance-id 01... --instance-role editor --api-key myapikey
p users list --role admin --api-key myapikey
p users list --is-active --api-key myapikey
p users list --cdg 01GROUPID... --api-key myapikey

# Get a single user by id (user ids are integers, not ULIDs)
p users get --id 2446 --api-key myapikey

List filters: --instance-id, --instance-role (server-side requires --instance-id), --role, --is-active, --cdg, plus --page/--page-size (max 500). ID shapes: user ids are integers; instance and group ids are ULIDs.

To run the invitations command:

Read pending user invitations (read-only).

# List pending invitations (paginated)
p invitations list --api-key myapikey

# Get a single invitation by id (invitation ids are 'uinv_...' strings, not ULIDs)
p invitations get --id uinv_0yKQ41LLqOI2kn4E --api-key myapikey

To run the memberships command:

Read instance memberships, add members, and change their role.

# List memberships (filter by instance or user; user ids are integers)
p memberships list --instance-id 01... --api-key myapikey
p memberships list --user-id 2446 --api-key myapikey

# Add a user to an instance (always created as 'member')
p memberships add --instance-id 01... --user-id 2446 --api-key myapikey

# Change a membership's role (org-admin key required; membership ids are integers)
p memberships set-role --membership-id 3537 --role editor --api-key myapikey

add always creates the membership as member; use set-role to change it. set-role needs an org-admin key (an instance-admin key can add but not set-role). --membership-id is the integer membership row id from memberships list (not a user id). --role is the short role name (e.g. editor) discovered via p roles list — the prefixed key (instance:editor) is rejected. --scope defaults to instance; --scope organization targets the organization membership row instead — note its row id is NOT discoverable via this CLI today (memberships list returns instance memberships only), so use it only when you already have the org-membership id from another source.

To run the groups command:

Read/create content-distribution groups and manage their members.

# List groups (filter by instance)
p groups list --instance-id 01... --api-key myapikey

# Get a group by id
p groups get --id 01GROUPID... --api-key myapikey

# Create a group (name min 3 chars)
p groups create --instance-id 01... --name "West Region" --api-key myapikey

# Add a user to a group (user ids are integers)
p groups add-user --group-id 01GROUPID... --user-id 2446 --api-key myapikey

# List a group's members
p groups list-users --group-id 01GROUPID... --api-key myapikey

add-user is rejected on auto-login-managed groups (their membership is derived, not manually editable).

To run the roles command:

Read the org's role set (6 system roles + any custom roles) — the discovery aid for p memberships set-role.

# List the org's roles
p roles list --api-key myapikey

# Filter by scope
p roles list --scope instance --api-key myapikey

list returns a { items: [...] } object; each item's role_key is prefixed (org:admin, instance:editor). Pass the short name (e.g. editor) to set-role, not the prefixed key. Like set-role, roles list currently needs an org-admin key: while the granular-permissions rollout is off (the production default), the endpoint 403s non-org-admin callers.

To run the metadata-template command:

Read and additively build an instance's metadata-field schema. list and upsert require --instance-id (get only needs --id; scaffold makes no request).

# Read the schema for an instance (0 or 1 template — one per instance)
p metadata-template list --instance-id 01... --api-key myapikey

# Get one template by id (ids are ULIDs)
p metadata-template get --id 01TEMPLATEID... --api-key myapikey

# Print a starter schema to fill in (optionally to a file)
p metadata-template scaffold --out ./schema.json

# Additively upsert the schema (merges by section label)
p metadata-template upsert --instance-id 01... --sections-file ./schema.json --api-key myapikey

upsert merges the incoming sections by section label — a section whose label matches an existing one is replaced, other sections are preserved. It cannot remove a section or field (that's a UI operation). options for select/multi-select fields are { label, value } objects (bare strings are rejected). upsert requires an instance- or org-admin key; a non-admin member key is rejected (400 → VALIDATION).