Ppds Core

PPDS Core — connect, select, stay safe

PPDS (Power Platform Developer Suite) is a single .NET global tool giving you a typed CLI, an MCP server, a TUI, and NuGet libraries over Microsoft Dataverse. One install, no Python, no PAC CLI dependency. Docs: https://joshsmithxrm.github.io/ppds-docs/

dotnet tool install -g PPDS.Cli   # CLI: `ppds`   (update: dotnet tool update -g PPDS.Cli)
dotnet tool install -g PPDS.Mcp   # MCP server: `ppds-mcp-server`

Verify: ppds --version. These skills target the 1.2.0 surface (flag tables generated from 1.2.0 stable). If the installed major/minor differs, prefer live --help.

Surface routing (applies to every ppds-* skill)

The CLI is the primary surface for terminal agents. Use the MCP server instead when either holds:

1. The host has no shell (an MCP-only client), or
2. You want protocol-level session safety the shell cannot give you —

--read-only (all DML rejected for the session) and --allowed-env (environment switching locked to an allowlist). Setup: [references/mcp-server.md](references/mcp-server.md).

Where an MCP tool mirrors a CLI command this package names it, e.g. ppds env list ↔ ppds_env_list. The released server (1.0.0) exposes 41 tools — the authoritative list is [references/mcp-tools.md](references/mcp-tools.md). The CLI surface is wider; anything without an MCP tool routes to the CLI.

Authentication profiles

Profiles are stored per-machine and shared by CLI, MCP server, and TUI. All methods and exact flags: [references/cli-auth.md](references/cli-auth.md).

ppds auth create --name dev                    # interactive browser (default)
ppds auth create --name dev --deviceCode      # headless / SSH / containers
ppds auth create --name ci --applicationId  --clientSecret  --tenant 

Also supported: certificate file/store (--certificateDiskPath / --certificateThumbprint), --managedIdentity, and workload identity federation (--githubFederated, --azureDevOpsFederated).

Manage: ppds auth list, ppds auth select --index (or --name ), ppds auth who, ppds auth update, ppds auth delete, ppds auth clear.

Environment selection

A profile has one selected environment; commands accept per-call overrides. Exact flags: [references/cli-env.md](references/cli-env.md).

ppds env list --filter contoso          # discover (name/URL/ID, partial ok)
ppds env select --environment 
ppds env who                            # identity + selected environment

Per-call override on most commands: --environment (alias -env) and --profile (-p). ppds org ... is an alias for ppds env ....

The safety model — hard rules

These rules are not style; agents must follow them.

1. Know your target before any mutation. Run ppds env who (CLI) or

ppds_auth_who (MCP) and state the environment to the user before the first write of a session. Environments have a configured EnvironmentConfig.Type: Production, Sandbox, Development, Test, Trial, or Unknown. Production gets blocked-by-default DML that requires confirmation with a preview; treat Unknown with the same suspicion.

1. Multi-environment confirmation. When a session has touched more than

one environment, or a command carries an explicit --environment override, restate the exact target (URL, not nickname) and get the user's confirmation before executing any mutation. Cross-environment DML defaults to read-only (cross_env_dml_policy: ReadOnly); a Production target always prompts even when the policy is Allow.

1. Preview before you execute. Most PPDS mutation surfaces have a

--dry-run preview: use it, show the user the result, then execute. ppds query sql --dry-run (DML plan), ppds plugins deploy --dry-run, ppds plugintraces delete --dry-run, and friends. Only add --confirm / --force after a human has seen the preview. Where no --dry-run exists — notably ppds data import, ppds data copy, ppds solutions import — import into a sandbox first and lean on the rule 1–2 confirmation gates; for data moves, ppds data analyze --schema previews dependencies.

1. MCP sessions get pinned. Launch ppds-mcp-server with --read-only

for analysis sessions, and --allowed-env (repeatable) when switching must be possible. No --allowed-env flags means ppds_env_select is disabled — that is a feature, not a bug.

1. Never bypass a refusal. Exit code 9 (Forbidden), exit code 11

(ConfirmationRequired), Query.DmlBlocked, Safety.ShakedownActive — these are answers, not obstacles. Surface them to the user.

Reading PPDS output

• stdout is data, stderr is status. Pipe-safe by design. Parse stdout;

show stderr to humans.

• Machine-readable: add -f json (--output-format Json); CSV is -f csv.
• Quiet/verbose: -q warnings+errors only; -v debug; --debug trace.
• Non-zero exits carry a structured JSON error envelope on stderr with an

error.code like Connection.Throttled. Exit codes 0–11 and per-code agent actions: [references/error-codes.md](references/error-codes.md).

Common mistakes (do not invent these)

| Wrong | Correct | |-------|---------| | ppds env select (positional) | ppds env select --environment — the flag is required | | ppds auth select 1 | ppds auth select --index 1 | | ppds auth login / ppds login | ppds auth create (first time) or ppds auth select (existing) | | ppds env switch | ppds env select --environment | | --format json / --json | -f json / --output-format Json | | pac auth create patterns (e.g. --url) | PPDS is not PAC CLI — check [references/cli-auth.md](references/cli-auth.md) |

Where to go next

| Need | Skill | |------|-------| | SQL / FetchXML queries, DML, explain, history | ppds-query | | Plugin registration, deployment, trace debugging | ppds-plugins | | Solutions, import jobs, env vars, connection refs | ppds-solutions-alm | | Tables, columns, relationships, keys, choices, views, forms | ppds-metadata | | Bulk data export/import/copy/load/delete | ppds-data | | Web resources pull/push/publish | ppds-webresources | | Users, roles, diagnostics | [references/cli-users.md](references/cli-users.md), [references/cli-roles.md](references/cli-roles.md), [references/cli-logs.md](references/cli-logs.md) | | Model-driven apps, data sources/providers, flows | no dedicated skill yet — ppds model-driven-app, ppds data-sources, ppds data-providers, ppds flows, or ppds api request | | Anything else (raw Web API escape hatch) | ppds api request — prefer a typed command when one exists |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: joshsmithxrm
• Source: joshsmithxrm/ppds-skills
• License: MIT

Install and usage instructions live in the source repository linked above.