Operator CLI

The CLI provides a safe path from one non-secret configuration document to a verified MCP connection:

Every command and nested action accepts -h and --help, writes help to stdout, returns status 0, reads no environment or credential, and invokes no operator dependency. Use guildcontrol FAMILY --help for the complete family catalog, guildcontrol FAMILY ACTION --help for one exact action, or guildcontrol help FAMILY ACTION for the same contextual result. Unknown actions and extra arguments remain usage errors even when a help flag is present, so a typo cannot silently select broader documentation.

node dist/bin.js catalog --check
node dist/bin.js catalog --html ./guildcontrol-contract.html
node dist/bin.js preset list
node dist/bin.js preset show server-observer --json
node dist/bin.js preset install server-observer --application-id APPLICATION_ID --guild-id GUILD_ID --html ./guildcontrol-onboarding.html
node dist/bin.js setup --config ./guildcontrol.json --preset server-observer --guild-id GUILD_ID
node dist/bin.js setup --config ./discord-reader.json --preset channel-reader --guild-id GUILD_ID --channel-id CHANNEL_ID
node dist/bin.js setup --config ./guildcontrol.json
node dist/bin.js config validate ./guildcontrol.json
node dist/bin.js config show ./guildcontrol.json
node dist/bin.js config explain capabilities.deletions
node dist/bin.js config init ./mounted-secret.json --name mounted-secret --application-id APPLICATION_ID --bot-id BOT_ID --guild-id GUILD_ID --token-file /run/secrets/discord_bot_token
node dist/bin.js config workbench ./guildcontrol.json --html ./guildcontrol-workbench.html
node dist/bin.js config plan ./guildcontrol.json ./guildcontrol.candidate.json
node dist/bin.js config apply ./guildcontrol.json ./guildcontrol.candidate.json --plan-digest PLAN_DIGEST --confirm ACTIVE_POLICY_NAME
node dist/bin.js recipe list
node dist/bin.js recipe show guild-starter --json
node dist/bin.js recipe plan guild-starter ./guildcontrol.json --guild-id GUILD_ID
node dist/bin.js recipe apply guild-starter ./guildcontrol.json --guild-id GUILD_ID --plan-digest PLAN_DIGEST --confirm guild-starter
node dist/bin.js recipe show guild-builder --json
node dist/bin.js recipe show coordination-channel --json
node dist/bin.js recipe plan coordination-channel ./guildcontrol.json --channel-id CHANNEL_ID
node dist/bin.js recipe apply coordination-channel ./guildcontrol.json --channel-id CHANNEL_ID --plan-digest PLAN_DIGEST --confirm coordination-channel
node dist/bin.js recipe show message-channel --json
node dist/bin.js recipe plan message-channel ./guildcontrol.json --channel-id CHANNEL_ID
node dist/bin.js recipe apply message-channel ./guildcontrol.json --channel-id CHANNEL_ID --plan-digest PLAN_DIGEST --confirm message-channel
node dist/bin.js recipe show direct-messenger --json
node dist/bin.js recipe plan direct-messenger ./guildcontrol.json --user-id EXPECTED_RECIPIENT_USER_ID
node dist/bin.js recipe apply direct-messenger ./guildcontrol.json --user-id EXPECTED_RECIPIENT_USER_ID --plan-digest PLAN_DIGEST --confirm direct-messenger
node dist/bin.js setup --profile observer --preset server-observer --guild-id GUILD_ID
node dist/bin.js setup --profile observer
node dist/bin.js profile list
node dist/bin.js activity --config ./guildcontrol.json --html ./guildcontrol-activity.html
node dist/bin.js coordination list --config ./guildcontrol.json
node dist/bin.js coordination resolve CLAIM_ID --confirm CLAIM_ID --config ./guildcontrol.json
node dist/bin.js doctor --config ./guildcontrol.json
node dist/bin.js doctor --config ./guildcontrol.json --online
node dist/bin.js smoke --config ./guildcontrol.json
node dist/bin.js host --npx --config ./guildcontrol.json --html ./guildcontrol-host-activation.html
node dist/bin.js host plan --npx --config ./guildcontrol.json --adapter mcp-json --host-file ./mcp.json
node dist/bin.js host apply --npx --config ./guildcontrol.json --adapter mcp-json --host-file ./mcp.json --plan-digest PLAN_DIGEST --confirm HOST_SERVER_NAME
node dist/bin.js host --npx --config ./guildcontrol.json --adapter mcp-json --inspect-host-file ./mcp.json

catalog starts a separate credential-free stdio server that reuses the production registrations while disabling all tool execution. It reads no ambient token or policy, constructs no Discord client, opens no Gateway or telemetry exporter, and creates no activity record. Static safety guidance and validated prompts remain inspectable; every listed, invalid, disabled, discovery, or unknown tool call returns the same fixed CATALOG_ONLY result. The production completion capability and every exact binding remain registered. Policy-bound completion returns no identifiers, while the static exact-tool access template completes only public canonical tool names. Add --check to verify the exact tool, prompt, resource, resource-template, and completion identities, every tool schema, risk annotation, and access lifecycle, the static safety guide, tool-access index, canonical tool-name completion, one exact per-tool contract, zero-value policy-completion boundary, and execution guard in process without contacting Discord. Add --json with --check for deterministic machine-readable evidence containing the sorted protocol inventories, access-stage and risk-class accounting, reviewed workflow companions, completion manifest, production toolsets, REST-method totals, a digest of the normalized MCP contract, and separate tool-access and safety-resource digests. Add --html FILE to render the same negotiated snapshot as a guided product tour and searchable standalone explorer with exact schemas, annotations, access contracts, prompts, resources, completion routes, instructions, safety guidance, and toolset, workflow, risk, and access-stage filters. The tour maps package inspection, read-only scope, goal routing, first live read, reviewed plan, approved execution, and ambiguity recovery to required exact prompt and tool declarations; rendering fails if a required declaration or access stage changes without an explicit tour update. It is a workflow map rather than a recorded or simulated Discord result and states which live identity, permission, target, and outcome evidence remains unproven. The HTML export embeds no credential, configured identifier, timestamp, machine path, external asset, or runtime network capability; it uses a restrictive content security policy, is written with private permissions, and refuses to replace an existing path. Its bytes are deterministic for one installed release, so exports from separate installations of the same archive can be compared directly. HTML export may be combined with --check, but not with JSON output. The contract digest includes negotiated server capabilities, the access manifest, the access index, one exact access resource, canonical tool-name completion, and the policy-completion manifest while excluding the package version, timestamp, machine paths, ambient configuration, and configured completion values so equivalent installed contracts can be compared directly across builds.

preset list and preset show NAME inspect deterministic least-privilege setup contracts without a credential, Discord request, Gateway connection, telemetry exporter, profile write, or activity record. Each report includes the exact toolsets and tool names derived from the production catalogs, allowed risk classes, exact scope requirements, bot permission names and decimal bitfield, privileged-intent guidance, disabled Gateway state, and an explicit zero-write assertion.

preset install NAME --application-id ID --guild-id ID turns one of those read-only contracts into a deterministic Discord bot installation plan. Its fixed-origin authorization URL uses only the bot scope, exact preset permissions, a preselected guild, and a locked guild selector. The versioned JSON report explicitly states that no credential was required, no Discord request or browser open occurred, no callback or user token is involved, and Administrator is absent. It prints exact-version npx commands for strict setup with --npx, private host activation, and optional offline validation, online doctor, and read-only smoke, followed by one natural-language first-read request using only list_channels. Add --html FILE for the deterministic standalone guide described in Discord bot setup; human output appends its privacy and digest evidence, while JSON output adds the guide report without changing the installation-plan fields. It does not install the bot by itself or claim that guild role and channel overrides are sufficient until setup verifies the resulting access.

doctor requires --config FILE, --profile NAME, or GUILDCONTROL_CONFIG_FILE. It checks the Node.js version, referenced bot credential, configuration syntax, application and bot identity pins, local allowlists, exact MCP tool surface and toolsets, complete selected-tool access lifecycle coverage, Gateway policy, native Interaction ingress and managed-command policies, observability policy, interaction policy, static rich-embed policy, exact-user private-message audit, delivery, editing, and deletion policies, reaction-user-audit and reaction-moderation policies, member-directory policy, ban-audit policy, guild-prune audit and execution policies, invite-creation, audit, and revocation policies, onboarding-audit and replacement policy, Welcome Screen audit and replacement policy, guild-profile audit and change policies, named guild-settings audit and change policies, guild incident-action audit and change policies, authenticated widget-settings audit, replacement, and public-exposure policies, member-role policy, member voice-audit and change policies, attachment policy, forum-post policy, forum-tag audit and change policies, message-pin policy, announcement-crosspost policy, native message-forwarding and cross-guild policies, announcement-subscription audit and change policies, native-poll audit, voter-audit, creation, and ending policies, webhook administration and webhook-message policies, guild-expression policy, soundboard audit and change policy, scheduled-event inventory, subscriber-audit, and change policies, Stage-instance audit, lifecycle, and notification policies, channel-clone audit and change policies, channel-deletion audit and change policies, channel-metadata policy, permission-overwrite policy, guild-scaffold policy, channel-creation policy, role-creation policy, role-configuration policy, role-deletion audit and change policies, role-order audit and change policies, message-deletion policy, and administration policy. Default human output summarizes pass, warning, and failure totals and then shows only actionable warnings and failures. Add -v or --verbose for every check, or --json for the complete machine-readable report. A clean report exits 0, warnings exit 1, and failures exit 2; the warning headline is ready with warnings because warnings do not make the configuration unusable. The lifecycle check summarizes local, live-read, plan, execution, receipt-verification, and guarded-write stages without granting authority or claiming that any Discord target is ready. Offline checks attempt the selected bot credential but treat a missing environment value or unavailable credential file as a separate failure, then continue inspecting every policy field without substituting diagnostic data into service execution. They inspect the configured private webhook credential root but never read a stored webhook credential. They do not read attachment, soundboard, or cover files, contact Discord, open a Gateway connection, or start telemetry export. Add --online to verify the application, bot identity, Message Content and Guild Members intent flags, and first guild-membership page without listing guild members, guild bans, reaction users, scheduled-event subscribers, invites, onboarding, Welcome Screens, guild profiles, guild settings, guild incident actions, widget settings, announcement subscriptions, webhook messages, private messages, member voice state, soundboard sounds, Stage instances, or channels, estimating or beginning a guild prune, calling anonymous widget routes, reading messages or reasons, opening a Gateway connection, or starting telemetry export. Online verification is skipped without constructing a Discord service when the real selected credential is unavailable. Configured announcement crossposts, message forwarding, Components V2, or static rich embeds make an unconfirmed Message Content intent an online failure. Native Interaction startup separately verifies the outgoing-endpoint state and exact managed-command inventory before the Gateway begins accepting requests.

The offline doctor reports parent-category permission synchronization independently, including its disabled state, missing exact child scope, toolset exposure, or enabled exact-scope and review boundary, without reading channel or overwrite state.

Application linked-role metadata changes appear as a separate doctor check. The check inspects only the capability gate, pinned-application replacement boundary, complete-schema contract, signed-state privacy, durable application-wide coordination, one-shot content-free lifecycle, non-retried write, and exact response plus readback contract. It never reads the verification endpoint or schema and never performs a write. Setup warns when the capability is enabled but the linked-roles toolset is omitted.

Test-entitlement changes and consumable-entitlement consumption appear as separate doctor checks because their capabilities and exact scopes are independent. The offline checks report the selected beneficiary and current-application SKU boundaries, subscription or consumable type contract, receipt-proven deletion or external-fulfillment boundary, hash-only sensitive references, content-free application-wide coordination, non-retried mutation, and exact lifecycle readback without reading the SKU catalog or an entitlement and without performing a write. Setup warns when either capability is enabled but the application-entitlement-changes toolset is omitted.

The offline doctor reports the effective lossless MCP read-response limit and states that oversized reads fail whole while final mutation outcomes remain visible.

Bulk-ban audit and execution appear as separate doctor checks. These checks inspect only the strict local policy, exact guild count, protected-target boundary, toolset exposure, permission contract, complete-set coordination, single-dispatch rule, partial-outcome semantics, and per-target readback contract; they never read a member or ban and never perform a write.

Guild-prune audit and execution also appear as separate doctor checks. These inspect only the strict local policy, exact guild and optional include-role counts, protected-target boundary, configured member ceiling, toolset exposure, permission contract, non-exact privacy boundary, coordination contract, and single-dispatch count-settlement rule. They never request a prune estimate, read a member or role, or begin a prune.

The invite-creation policy check reports disabled, incomplete, or ready state, exact target and private-root counts, required channel permissions, conditional MANAGE_GUILD for exact-user acceptance, explicit finite acceptance, unique intent, exclusive 0600 delivery after verification, and the capability-free MCP and lifecycle boundary without creating a file or contacting Discord.

The voice-channel-status policy check reports disabled, incomplete, or ready state, exact target count, ordinary-voice enforcement, conditional permission proof, the derived privacy-minimized Gateway projection, and its nonprivileged GUILDS intent without querying any status text.

Every non-passing doctor check includes one bounded next action and one package-relative documentation reference in both human and JSON output. Guidance is derived from the stable check ID, so new warning and failure checks receive a safe configuration-review fallback until a narrower recovery path is defined. Passing checks omit recovery fields.

The offline nickname diagnostics report the base self-only gate, exact guild scope, broader other-member gate, protected-user and hierarchy boundary, required CHANGE_NICKNAME or MANAGE_NICKNAMES evidence, signed approval, one-shot execution, and exact readback without reading a member or nickname or contacting Discord.

setup requires one --config FILE or --profile NAME, validates the complete selected policy and local file boundary, performs the same safe online identity check, audits configured against installed guild scope, requires at least one accessible guild inside local scope, and prints a portable credential-free stdio launch descriptor. It is the normal first-run readiness gate, so a completed setup exits 0 while preserving non-blocking warnings in human and JSON output; command, policy, credential, identity, installation, or Discord verification failures exit 2. Without --preset, it loads and verifies an existing policy without rewriting it. With --preset, it creates the selected target after verification or replaces it only with --force. By default the descriptor points at the exact running Node.js executable and CLI entrypoint. Add --npx to use npx --yes guildcontrol@0.1.2 serve as the stable exact-version package launch, or --command COMMAND for an already installed executable that accepts serve; the two choices are mutually exclusive. Every mode selects the same policy, sets no policy values, and names exactly the environment variables and files that must be supplied as secrets. It never includes a bot token or collector header value.

The host generation form requires one explicit --config FILE or --profile NAME and turns the validated non-secret policy into a domain-digested activation plan without resolving a credential, contacting Discord or another network endpoint, starting a process, discovering a host, or changing policy or host configuration. The default descriptor uses the installed Node.js executable and CLI entrypoint. Add --npx for the exact published package version or --command COMMAND for an installed executable; the choices are mutually exclusive. --name NAME changes only the portable server label. The plan binds the pinned public application and bot identities, exact guild and channel read scope, tool surface and toolsets, exact policy selector, ordered stdio launch, named external secret references, an empty inline environment map, required-server behavior, write approval, elicitation, timeouts, and a read-only verification request. --json emits the same structured evidence.

Add --html FILE to exclusively create a mode-0600 standalone activation guide. The page maps portable fields by meaning rather than naming a host, provides copy controls, explains full and progressive tool surfaces, supplies an exact structured smoke fallback and read-only verification request, and makes the missing automation boundaries visible. It includes no credential value, external asset, network capability, external navigation, browser persistence, host writer, or browser launch. It does contain public application and bot IDs, private guild and channel IDs, the exact policy selector, command arguments, and any secret-file paths, so it is a private operator artifact that must not be shared or committed. The artifact cannot validate a host-specific translation or prove how a host implements write approval or elicitation.

Release-exact migration planning

migrate list emits the immutable source catalog for every competitor in the scored local comparison. Each entry names one exact product@version ID, Registry identity, public evidence URL, tagged or version-matching audit fidelity, least-privilege baseline preset, complete public source-tool inventory count and digest, disposition totals, mapping count, source limitations, and manifest digest. Human and --json output are deterministic. The command reads no source checkout, configuration, MCP host setting, environment value, credential, network, Discord endpoint, activity state, or coordination state and changes nothing.

migrate plan SOURCE accepts only a canonical versioned source ID from that catalog. Unversioned aliases, paths, latest, and nearest-version substitution fail closed. Every audited source tool appears in exactly one stable outcome group. A group records its supported, review-required, or intentionally-excluded disposition, canonical target tools, applicable additive recipes, operator instruction, and trust-model change. Supported means the target provides the operator outcome, not that source arguments can be reused or live authority is ready. Review-required exposes a material input, authority, privacy, failure, or recovery difference. Intentionally excluded operations have no target tool or recipe.

Planning negotiates the credential-free production catalog and rejects any mapped target tool absent from it. The report binds the source inventory, normalized manifest, migration catalog, negotiated target contract, mappings, staged commands, limitations, and fixed non-execution disclosures through separate SHA-256 digests. It names the target package version and baseline preset, deduplicates all target tool and recipe routes, and emits exact placeholder commands for catalog inspection, setup, recipe review and application, workbench review, host activation, offline doctor, online doctor, smoke, and deliberate source retirement. Placeholders such as GUILD_ID, CHANNEL_ID, USER_ID, and PLAN_DIGEST are intentionally invalid until replaced by the operator.

Add --html FILE to exclusively create a mode-0600 standalone migration guide. It contains the exact plan, source and target evidence, searchable outcome cards, disposition filters, complete source and target tool chips, recipe routes, copyable commands, limitations, and an in-memory checklist. It embeds no output path or credential value, loads no external asset, makes no automatic request, stores no browser state, opens no browser, and never replaces an existing file. Source and Registry links navigate only when activated. A failed partial write is removed. --html can accompany --json, which then adds the export receipt to the plan.

The planner never scans source text, rewrites a prompt or MCP argument, imports environment policy, creates a target configuration, changes MCP host settings, starts a process, or contacts Discord. It is not a compatibility layer or alternate runtime policy source. Follow the complete migration guide and run the emitted verification before disabling the source deployment. Credential revocation remains an explicit external operator action.

Preset setup requires an exact non-empty guild scope; channel scope may remain empty to inherit the exact guild boundary where the preset permits it. --token-env DISCORD_NAME_TOKEN selects a caller-owned credential variable, while --token-file ABSOLUTE_FILE selects a mounted or otherwise externally managed credential file. The two inputs are mutually exclusive. --force replaces only a target whose saved application and bot identities still match while retaining a recoverable hidden backup. These options are valid only with --preset. Use --profile NAME when private per-user managed storage is preferable; profiles use the same complete policy contract and secret-only launch boundary.

For the safest first connection, add --preset server-observer and repeat --guild-id ID for every intended guild. Optional repeated --channel-id ID values narrow channel access further. This recommended preset exposes only guild metadata, roles, permission diagnostics, connector health, observability state, content-free activity, and exact-tool discovery, so it does not require Message Content intent. Use channel-reader only when bounded message history and native search are needed; it requires at least one exact channel ID and recommends Message Content intent. Channel scope retains the connector's documented child-thread inheritance from an allowlisted parent, and every preset report exposes that fact. Preset setup rejects duplicate, invalid, missing, or excessive scope IDs and any guild scope that is not fully present on the bounded membership-verification page. It disables the Gateway, rejects ambient connector policy, and saves the verified identity, resolved exact scope, credential reference, and toolsets rather than a mutable preset name. Both presets use the full surface and are mechanically rejected if a selected tool ever receives a write risk classification.

Preset setup is intentionally a one-way least-privilege starting point. It cannot enable interaction, administrative, or destructive tools. Add any later capability through the documented exact feature gate, narrower allowlist, Discord permission, and reviewed workflow rather than expecting a preset name to grant it.

recipe list and recipe show NAME inspect immutable additive workflow contracts without reading a file or credential, contacting Discord, constructing a client, opening the Gateway, exporting telemetry, or writing activity. Each descriptor derives its exact canonical tools and risk classes from the production catalogs and reports every capability, feature-scope destination, toolset, Discord permission name and decimal bitfield, privileged intent, Gateway evidence connection and intent, event-feed effect, risk, warning, outer boundary, and scope-input limit. Recipes are write-capable policy expansions, unlike the intentionally read-only setup presets, but they grant no Discord authority and bypass none of the underlying workflow gates.

recipe plan NAME FILE reads one protected schema-v2 document, validates its complete cross-field policy with placeholders, and applies only the recipe's declared additive capabilities, exact scope IDs, and canonical toolsets in memory. It preserves identity, credential references, outer read scope, all existing capabilities and feature scopes, Gateway behavior, limits, storage, runtime, and observability. The report includes the complete proposed non-secret document, current and proposed document digests, exact path-level changes, normalized request, recipe contract digest, permissions, intents, risks, warnings, and structured offline-validation, online-doctor, and smoke commands. It also emits one immutable applyCommand as a shell-neutral command plus args array containing the canonical file path, normalized exact scope, fresh plan digest, and required confirmation. An operator or compatible host can review and execute that argv without reconstructing approval inputs or quoting a path. It reads no secret value and contacts no Discord endpoint.

recipe apply NAME FILE recomputes that complete plan and requires both --plan-digest DIGEST and --confirm NAME to match exactly. The digest binds the normalized absolute file path, current and proposed canonical documents, exact recipe and scope request, descriptor contract, changes, and warnings. The atomic writer compares the reviewed source again inside its exclusive file lock, rejects any semantic concurrent change or removal, keeps application and bot identity pinned, publishes and verifies the exact proposed document, and retains a recoverable hidden backup. An already-current application is a no-write, no-backup result. Application still reads no secret value and contacts no Discord endpoint.

guild-starter is the narrower setup path for the bundled deterministic layouts. It enables only guild-blueprints, additive guild scaffolds, exact-guild channel-order audit and change, and named guild-settings audit and change for each selected guild. It preserves the live guild name; optional guildName input remains blocked until guild-profile audit and change plus the exact profile scope are separately reviewed and added. The recipe requests View Channel, Manage Channels, Manage Guild, and the nonprivileged GUILDS layout-evidence intent, but not Manage Roles, Administrator, or a privileged intent. The compiler itself creates no role, and its channel chains order only categories and children already known to share one parent. The shared scaffold and ordering capabilities do not restrict a separately authored custom manifest to starter output: an existing Manage Roles bot grant could still satisfy a role-creation frontier, and an explicitly acknowledged custom channel chain could reparent a compatible existing channel. Retain the compiled request and least-privilege bot permissions. The recipe leaves Community, Welcome Screen, onboarding, AutoMod, publications, exact existing-role or channel-metadata convergence, role ordering, and permission overwrites disabled. Information channels remain ordinary public text channels until their exact created IDs receive separately configured and reviewed overwrites. The derived layout connection does not enable the content-free event feed. Recipe planning and application do not open the connection or contact Discord.

guild-builder enables guild-blueprints, two-pass live blueprint capture, guild scaffold, exact-guild channel-order audit and changes, guild-profile audit and changes, named guild-settings audit and changes, monotonic Community audit and changes, complete Welcome Screen audit and replacement, complete onboarding audit and replacement, and AutoMod audit plus reviewed changes. Every selected guild must already be inside readScope.guildIds; its ID is added to the corresponding feature scopes, including scopes.channelOrderingGuildIds, scopes.guildCommunityGuildIds, and scopes.automodGuildIds. The recipe requires View Channel, Manage Channels, Manage Guild, and Manage Roles and requests no privileged intent. It never grants Administrator: first-time Community enablement needs temporary guild ownership or complete Administrator authority, while routing-only changes need Manage Guild; remove temporary Administrator immediately after that frontier. It deliberately omits Moderate Members, which is additionally required only for manifests containing timeout actions, and never infers scopes.automodAlertChannelIds; add each content-bearing alert destination only after its exact Discord channel ID is known. It also cannot infer existing role or channel mutation targets, so it does not enable capabilities.roleConfiguration or capabilities.channelMetadataChanges and does not populate their exact scope arrays; add those through separately reviewed configuration when the manifest uses exact convergence phases. Guild-settings, Community, and onboarding evidence cause the resulting runtime to derive a privacy-minimized GUILDS-only layout connection for those exact guilds even when gateway.enabled remains false; the content-free event feed stays disabled unless it was already enabled. Planning, capture, and application never open that connection. The recipe deliberately excludes static publications until exact channel scope is configured separately.

coordination-channel enables only the coordination toolset and interaction capability, then adds selected exact channels to scopes.interactionChannelIds. It reports View Channel, Send Messages, Read Message History, and Send Messages in Threads, with no privileged intent, Gateway evidence connection, general message tools, reaction tools, Components V2, rich embeds, Add Reactions, or Embed Links. A nonempty readScope.channelIds is an enforced outer allowlist; an empty outer channel list retains the documented all-visible-channels-inside-the-configured-guild boundary and produces an explicit offline warning. Exact notification users remain a separate policy decision. Aggregate reaction status remains unavailable unless the interactions toolset is selected separately, and reaction-user audit or moderation still needs its own capability. Recipe planning and application contact no Discord service.

message-channel is the least-privilege ordinary write path. It enables only the message-writes toolset and interaction capability, adds selected exact channels to scopes.interactionChannelIds, and exposes send_message, edit_own_message, and signal_command_processing alongside local discovery. It reports View Channel, Send Messages, Read Message History, and Send Messages in Threads, with no privileged intent, Gateway evidence connection, general message reads, reactions, Components V2, embeds, Add Reactions, or Embed Links. Discord's documented app-authored-message exception allows the connector to verify its own created or edited content without Message Content. Recipe plan and apply are the one-time offline authority review. Once the host reloads the applied policy, sends and connector-owned edits require only ordinary MCP host write approval; they do not use a Discord-content plan, signed elicitation, or destructive confirmation. Exact scope, mention suppression, nonce replay protection, shared anti-spam limits, authorship checks, and fresh readback still apply.

channel-publisher composes the messages, message-writes, interactions, and embed-messages toolsets plus the interaction and static rich-embed capabilities, then adds selected exact channels to both scopes.interactionChannelIds and scopes.embedMessageChannelIds. It reports Add Reactions, View Channel, Embed Links, Send Messages, Read Message History, and Send Messages in Threads plus required Message Content intent for the bundled content-dependent publication workflows. It adds no Gateway evidence connection and preserves the configured event-feed policy. Mentions remain suppressed unless exact notification users are configured separately. The recipe does not enable reaction-user audit or reaction moderation, even though their tools share the selected interaction toolset and remain independently policy-gated. Static rich embeds remain a separately reviewed workflow and share only the process-local interaction rate budget.

incident-response enables only capabilities.guildIncidentAudit, capabilities.guildIncidentChanges, the exact selected IDs in scopes.guildIncidentGuildIds, and the guild-incidents toolset. Every selected guild must already be inside readScope.guildIds. The recipe reports Manage Guild, requests no privileged intent, adds no Gateway evidence connection, and leaves every other capability, scope, toolset, and event-feed setting unchanged. Planning and application read no credential, contact no Discord endpoint, and do not change incident state; the resulting policy merely makes the separately reviewed workflow available.

direct-messenger enables exactly capabilities.directMessageAudit, capabilities.directMessageDelivery, capabilities.directMessageEditing, and capabilities.directMessageDeletion, adds each selected ordinary user ID to scopes.directMessageUserIds, and adds only the direct-messages toolset. It does not enable capabilities.directMessageAttachments or add an attachment root because local-file disclosure requires a separate operator decision. Its scope is independent of guild and channel read scope. The descriptor reports no guild permission, privileged intent, or Gateway evidence connection. It warns that exact user scope is not proof of consent or Discord-side delivery eligibility, that private text, static component layouts, previews, and review text are transient, and that approved mutations remain fixed-rate, one-shot, non-retried operations. Recipe planning and application do not fetch a user, open a DM channel, or otherwise contact Discord.

Recipes compose additively. Apply guild-starter to an existing read-only policy for a bundled public layout, or choose the broader guild-builder only when its Community, onboarding, Welcome Screen, AutoMod, and requested Manage Roles authority is intended. Apply message-channel, coordination-channel, or channel-publisher only after the target channel's exact Discord ID is known; choose message-channel for ordinary plain-text writes, coordination for strict directed notes, and publisher only for the broader read, reaction, Components V2, or embed surface. Apply incident-response independently whenever an existing exact guild needs the time-bounded lockdown workflow. Apply direct-messenger only after identifying each exact user who expects private contact. None of these recipes depends on another unless its own descriptor says so. No recipe removes or disables existing policy, infers a channel or user from a name, edits the Discord application or bot role, grants Administrator, or provides an environment-policy compatibility path.

profile list and profile show NAME inspect saved contracts without reading a credential, contacting Discord, opening the Gateway, or starting telemetry. profile remove NAME --confirm NAME moves one validated profile into private recoverable trash and leaves its external credential active. profile restore NAME --confirm NAME restores the newest valid generation only when the active name is absent. Add --json to any profile lifecycle command for a versioned path-free report.

activity requires --config FILE, --profile NAME, or GUILDCONTROL_CONFIG_FILE so it can inspect the selected policy's activity-state root. It reads a bounded newest-first window of strict content-free activity records and the complete durable-claim inventory without resolving a credential, constructing a Discord client, opening the Gateway, starting telemetry, or changing activity or coordination state. Records with one activity ID form a lifecycle: only the newest is current and older pending or intermediate records remain visible as superseded history. Completed and no-op current records are settled; accepted or pending records remain pending; uncertain results remain uncertain; failures, drift, and every unrecognized terminal status require review. Durable claims correlate to an activity only when both its keyed operation hash and plan digest match, which prevents an identifier coincidence from being presented as recovery evidence. Claims without a match in the bounded activity window remain visible and explicitly counted instead of being silently dropped.

The human report includes exact content-free entries, claim IDs, bounded Discord targets, owner liveness, receipt state, and fixed next actions. --json returns the same path-free digest-bound report. Its independent-local-reads consistency marker makes clear that the digest binds the collected evidence but does not claim one globally locked instant across the append-only journal and claim directories. --html FILE exclusively creates the requested private standalone explorer with current-disposition and operation-kind filters, exact evidence, and copy controls; that output file is the only state created. It embeds no credential, content, local path, external asset, network capability, navigation, or browser storage and refuses to replace an existing file. The artifact is evidence only and cannot retry an operation or resolve a claim. Exit status is 0 only when every current lifecycle in the bounded window is settled, no review-required claim exists, and no recent non-empty line was skipped; status 1 preserves the complete report when operator attention is needed. Increase --limit within the connector's fixed activity bound when earlier lifecycle context is relevant.

coordination list requires --config FILE, --profile NAME, or GUILDCONTROL_CONFIG_FILE so it can identify the selected policy's activity-state root. It inspects that non-secret document without resolving a Discord credential, opening the Gateway, starting telemetry, or constructing a Discord client. It reports only content-free claim identity, bounded exact targets, owner liveness, receipt state, and whether the next writer may reclaim automatically or operator review is required. For a quarantined claim, stop the owning connector process, inspect the exact Discord state and audit log, then run coordination resolve CLAIM_ID --confirm CLAIM_ID with the same selection. Resolution writes an immutable content-free acknowledgement before releasing the exact claim and never removes or reopens the old operation receipt or operation key. Add --json for a versioned report. Never use coordination state on a network filesystem or assume that separate activity-state roots coordinate with one another.

smoke requires --config FILE, --profile NAME, or GUILDCONTROL_CONFIG_FILE. It launches the current CLI executable and entrypoint as a real serve child with that exact selection, connects the official MCP client over operating-system stdio, pins stable MCP protocol version 2026-07-28, and reports the negotiated transport, protocol, server name, and server version. The child receives only the MCP SDK's safe process baseline, the selected non-secret configuration-file variable when applicable, and exact secret environment values named by the policy. Its bounded stderr tail is sanitized and redacted before a startup failure reaches the operator.

After startup, the command validates the configured tool, resource, resource-template, and prompt catalogs, checks every exposed tool's complete risk annotations, and exercises local discovery. Its report partitions every negotiated tool into exhaustive sorted read-only and write-capable inventories, then identifies destructive tools as an explicit subset of the write-capable inventory. For a progressive surface, it reveals every configured toolset inside the temporary server and verifies the resulting exact tools. Identity verification uses get_connector_status when the connector toolset is exposed and the same read-only service status path otherwise, and rejects an obsolete schema, missing or altered privacy evidence, mutable profile text, or a local activity path in that result. These checks do not list Discord channels, read guild settings, guild incident actions, widget settings, or messages, call anonymous widget routes, or write to Discord. Because the child follows normal serve startup, any Gateway, native Interaction, local-state, or telemetry runtime selected by the policy can start and is shut down when the check finishes; smoke is a real startup proof, not an offline check.

Add --json to setup, host, migrate, doctor, smoke, activity, config commands, preset commands, recipe commands, coordination commands, or a profile lifecycle command, or use it with catalog --check, for a versioned machine-readable report. When a JSON-requested command fails, it emits one redacted error document to stdout with a stable category, message, recovery action, documentation reference, retry boundary, and optional Discord retry delay; stderr stays empty. Human failures print the same action and reference after the concise error. Neither form includes credentials, headers, response bodies, remote routes, local paths, stacks, causes, or arbitrary environment values.

CLI exit status is 0 for clean success, 1 for success with warnings or failure to start a long-running stdio server or catalog process, and 2 for invalid usage, a failed doctor check, or a failed bounded operator command. A warning-only doctor or setup report remains fully readable but returns 1 so automation cannot mistake a degraded boundary for a clean result.

Run node dist/bin.js help for the complete command summary.

Canonical source: docs/reference.md