@pitcher/cli-scripts 2.4.0 → 2.6.0

package/README.md

@@ -270,6 +270,23 @@ p announcements scaffold --out ./announcement.json --api-key myapikey
 
 `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.
+
+```bash
+# 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.
@@ -289,3 +306,91 @@ 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.
+
+```bash
+# 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).
+
+```bash
+# 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.
+
+```bash
+# 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.
+
+```bash
+# 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`.
+
+```bash
+# 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.

package/dist/index.js

@@ -17,6 +17,12 @@ import { createAnalyticsCommand } from './src/commands/analytics.js';
 import { createAnnouncementsCommand } from './src/commands/announcements.js';
 import { createDsrLandingCommand } from './src/commands/dsrLanding.js';
 import { createEmailTemplateCommand } from './src/commands/emailTemplate.js';
+import { createThemesCommand } from './src/commands/themes.js';
+import { createUsersCommand } from './src/commands/users.js';
+import { createInvitationsCommand } from './src/commands/invitations.js';
+import { createMembershipsCommand } from './src/commands/memberships.js';
+import { createGroupsCommand } from './src/commands/groups.js';
+import { createRolesCommand } from './src/commands/roles.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -39,6 +45,12 @@ program.addCommand(createTagsCommand());
 program.addCommand(createAnnouncementsCommand());
 program.addCommand(createDsrLandingCommand());
 program.addCommand(createEmailTemplateCommand());
+program.addCommand(createThemesCommand());
+program.addCommand(createUsersCommand());
+program.addCommand(createInvitationsCommand());
+program.addCommand(createMembershipsCommand());
+program.addCommand(createGroupsCommand());
+program.addCommand(createRolesCommand());
 program.addCommand(createOrgCommand());
 program.addCommand(createAnalyticsCommand());
 program.parseAsync(process.argv);

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

@@ -0,0 +1,35 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export interface GroupsDeps {
+    client?: AxiosInstance;
+}
+export declare function runGroupsList(opts: CommonOpts & {
+    instanceId?: string;
+    page?: number;
+    pageSize?: number;
+}, deps?: GroupsDeps): Promise<Envelope<{
+    results: unknown[];
+    pagination: Record<string, unknown>;
+}>>;
+export declare function runGroupsGet(opts: CommonOpts & {
+    id?: string;
+}, deps?: GroupsDeps): Promise<Envelope<unknown>>;
+export declare function runGroupsCreate(opts: CommonOpts & {
+    instanceId?: string;
+    name?: string;
+}, deps?: GroupsDeps): Promise<Envelope<unknown>>;
+export declare function runGroupsAddUser(opts: CommonOpts & {
+    groupId?: string;
+    userId?: string;
+}, deps?: GroupsDeps): Promise<Envelope<unknown>>;
+export declare function runGroupsListUsers(opts: CommonOpts & {
+    groupId?: string;
+    page?: number;
+    pageSize?: number;
+}, deps?: GroupsDeps): Promise<Envelope<{
+    results: unknown[];
+    pagination: Record<string, unknown>;
+}>>;
+export declare function createGroupsCommand(): Command;

package/dist/src/commands/groups.js

@@ -0,0 +1,125 @@
+import { Command } from 'commander';
+import { clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+import { createCliError } from '../core/errors.js';
+import { emitEnvelope } from '../core/output.js';
+import { listPageParams, listPaginationEcho } from '../core/pagination.js';
+import { assertIntFlags } from '../schema/content.js';
+import { withAuthFlags } from './withAuth.js';
+const GROUPS = '/api/v1/content-distribution-groups/';
+const GROUP_MEMBERS = '/api/v1/content-distribution-group-memberships/';
+export async function runGroupsList(opts, deps = {}) {
+    try {
+        assertIntFlags(opts);
+        const client = clientFor(opts, deps);
+        const params = { ...listPageParams(opts) };
+        if (opts.instanceId)
+            params.instance_id = opts.instanceId;
+        const res = await client.get(GROUPS, { params });
+        return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runGroupsGet(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required for groups get');
+        const client = clientFor(opts, deps);
+        const res = await client.get(`${GROUPS}${encodeURIComponent(opts.id)}`);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runGroupsCreate(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for groups create');
+        if (!opts.name)
+            throw createCliError('VALIDATION', '--name is required for groups create');
+        const client = clientFor(opts, deps);
+        const res = await client.post(GROUPS, { instance_id: opts.instanceId, name: opts.name });
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runGroupsAddUser(opts, deps = {}) {
+    try {
+        if (!opts.groupId)
+            throw createCliError('VALIDATION', '--group-id is required for groups add-user');
+        if (!opts.userId)
+            throw createCliError('VALIDATION', '--user-id is required for groups add-user');
+        const client = clientFor(opts, deps);
+        const res = await client.post(GROUP_MEMBERS, {
+            content_distribution_group_id: opts.groupId,
+            user_id: opts.userId,
+        });
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runGroupsListUsers(opts, deps = {}) {
+    try {
+        assertIntFlags(opts);
+        const client = clientFor(opts, deps);
+        const params = { ...listPageParams(opts) };
+        // The list filterset is content_distribution_group_id (NOT the bare relation
+        // name) — an unknown param is silently ignored by DjangoFilterBackend and the
+        // endpoint returns every visible membership in the org.
+        if (opts.groupId)
+            params.content_distribution_group_id = opts.groupId;
+        const res = await client.get(GROUP_MEMBERS, { params });
+        return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createGroupsCommand() {
+    const cmd = new Command('groups').description('read/create content-distribution groups and manage their members');
+    withAuthFlags(cmd.command('list'))
+        .option('--instance-id <id>', 'Filter by instance')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--page-size <n>', 'Page size (max 500)', (v) => parseInt(v, 10))
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runGroupsList({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('get'))
+        .option('--id <id>', 'Group ID')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runGroupsGet({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('create'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--name <name>', 'Group name (required, min 3 chars)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runGroupsCreate({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('add-user'))
+        .description('add a user to a group (rejected on auto-login-managed groups)')
+        .option('--group-id <id>', 'Group ID (required)')
+        .option('--user-id <id>', 'User ID (integer, required)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runGroupsAddUser({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('list-users'))
+        .option('--group-id <id>', 'Group whose members to list')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--page-size <n>', 'Page size (max 500)', (v) => parseInt(v, 10))
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runGroupsListUsers({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -0,0 +1,18 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export interface InvitationsDeps {
+    client?: AxiosInstance;
+}
+export declare function runInvitationsList(opts: CommonOpts & {
+    page?: number;
+    pageSize?: number;
+}, deps?: InvitationsDeps): Promise<Envelope<{
+    results: unknown[];
+    pagination: Record<string, unknown>;
+}>>;
+export declare function runInvitationsGet(opts: CommonOpts & {
+    id?: string;
+}, deps?: InvitationsDeps): Promise<Envelope<unknown>>;
+export declare function createInvitationsCommand(): Command;

package/dist/src/commands/invitations.js

@@ -0,0 +1,49 @@
+import { Command } from 'commander';
+import { clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+import { createCliError } from '../core/errors.js';
+import { emitEnvelope } from '../core/output.js';
+import { listPageParams, listPaginationEcho } from '../core/pagination.js';
+import { assertIntFlags } from '../schema/content.js';
+import { withAuthFlags } from './withAuth.js';
+export async function runInvitationsList(opts, deps = {}) {
+    try {
+        assertIntFlags(opts);
+        const client = clientFor(opts, deps);
+        const params = { ...listPageParams(opts) };
+        const res = await client.get('/api/v1/invitations/', { params });
+        return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runInvitationsGet(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required for invitations get');
+        const client = clientFor(opts, deps);
+        const res = await client.get(`/api/v1/invitations/${encodeURIComponent(opts.id)}`);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createInvitationsCommand() {
+    const cmd = new Command('invitations').description('read pending user invitations (read-only)');
+    withAuthFlags(cmd.command('list'))
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--page-size <n>', 'Page size (max 500)', (v) => parseInt(v, 10))
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runInvitationsList({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('get'))
+        .option('--id <id>', 'Invitation ID')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runInvitationsGet({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -0,0 +1,26 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export interface MembershipsDeps {
+    client?: AxiosInstance;
+}
+export declare function runMembershipsList(opts: CommonOpts & {
+    instanceId?: string;
+    userId?: string;
+    page?: number;
+    pageSize?: number;
+}, deps?: MembershipsDeps): Promise<Envelope<{
+    results: unknown[];
+    pagination: Record<string, unknown>;
+}>>;
+export declare function runMembershipsAdd(opts: CommonOpts & {
+    instanceId?: string;
+    userId?: string;
+}, deps?: MembershipsDeps): Promise<Envelope<unknown>>;
+export declare function runMembershipsSetRole(opts: CommonOpts & {
+    membershipId?: string;
+    role?: string;
+    scope?: string;
+}, deps?: MembershipsDeps): Promise<Envelope<unknown>>;
+export declare function createMembershipsCommand(): Command;

package/dist/src/commands/memberships.js

@@ -0,0 +1,97 @@
+import { Command } from 'commander';
+import { clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+import { createCliError } from '../core/errors.js';
+import { emitEnvelope } from '../core/output.js';
+import { listPageParams, listPaginationEcho } from '../core/pagination.js';
+import { assertIntFlags } from '../schema/content.js';
+import { withAuthFlags } from './withAuth.js';
+export async function runMembershipsList(opts, deps = {}) {
+    try {
+        assertIntFlags(opts);
+        const client = clientFor(opts, deps);
+        const params = { ...listPageParams(opts) };
+        if (opts.instanceId)
+            params.instance_id = opts.instanceId;
+        if (opts.userId)
+            params.user_id = opts.userId;
+        const res = await client.get('/api/v1/instance-memberships/', { params });
+        return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runMembershipsAdd(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for memberships add');
+        if (!opts.userId)
+            throw createCliError('VALIDATION', '--user-id is required for memberships add');
+        const client = clientFor(opts, deps);
+        // Role is hardcoded to 'member' — never send a caller-supplied role to
+        // Django's unvalidated create endpoint. Role changes go through set-role.
+        const body = { instance_id: opts.instanceId, user_id: opts.userId, role: 'member' };
+        const res = await client.post('/api/v1/instance-memberships/', body);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runMembershipsSetRole(opts, deps = {}) {
+    try {
+        if (!opts.membershipId)
+            throw createCliError('VALIDATION', '--membership-id is required for memberships set-role');
+        if (!opts.role)
+            throw createCliError('VALIDATION', '--role is required for memberships set-role');
+        const client = clientFor(opts, deps);
+        const scope = opts.scope ?? 'instance';
+        // Role passed through unvalidated — next-core validates against the org's
+        // real role set (system + custom) and 400s on anything bogus.
+        const res = await client.patch(`/core/api/protected/roles/assignments/${encodeURIComponent(opts.membershipId)}`, { scope, role: opts.role });
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+const SET_ROLE_HELP = `
+Changes a membership's role via the validating next-core endpoint. Requires an
+ORG-admin key (an instance-admin key can 'add' but not 'set-role').
+  --membership-id  the INTEGER membership ROW id (from 'memberships list'), not a user id
+  --role           SHORT role name (e.g. 'editor'); run 'p roles list' to discover.
+                   Do NOT pass the prefixed key ('instance:editor') — it is rejected.
+  --scope          'instance' (default) or 'organization'. Organization scope targets
+                   the ORG membership row, whose id is NOT discoverable via this CLI
+                   ('memberships list' returns instance memberships only).`;
+export function createMembershipsCommand() {
+    const cmd = new Command('memberships').description('read instance memberships, add members, and set roles');
+    withAuthFlags(cmd.command('list'))
+        .option('--instance-id <id>', 'Filter by instance')
+        .option('--user-id <id>', 'Filter by user (integer id)')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--page-size <n>', 'Page size (max 500)', (v) => parseInt(v, 10))
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runMembershipsList({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('add'))
+        .description("add a user to an instance as 'member' (use set-role to change the role)")
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--user-id <id>', 'User ID (integer, required)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runMembershipsAdd({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('set-role'))
+        .option('--membership-id <id>', 'Membership row ID (integer, required)')
+        .option('--role <role>', 'Short role name, e.g. editor (required)')
+        .option('--scope <scope>', 'instance | organization', 'instance')
+        .addHelpText('after', SET_ROLE_HELP)
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runMembershipsSetRole({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -0,0 +1,11 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export interface RolesDeps {
+    client?: AxiosInstance;
+}
+export declare function runRolesList(opts: CommonOpts & {
+    scope?: string;
+}, deps?: RolesDeps): Promise<Envelope<unknown>>;
+export declare function createRolesCommand(): Command;

package/dist/src/commands/roles.js

@@ -0,0 +1,38 @@
+import { Command } from 'commander';
+import { clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+import { emitEnvelope } from '../core/output.js';
+import { withAuthFlags } from './withAuth.js';
+const ROLES_ENDPOINT = '/core/api/protected/roles/configs';
+export async function runRolesList(opts, deps = {}) {
+    try {
+        const client = clientFor(opts, deps);
+        const params = {};
+        if (opts.scope)
+            params.scope = opts.scope;
+        const res = await client.get(ROLES_ENDPOINT, { params });
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+const LIST_HELP = `
+Lists the org's role set (6 system roles + any custom roles) — the discovery
+aid for 'p memberships set-role'. Response is 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.
+
+Needs an ORG-admin key: while the granular-permissions rollout is off (the
+production default), the endpoint 403s non-org-admin callers.`;
+export function createRolesCommand() {
+    const cmd = new Command('roles').description('read the org role set (system + custom) for set-role');
+    withAuthFlags(cmd.command('list'))
+        .option('--scope <scope>', 'Filter by scope: instance | organization')
+        .addHelpText('after', LIST_HELP)
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRolesList({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -0,0 +1,17 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export declare const THEME_RETRIEVE_LIMIT = 1000;
+export interface ThemesDeps {
+    client?: AxiosInstance;
+}
+export declare function runThemesList(opts: CommonOpts & {
+    instanceId?: string;
+    withUsage?: boolean;
+    withCanvasIds?: boolean;
+}, deps?: ThemesDeps): Promise<Envelope<unknown>>;
+export declare function runThemesGet(opts: CommonOpts & {
+    id?: string;
+}, deps?: ThemesDeps): Promise<Envelope<unknown>>;
+export declare function createThemesCommand(): Command;

package/dist/src/commands/themes.js

@@ -0,0 +1,82 @@
+import { Command } from 'commander';
+import { clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+import { createCliError } from '../core/errors.js';
+import { emitEnvelope } from '../core/output.js';
+import { withAuthFlags } from './withAuth.js';
+const THEMES_ENDPOINT = '/core/api/protected/themes';
+// Mirror of next-core THEME_RETRIEVE_LIMIT (themes/limits.ts). The list route
+// caps at this many rows (newest-first) with no total/hasMore, so a full page
+// may be silently truncated — we warn when the count equals the cap. Keep this
+// in sync with the server constant: if the server cap changes and this does not,
+// the truncation warning stops firing.
+export const THEME_RETRIEVE_LIMIT = 1000;
+export async function runThemesList(opts, deps = {}) {
+    try {
+        const client = clientFor(opts, deps);
+        const params = {};
+        if (opts.instanceId)
+            params.instance_id = opts.instanceId;
+        // The route compares === 'true' (string); send the literal only when set.
+        if (opts.withUsage)
+            params.used_in_canvases_count = 'true';
+        if (opts.withCanvasIds)
+            params.include_canvas_ids = 'true';
+        const res = await client.get(THEMES_ENDPOINT, { params });
+        const data = res.data;
+        if (Array.isArray(data) && data.length === THEME_RETRIEVE_LIMIT) {
+            const base = `results may be truncated at the server cap of ${THEME_RETRIEVE_LIMIT}`;
+            // Only advise --instance-id when it isn't already narrowing the scope.
+            return ok(data, [opts.instanceId ? base : `${base}; narrow with --instance-id`]);
+        }
+        return ok(data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runThemesGet(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required for themes get');
+        const client = clientFor(opts, deps);
+        const res = await client.get(`${THEMES_ENDPOINT}/${encodeURIComponent(opts.id)}`);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+const LIST_HELP = `
+Themes carry the instance branding you reference when authoring:
+  settings     colors
+  typography   fonts
+  assets, logo branding assets
+
+Notes:
+  - Results are server-capped (newest-first); there is no --limit/--page.
+  - --instance-id narrows to themes bound to that instance and EXCLUDES
+    org-level (default) themes; omit it to see all themes in the org.`;
+export function createThemesCommand() {
+    const cmd = new Command('themes').description('read canvas/branding themes (colors, fonts, assets) for authoring');
+    withAuthFlags(cmd.command('list'))
+        .option('--instance-id <id>', 'Filter to themes bound to this instance (excludes org-level themes)')
+        .option('--with-usage', 'Include a per-theme count of canvases using it')
+        .option('--with-canvas-ids', 'Include the canvas ids using each theme')
+        .addHelpText('after', LIST_HELP)
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runThemesList({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('get'))
+        // --id via .option (not .requiredOption) so a missing id flows through the
+        // in-run guard in runThemesGet and returns a VALIDATION envelope (the agent
+        // contract: envelope + exit code on stdout), rather than commander's plain
+        // parse error + exit 1.
+        .option('--id <id>', 'Theme ID')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runThemesGet({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -0,0 +1,23 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export interface UsersDeps {
+    client?: AxiosInstance;
+}
+export declare function runUsersList(opts: CommonOpts & {
+    instanceId?: string;
+    instanceRole?: string;
+    role?: string;
+    isActive?: boolean;
+    cdg?: string;
+    page?: number;
+    pageSize?: number;
+}, deps?: UsersDeps): Promise<Envelope<{
+    results: unknown[];
+    pagination: Record<string, unknown>;
+}>>;
+export declare function runUsersGet(opts: CommonOpts & {
+    id?: string;
+}, deps?: UsersDeps): Promise<Envelope<unknown>>;
+export declare function createUsersCommand(): Command;

package/dist/src/commands/users.js

@@ -0,0 +1,64 @@
+import { Command } from 'commander';
+import { clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+import { createCliError } from '../core/errors.js';
+import { emitEnvelope } from '../core/output.js';
+import { listPageParams, listPaginationEcho } from '../core/pagination.js';
+import { assertIntFlags } from '../schema/content.js';
+import { withAuthFlags } from './withAuth.js';
+export async function runUsersList(opts, deps = {}) {
+    try {
+        assertIntFlags(opts);
+        const client = clientFor(opts, deps);
+        const params = { ...listPageParams(opts) };
+        if (opts.instanceId)
+            params.instance_id = opts.instanceId;
+        if (opts.instanceRole)
+            params.instance_role = opts.instanceRole;
+        if (opts.role)
+            params.role = opts.role;
+        if (opts.isActive)
+            params.is_active = true;
+        if (opts.cdg)
+            params.content_distribution_groups = opts.cdg;
+        const res = await client.get('/api/v1/users/', { params });
+        return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runUsersGet(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required for users get');
+        const client = clientFor(opts, deps);
+        const res = await client.get(`/api/v1/users/${encodeURIComponent(opts.id)}`);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createUsersCommand() {
+    const cmd = new Command('users').description('read users in the org (read-only)');
+    withAuthFlags(cmd.command('list'))
+        .option('--instance-id <id>', 'Filter to users with a membership in this instance')
+        .option('--instance-role <role>', 'Filter by instance role (requires --instance-id server-side)')
+        .option('--role <role>', 'Filter by org role')
+        .option('--is-active', 'Only users with an active membership')
+        .option('--cdg <id>', 'Filter to members of this content-distribution group')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--page-size <n>', 'Page size (max 500)', (v) => parseInt(v, 10))
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runUsersList({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('get'))
+        .option('--id <id>', 'User ID (integer)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runUsersGet({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",