@ppdostudio/ppdo-cli 0.0.0-stage → 1.0.0-beta.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +54 -0
- package/LICENSE +114 -0
- package/README.md +330 -2
- package/THIRD-PARTY-NOTICES +25 -0
- package/dist/bin.js +5 -0
- package/dist/chunks/ado-NLCWVIVQ.js +103 -0
- package/dist/chunks/api-T5SWGOFX.js +2 -0
- package/dist/chunks/api-YKKPVMTX.js +2 -0
- package/dist/chunks/auth-IP7AOWSF.js +6 -0
- package/dist/chunks/azCli-T67ZMIC3.js +2 -0
- package/dist/chunks/batch-GCXLGQET.js +4 -0
- package/dist/chunks/build-XDCWMEEL.js +4 -0
- package/dist/chunks/bulk-5QO343HO.js +2 -0
- package/dist/chunks/chunk-3C3GSN3J.js +2 -0
- package/dist/chunks/chunk-4S5ETLH4.js +2 -0
- package/dist/chunks/chunk-5KZDCOFA.js +8 -0
- package/dist/chunks/chunk-5SBBTR3Y.js +2 -0
- package/dist/chunks/chunk-5UOZCXQF.js +5 -0
- package/dist/chunks/chunk-BALEFXOL.js +29 -0
- package/dist/chunks/chunk-BWZ6HZXM.js +2 -0
- package/dist/chunks/chunk-C42MGXRN.js +2 -0
- package/dist/chunks/chunk-GE3XBV3K.js +2 -0
- package/dist/chunks/chunk-GT52BRS2.js +194 -0
- package/dist/chunks/chunk-HLE2WURE.js +2 -0
- package/dist/chunks/chunk-J4R6QXW7.js +2 -0
- package/dist/chunks/chunk-J777TCSE.js +4 -0
- package/dist/chunks/chunk-JAGU2NM5.js +2 -0
- package/dist/chunks/chunk-JEAIFLEN.js +51 -0
- package/dist/chunks/chunk-JGLUQBCK.js +2 -0
- package/dist/chunks/chunk-MME53RWW.js +4 -0
- package/dist/chunks/chunk-MTF66YXU.js +2 -0
- package/dist/chunks/chunk-NNHEYYF5.js +2 -0
- package/dist/chunks/chunk-OP6EXLWQ.js +5 -0
- package/dist/chunks/chunk-PDFXH652.js +2 -0
- package/dist/chunks/chunk-QE4DELWW.js +2 -0
- package/dist/chunks/chunk-QMTPHZLQ.js +2 -0
- package/dist/chunks/chunk-RHQP7X6H.js +3 -0
- package/dist/chunks/chunk-S4KF5Z3S.js +10 -0
- package/dist/chunks/chunk-TQLZ3TRU.js +2 -0
- package/dist/chunks/chunk-TZSB4PR7.js +4 -0
- package/dist/chunks/chunk-UCTMKA2J.js +4 -0
- package/dist/chunks/chunk-UKKSN4F7.js +3 -0
- package/dist/chunks/chunk-UWFDJKOJ.js +2 -0
- package/dist/chunks/chunk-UYDBLVAM.js +2 -0
- package/dist/chunks/chunk-WIA546AL.js +13 -0
- package/dist/chunks/chunk-WXCLWAE2.js +2 -0
- package/dist/chunks/chunk-WXOTXJNG.js +3 -0
- package/dist/chunks/chunk-X7VWUI6N.js +2 -0
- package/dist/chunks/chunk-XL7E7LX5.js +3 -0
- package/dist/chunks/chunk-ZHHVG47C.js +2 -0
- package/dist/chunks/chunk-ZNJ4DRCA.js +2 -0
- package/dist/chunks/chunk-ZUXLC5VX.js +2 -0
- package/dist/chunks/commands-GHYN6GZT.js +2 -0
- package/dist/chunks/component-PAASRIK6.js +2 -0
- package/dist/chunks/components-LRHXR5HR.js +2 -0
- package/dist/chunks/config-JN3I5EII.js +2 -0
- package/dist/chunks/connection-IWFELK5W.js +2 -0
- package/dist/chunks/connref-ZDY7JYK5.js +2 -0
- package/dist/chunks/customizations-IE2KO275.js +7 -0
- package/dist/chunks/dependency-EFDSIKSN.js +3 -0
- package/dist/chunks/discovery-XXVLVHD6.js +2 -0
- package/dist/chunks/dist-ILNYGTM2.js +136 -0
- package/dist/chunks/dv-3OESFBNW.js +192 -0
- package/dist/chunks/env-MZPI3UA2.js +5 -0
- package/dist/chunks/environment-NUQHU74A.js +2 -0
- package/dist/chunks/environments-WMBLSAQF.js +2 -0
- package/dist/chunks/envvar-YN35IDWJ.js +2 -0
- package/dist/chunks/esm-Z4QMBGAD.js +2 -0
- package/dist/chunks/fanout-DUP5CD5X.js +2 -0
- package/dist/chunks/fetchxml-ONTNTA6Z.js +6 -0
- package/dist/chunks/functions-K5TYRB2C.js +2 -0
- package/dist/chunks/graph-JI23YQB5.js +5 -0
- package/dist/chunks/group-DKEPSVRV.js +6 -0
- package/dist/chunks/history-SNSJRV6B.js +2 -0
- package/dist/chunks/identity-OW4WCDOA.js +2 -0
- package/dist/chunks/jobs-PXNJFWWF.js +2 -0
- package/dist/chunks/lifecycle-7RMWV26J.js +2 -0
- package/dist/chunks/main-ZVIKC3VA.js +4 -0
- package/dist/chunks/metadata-74WGGOV5.js +2 -0
- package/dist/chunks/metadataCreate-W3NDI5FB.js +2 -0
- package/dist/chunks/msalUser-JRNX5HPO.js +2 -0
- package/dist/chunks/names-SFYZQY6Q.js +2 -0
- package/dist/chunks/pack-2UDE25IY.js +2 -0
- package/dist/chunks/pipelines-O3OYNCHT.js +4 -0
- package/dist/chunks/plan-ALLKT2QZ.js +2 -0
- package/dist/chunks/plugins-EUDJ7QIS.js +4 -0
- package/dist/chunks/policies-KVPQVUHS.js +2 -0
- package/dist/chunks/pools-7H2L4QJC.js +2 -0
- package/dist/chunks/process-G7LCTGKS.js +2 -0
- package/dist/chunks/project-HSZLY2AY.js +2 -0
- package/dist/chunks/projects-BHG2B4IX.js +4 -0
- package/dist/chunks/protect-WZO3MAHF.js +2 -0
- package/dist/chunks/provider-VXRAQRN2.js +2 -0
- package/dist/chunks/prs-NOXIZ7AT.js +2 -0
- package/dist/chunks/records-TN7ZKUJ7.js +2 -0
- package/dist/chunks/run-BXFENCN6.js +2 -0
- package/dist/chunks/run-F6H4QCWR.js +2 -0
- package/dist/chunks/run-HBQCSGYY.js +3 -0
- package/dist/chunks/run-JYU5BTWN.js +2 -0
- package/dist/chunks/run-MGLIIM7Z.js +3 -0
- package/dist/chunks/run-MHM3GTGH.js +2 -0
- package/dist/chunks/run-SRQPP6N3.js +3 -0
- package/dist/chunks/run-ZNDSC7LR.js +2 -0
- package/dist/chunks/runtime-VOF7XYXW.js +2 -0
- package/dist/chunks/security-FLEAZ4EA.js +2 -0
- package/dist/chunks/service-4PIAYFYF.js +2 -0
- package/dist/chunks/service-V2TQEEID.js +2 -0
- package/dist/chunks/services-B6V4VVX5.js +2 -0
- package/dist/chunks/skills-GD6Z6P3R.js +2 -0
- package/dist/chunks/solution-HF57MP27.js +2 -0
- package/dist/chunks/solutionExport-TLGHMUM5.js +2 -0
- package/dist/chunks/solutionfiles-P223QW2J.js +2 -0
- package/dist/chunks/spn-AIUWML5R.js +2 -0
- package/dist/chunks/tokenCache-3LMJRUTI.js +2 -0
- package/dist/chunks/unpack-XZLTBUGC.js +2 -0
- package/dist/chunks/users-KFAPPGF4.js +2 -0
- package/dist/chunks/vargroups-33EZAHGZ.js +2 -0
- package/dist/chunks/whoami-ULK5UMZV.js +2 -0
- package/dist/chunks/workitems-YGES6KKN.js +2 -0
- package/dist/chunks/xmldoc-B2HUNTVK.js +2 -0
- package/package.json +55 -4
- package/schema/ppdo-cli.schema.json +120 -0
- package/skills/README.md +12 -0
- package/skills/ppdo-cli/SKILL.md +84 -0
- package/skills/ppdo-cli-dataverse/SKILL.md +302 -0
- package/skills/ppdo-cli-devops/SKILL.md +150 -0
package/package.json
CHANGED
|
@@ -1,6 +1,57 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ppdostudio/ppdo-cli",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.0-beta.0",
|
|
4
|
+
"description": "Power Platform DevOps Studio CLI: Dataverse and Azure DevOps for agents and people",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"power-platform",
|
|
7
|
+
"dataverse",
|
|
8
|
+
"azure-devops",
|
|
9
|
+
"cli",
|
|
10
|
+
"agents",
|
|
11
|
+
"dynamics-365",
|
|
12
|
+
"power-apps",
|
|
13
|
+
"claude-code",
|
|
14
|
+
"github-copilot"
|
|
15
|
+
],
|
|
16
|
+
"license": "SEE LICENSE IN LICENSE",
|
|
17
|
+
"author": "Dylan Haskins and Ryan James",
|
|
18
|
+
"homepage": "https://powerplatformdevops.studio/",
|
|
19
|
+
"repository": {
|
|
20
|
+
"type": "git",
|
|
21
|
+
"url": "git+https://github.com/PPDOStudio/ppdo-cli-release.git"
|
|
22
|
+
},
|
|
23
|
+
"bugs": {
|
|
24
|
+
"url": "https://github.com/PPDOStudio/ppdo-cli-release/issues"
|
|
25
|
+
},
|
|
26
|
+
"type": "module",
|
|
27
|
+
"bin": {
|
|
28
|
+
"ppdo-cli": "dist/bin.js"
|
|
29
|
+
},
|
|
30
|
+
"files": [
|
|
31
|
+
"dist",
|
|
32
|
+
"skills",
|
|
33
|
+
"schema",
|
|
34
|
+
"CHANGELOG.md",
|
|
35
|
+
"THIRD-PARTY-NOTICES"
|
|
36
|
+
],
|
|
37
|
+
"scripts": {
|
|
38
|
+
"build": "node scripts/bundle.mjs",
|
|
39
|
+
"typecheck": "tsc --noEmit",
|
|
40
|
+
"test": "vitest run"
|
|
41
|
+
},
|
|
42
|
+
"devDependencies": {
|
|
43
|
+
"@azure/msal-node": "^5.3.1",
|
|
44
|
+
"@types/node": "^24.0.0",
|
|
45
|
+
"commander": "^14.0.0",
|
|
46
|
+
"esbuild": "^0.27.4",
|
|
47
|
+
"fflate": "^0.8.2",
|
|
48
|
+
"typescript": "^5.6.0",
|
|
49
|
+
"vitest": "^3.2.7"
|
|
50
|
+
},
|
|
51
|
+
"engines": {
|
|
52
|
+
"node": ">=22.12.0"
|
|
53
|
+
},
|
|
54
|
+
"optionalDependencies": {
|
|
55
|
+
"@azure/msal-node-extensions": "^5.6.1"
|
|
56
|
+
}
|
|
57
|
+
}
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"title": "ppdo-cli config",
|
|
4
|
+
"description": "config.json for ppdo-cli: identities (accounts), groups (an identity and a mode) and environments (one Dataverse URL or one DevOps project, in exactly one group). The identity, group and env commands write this file; prefer them, because they check the rules and ask a person before anything gains a wider mode.",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"additionalProperties": false,
|
|
7
|
+
"properties": {
|
|
8
|
+
"$schema": {
|
|
9
|
+
"type": "string",
|
|
10
|
+
"description": "Optional link to this schema, for editors. Kept when ppdo-cli rewrites the file."
|
|
11
|
+
},
|
|
12
|
+
"current-dataverse": {
|
|
13
|
+
"type": "string",
|
|
14
|
+
"description": "The default environment for dv commands, by name (ppdo-cli env use <name>)."
|
|
15
|
+
},
|
|
16
|
+
"current-devops": {
|
|
17
|
+
"type": "string",
|
|
18
|
+
"description": "The default environment for ado commands, by name (ppdo-cli env use <name>)."
|
|
19
|
+
},
|
|
20
|
+
"output": {
|
|
21
|
+
"type": "string",
|
|
22
|
+
"enum": ["json", "ndjson", "table", "tsv"],
|
|
23
|
+
"description": "The default output format. -o and PPDEVOPS_OUTPUT win over it."
|
|
24
|
+
},
|
|
25
|
+
"identities": {
|
|
26
|
+
"type": "object",
|
|
27
|
+
"description": "Accounts, by name. Each is one account in one tenant.",
|
|
28
|
+
"propertyNames": { "$ref": "#/$defs/name" },
|
|
29
|
+
"additionalProperties": { "$ref": "#/$defs/identity" }
|
|
30
|
+
},
|
|
31
|
+
"groups": {
|
|
32
|
+
"type": "object",
|
|
33
|
+
"description": "Groups, by name. A group gives its environments one identity and one mode.",
|
|
34
|
+
"propertyNames": { "$ref": "#/$defs/name" },
|
|
35
|
+
"additionalProperties": { "$ref": "#/$defs/group" }
|
|
36
|
+
}
|
|
37
|
+
},
|
|
38
|
+
"$defs": {
|
|
39
|
+
"name": {
|
|
40
|
+
"type": "string",
|
|
41
|
+
"pattern": "^[a-z0-9][a-z0-9_-]*$",
|
|
42
|
+
"description": "Lowercase letters, digits, '-' and '_', starting with a letter or digit."
|
|
43
|
+
},
|
|
44
|
+
"identity": {
|
|
45
|
+
"type": "object",
|
|
46
|
+
"additionalProperties": false,
|
|
47
|
+
"required": ["tenant"],
|
|
48
|
+
"properties": {
|
|
49
|
+
"tenant": {
|
|
50
|
+
"type": "string",
|
|
51
|
+
"description": "Entra tenant id or domain, for example contoso.onmicrosoft.com."
|
|
52
|
+
},
|
|
53
|
+
"username": {
|
|
54
|
+
"type": "string",
|
|
55
|
+
"description": "The account to sign in as (UPN). Required for browser, broker and device_code; a sign-in as anyone else is refused."
|
|
56
|
+
},
|
|
57
|
+
"method": {
|
|
58
|
+
"type": "string",
|
|
59
|
+
"enum": ["broker", "browser", "device_code", "az_cli", "spn"],
|
|
60
|
+
"default": "browser",
|
|
61
|
+
"description": "How to sign in: browser, broker (Windows single sign-on), device_code, az_cli (the Azure CLI's sign-in) or spn (a service principal)."
|
|
62
|
+
},
|
|
63
|
+
"client_id": {
|
|
64
|
+
"type": "string",
|
|
65
|
+
"description": "The app (client) id. For spn, the service principal's id. Otherwise it defaults to the Azure CLI's public client; set it only to sign in through your own app registration."
|
|
66
|
+
},
|
|
67
|
+
"config_dir": {
|
|
68
|
+
"type": "string",
|
|
69
|
+
"description": "az_cli only: the AZURE_CONFIG_DIR to use, so this identity has its own az login."
|
|
70
|
+
},
|
|
71
|
+
"secret_env": {
|
|
72
|
+
"type": "string",
|
|
73
|
+
"description": "spn only: the name of the environment variable that holds the client secret. The secret itself is never stored."
|
|
74
|
+
},
|
|
75
|
+
"certificate": {
|
|
76
|
+
"type": "string",
|
|
77
|
+
"description": "spn only, instead of secret_env: a PEM file with the private key and the certificate, or a PFX/P12 file without a password."
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
},
|
|
81
|
+
"group": {
|
|
82
|
+
"type": "object",
|
|
83
|
+
"additionalProperties": false,
|
|
84
|
+
"properties": {
|
|
85
|
+
"identity": {
|
|
86
|
+
"type": "string",
|
|
87
|
+
"description": "The identity every environment in the group uses."
|
|
88
|
+
},
|
|
89
|
+
"mode": {
|
|
90
|
+
"type": "string",
|
|
91
|
+
"enum": ["read-only", "read-write", "full"],
|
|
92
|
+
"default": "read-only",
|
|
93
|
+
"description": "How much agents may change: read-only (reads, plus POSTs that only read), read-write (everything except deletes) or full."
|
|
94
|
+
},
|
|
95
|
+
"environments": {
|
|
96
|
+
"type": "object",
|
|
97
|
+
"description": "Environments, by name. An environment name is used in one group only, and a URL or project belongs to one environment only.",
|
|
98
|
+
"propertyNames": { "$ref": "#/$defs/name" },
|
|
99
|
+
"additionalProperties": { "$ref": "#/$defs/environment" }
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
},
|
|
103
|
+
"environment": {
|
|
104
|
+
"type": "object",
|
|
105
|
+
"additionalProperties": false,
|
|
106
|
+
"description": "One Dataverse environment or one DevOps project: exactly one of dataverse or devops.",
|
|
107
|
+
"oneOf": [{ "required": ["dataverse"] }, { "required": ["devops"] }],
|
|
108
|
+
"properties": {
|
|
109
|
+
"dataverse": {
|
|
110
|
+
"type": "string",
|
|
111
|
+
"description": "The Dataverse environment URL, for example https://contoso.crm.dynamics.com."
|
|
112
|
+
},
|
|
113
|
+
"devops": {
|
|
114
|
+
"type": "string",
|
|
115
|
+
"description": "<organization>/<project>, for example contoso/platform."
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
}
|
package/skills/README.md
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Bundled agent skills
|
|
2
|
+
|
|
3
|
+
`ppdo-cli skills install` copies (or with `--link`, links) every sub-folder of
|
|
4
|
+
this folder that holds a `SKILL.md` into an agent's skill folder.
|
|
5
|
+
|
|
6
|
+
Each skill's `name:` must match its folder, and together the skills must list
|
|
7
|
+
every `dv`, `ado`, `graph` and `whoami` command with each of its own options
|
|
8
|
+
(`test/skills.test.ts` checks both). When a command or option changes, update
|
|
9
|
+
the skill that lists it in the same change.
|
|
10
|
+
|
|
11
|
+
This folder ships with the package (`files` in package.json) and is found from
|
|
12
|
+
the bundle's own location, so keep it next to package.json.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ppdo-cli
|
|
3
|
+
description: Use the ppdo-cli CLI to reach Dataverse and Azure DevOps. Load before any ppdo-cli command - covers checking the account and environment, safety modes, exit codes, output, and the raw api fallback.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# ppdo-cli
|
|
7
|
+
|
|
8
|
+
`ppdo-cli` calls Dataverse (`ppdo-cli dv …`), Azure DevOps (`ppdo-cli ado …`) and Microsoft Graph (`ppdo-cli graph …`) with sign-in, retries, paging and errors handled. Output is JSON on stdout; errors are one JSON object on stderr.
|
|
9
|
+
|
|
10
|
+
## Before anything else
|
|
11
|
+
|
|
12
|
+
1. Run `ppdo-cli whoami`. For each service it shows the environment, its group and mode, and the account.
|
|
13
|
+
2. Check the mode against your plan. If the task needs a write in a `read-only` environment, or a delete outside `full`, tell the user **before** you start, not halfway through.
|
|
14
|
+
3. Tell the user which environment and account you are about to use before you change anything.
|
|
15
|
+
4. If a command exits 3, ask the user to run the `ppdo-cli auth login …` command from the hint. Never try to sign in yourself.
|
|
16
|
+
|
|
17
|
+
## Which skill
|
|
18
|
+
|
|
19
|
+
- Anything in Dataverse (data, metadata, solutions and source folders, and why something failed or changed), and Entra groups (`graph group`): ppdo-cli-dataverse.
|
|
20
|
+
- Repos, pull requests, work items, pipelines, and a failed pipeline run: ppdo-cli-devops.
|
|
21
|
+
|
|
22
|
+
When no command fits, `ppdo-cli dv api` and `ppdo-cli ado api` call any endpoint with auth, retries and paging handled (options in those skills).
|
|
23
|
+
|
|
24
|
+
## Modes
|
|
25
|
+
|
|
26
|
+
Each environment's mode comes from its group and limits what runs:
|
|
27
|
+
|
|
28
|
+
- `read-only`: reads, plus POSTs that only read (a `$batch` of GETs, solution export, a WIQL query).
|
|
29
|
+
- `read-write`: everything except deletes.
|
|
30
|
+
- `full`: everything.
|
|
31
|
+
|
|
32
|
+
Check the mode in `whoami`. Use `--dry-run` to show a write without sending it; it exits 7 too if the write would be blocked.
|
|
33
|
+
|
|
34
|
+
The mode is the user's decision. Never get around a block: don't pass `--env` or set `PPDEVOPS_DATAVERSE` / `PPDEVOPS_DEVOPS` to reach an environment with a wider mode, don't switch to `--client-id` or raise `--mode`, don't change groups, environments or identities, and don't edit ppdo-cli's config files or `.ppdo-cli.json`. Use another environment only when the user names it. (Widening is refused without a person at a terminal anyway.)
|
|
35
|
+
|
|
36
|
+
## Exit codes
|
|
37
|
+
|
|
38
|
+
| Code | Meaning | What to do |
|
|
39
|
+
|---|---|---|
|
|
40
|
+
| 0 | ok | |
|
|
41
|
+
| 1 | error, or some items of a many-item command failed (`batch`, `upsert`, `workflow enable`, …) | read the error, or each item's result |
|
|
42
|
+
| 2 | usage | fix the command (see `--help`) |
|
|
43
|
+
| 3 | not signed in / wrong account | user runs the hinted `ppdo-cli auth login` |
|
|
44
|
+
| 4 | not found | check names and ids |
|
|
45
|
+
| 5 | throttled after retries | wait, then retry |
|
|
46
|
+
| 6 | conflict / precondition | re-read the record, then retry |
|
|
47
|
+
| 7 | blocked by the environment's mode | stop and tell the user |
|
|
48
|
+
| 8 | forbidden | the account lacks permission |
|
|
49
|
+
| 130 | interrupted | |
|
|
50
|
+
|
|
51
|
+
## Setup and checks
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
ppdo-cli whoami [--service dv|ado] [--check]
|
|
55
|
+
ppdo-cli env list [--service dv|ado] [--group <name>]
|
|
56
|
+
ppdo-cli group discover <group> [--add <url name,…>|all]
|
|
57
|
+
ppdo-cli commands [<group>]
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
- `whoami --check` calls each service to confirm the account works; `--service` limits it to one.
|
|
61
|
+
- `env list` shows every environment with its group and mode.
|
|
62
|
+
- `group discover` lists every Dataverse environment the group's account can reach (Global Discovery Service), with type, version and `added` for the ones already set up. `--add` puts new ones in the group; for a group agents can write to, only the user can confirm that at a terminal (exit 7 otherwise), so suggest the command instead.
|
|
63
|
+
- `commands dv` (or `ado`) lists every command in a group with its class: R read, W write, D delete, M depends on the HTTP method, L local only.
|
|
64
|
+
|
|
65
|
+
## Options on every command
|
|
66
|
+
|
|
67
|
+
| Option | Meaning |
|
|
68
|
+
|---|---|
|
|
69
|
+
| `--env <name>` | Use this environment instead of the default; `--env a,b,c` runs a read command against each |
|
|
70
|
+
| `--group <name>` | Run a read command against every environment in the group |
|
|
71
|
+
| `--identity <name>` | Use another identity's account (only when the user asks) |
|
|
72
|
+
| `--client-id <id> --tenant <id\|domain>` | `dv`, `ado` and `graph`: run as an app (service principal) instead of the config's account, only when the user asks. The secret comes from `PPDEVOPS_CLIENT_SECRET` (or `--certificate <pem\|pfx>`); `--env` may then be a URL; the mode is `--mode read-only\|read-write\|full`, `read-only` by default, never the group's. Nothing is saved |
|
|
73
|
+
| `-o json\|ndjson\|table\|tsv` | Output format; JSON by default. `-o table` is easier to show the user |
|
|
74
|
+
| `--dry-run` | Run the mode checks and print the request without sending it |
|
|
75
|
+
| `-v` / `-q` | Log requests to stderr (redacted) / hide notices on stderr |
|
|
76
|
+
| `--timeout <seconds>` | Overall deadline, retries included |
|
|
77
|
+
|
|
78
|
+
With `--env a,b,c` or `--group`, you get one labelled result per environment (for example `ppdo-cli dv solution get MySolution --group test-envs`). Writes always go to one environment at a time.
|
|
79
|
+
|
|
80
|
+
## Passing data
|
|
81
|
+
|
|
82
|
+
- Bodies and queries go in files: `--body @body.json`, `--fetchxml @query.xml`, `--wiql @query.wiql`, or `-` for stdin. Don't put JSON inline on the command line; Windows PowerShell 5.1 breaks it.
|
|
83
|
+
- List commands return 100 rows by default and say so on stderr when there are more. Narrow the query, or pass `--limit n` / `--all`.
|
|
84
|
+
- `--since` and `--until` take `30m`, `12h`, `7d`, `2w` or a date (`2026-10-01`). `--name` patterns use `*` as a wildcard.
|
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ppdo-cli-dataverse
|
|
3
|
+
description: Work with Dataverse through ppdo-cli - query and change rows and metadata (tables, columns, choices, keys), functions, actions and bulk requests, and views, forms and web resources edited as files; move solutions between environments (dependencies, export, deployment settings, import or upgrade, verify) and keep them in source control without pac (clone, sync, unpack, pack); environment variables, connection references, flows and processes; and find out why something failed or changed (failed imports, plugin errors and traces, system jobs, flow runs, who changed a record, security and access). Use for any Dataverse task.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Dataverse with ppdo-cli
|
|
7
|
+
|
|
8
|
+
Load the ppdo-cli skill first (account, modes, exit codes, output).
|
|
9
|
+
|
|
10
|
+
- Data commands take the **entity set** name (plural, `accounts`); metadata commands take the **logical name** (`account`). Find both with `dv metadata list --search <text>`.
|
|
11
|
+
- OData options are flags; never type `$filter` yourself. Quotes inside a text value are doubled: `--filter "lastname eq 'O''Brien'"`.
|
|
12
|
+
- Narrow a list with `--select` and filters before reaching for `--limit n` or `--all`.
|
|
13
|
+
|
|
14
|
+
## Rows and record history: `dv query`, `get`, `create`, `update`, `delete`, `upsert`, `associate`, `disassociate`, `batch`, `history`
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
ppdo-cli dv query <entityset> [--select a,b] [--filter <expr>] [--expand <expr>] [--orderby <expr>] [--top n]
|
|
18
|
+
[--apply <expr>] [--count] [--fetchxml @file] [--formatted] [--limit n] [--all]
|
|
19
|
+
ppdo-cli dv get <entityset> <key> [--select a,b] [--expand <expr>] [--formatted]
|
|
20
|
+
ppdo-cli dv create <entityset> --body @file [--return] [--select a,b] [--bypass-plugins sync|async|all] [--bypass-step <id,…>]
|
|
21
|
+
ppdo-cli dv update <entityset> <key> --body @file [--if-match <etag>] [--upsert] [--return] [--bypass-plugins sync|async|all] [--bypass-step <id,…>]
|
|
22
|
+
ppdo-cli dv delete <entityset> <key> [--if-match <etag>] [--bypass-plugins sync|async|all] [--bypass-step <id,…>]
|
|
23
|
+
ppdo-cli dv upsert <entityset> --body @rows.ndjson [--key <a,b>] [--continue-on-error] [--bypass-plugins sync|async|all] [--bypass-step <id,…>]
|
|
24
|
+
ppdo-cli dv associate <entityset> <id> <navigation> <target>
|
|
25
|
+
ppdo-cli dv disassociate <entityset> <id> <navigation> [<target>]
|
|
26
|
+
ppdo-cli dv batch --file <requests.ndjson> [--changeset] [--continue-on-error] [--bypass-plugins sync|async|all] [--bypass-step <id,…>]
|
|
27
|
+
ppdo-cli dv history <entityset> <id> [--column <column>] [--since <when>] [--limit n] [--all]
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- `<key>`: a GUID, or `name=value[,name2=value2]` for an alternate key (text is quoted for you; `name:=123` keeps a number bare).
|
|
31
|
+
- `query`: `--apply` aggregates (`groupby((statecode),aggregate($count as n))`); `--count` adds the total; `--formatted` adds labels for choices and lookups; `--fetchxml` replaces the OData options and pages with the paging cookie.
|
|
32
|
+
- `create`/`update`: `--return` returns the row (`--select` its columns); `--if-match` fails with exit 6 if the row changed; `update` exits 4 if the row doesn't exist unless `--upsert`.
|
|
33
|
+
- `--bypass-plugins`/`--bypass-step` skip the environment's custom logic for that request: `sync` or `async` plugins and classic workflows, or `all` (cloud flows still run), or only the plugin steps named. Use them only when the user asks (for example a data fix a validation plugin would reject): they need a group in `full` mode (exit 7 otherwise) and the user's bypass privilege (system administrators have it).
|
|
34
|
+
- `upsert`: one JSON object per line (or a JSON array). `--key` matches rows on an alternate key's columns; without it each row needs the table's id column. Each row reports `created` or `updated` and its `id`; exits 1 if any row failed or didn't run (`--continue-on-error` keeps going). Lookups go in the row as `"<navigation>@odata.bind": "/accounts(<id>)"`.
|
|
35
|
+
- `associate`/`disassociate`: `<navigation>` is the navigation property (`metadata get <table> --relationships`); `<target>` is `contacts(<id>)` or `contacts(name=value)`. A lookup needs no `<target>` to unlink. `disassociate` is classed as a delete.
|
|
36
|
+
- `batch`: one JSON request per line, `{"method":"PATCH","path":"accounts(<id>)","body":{…}}`; returns one result per request and exits 1 if any failed. `--changeset` makes consecutive writes all-or-nothing; `--continue-on-error` keeps going after a failed request.
|
|
37
|
+
- `history` (record): who changed the row (or one `--column`) and when, newest first, with old and new values; choices and lookups show their label, with the raw value in `old_value`/`new_value`. An empty result prints why on stderr, for example that auditing is off for the table.
|
|
38
|
+
|
|
39
|
+
### Examples
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
ppdo-cli dv query accounts --select name,accountnumber --filter "statecode eq 0" --top 20 -o table
|
|
43
|
+
ppdo-cli dv query solutions --select uniquename,version --orderby "modifiedon desc" --top 3
|
|
44
|
+
ppdo-cli dv get accounts accountnumber=ABC-1 --select name
|
|
45
|
+
ppdo-cli dv fn RetrieveTotalRecordCount --param 'EntityNames=["account"]'
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Functions and actions: `dv fn`, `action`
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
ppdo-cli dv fn <name> [--bound <entityset>/<key>] [--param k=v]… [--string NAME]…
|
|
52
|
+
ppdo-cli dv action <name> [--bound <entityset>/<key>] [--body @file]
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
- `fn`: values are typed for you (GUIDs, numbers, booleans and JSON stay bare); `--string NAME` forces one to text. `--bound` calls the function on a row.
|
|
56
|
+
|
|
57
|
+
## Tables, columns and choices: `dv metadata`
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
ppdo-cli dv metadata list [--custom-only] [--search <text>] [--limit n] [--all]
|
|
61
|
+
ppdo-cli dv metadata get <table> [--attributes] [--relationships] [--keys] [--raw]
|
|
62
|
+
ppdo-cli dv metadata attribute <table> <column> [--raw]
|
|
63
|
+
ppdo-cli dv metadata optionset <name> [--raw]
|
|
64
|
+
ppdo-cli dv metadata create table <name> --display-name <text> [--plural <text>] [--description <text>] [--ownership user|organization]
|
|
65
|
+
[--primary-name <schema name>] [--solution <name>]
|
|
66
|
+
ppdo-cli dv metadata create column <table> <name> --type string|memo|int|decimal|money|bool|datetime|choice|lookup --display-name <text>
|
|
67
|
+
[--description <text>] [--required] [--max-length n] [--precision n] [--date-only]
|
|
68
|
+
[--choice <global choice> | --options <a,b,c>] [--target <table>] [--solution <name>]
|
|
69
|
+
ppdo-cli dv metadata create choice <name> --options <a,b,c> [--display-name <text>] [--description <text>] [--solution <name>]
|
|
70
|
+
ppdo-cli dv metadata create key <table> <name> --columns <a,b> [--display-name <text>] [--wait] [--solution <name>]
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
- `metadata create`: names carry the publisher prefix (`new_Project`, column `new_Code`); the table's primary name column is `<prefix>_name`. Choice option values start at the publisher's option prefix. A lookup column creates the relationship. A new alternate key's index builds in the background: use `--wait`, or check `metadata get <table> --keys` for `Active` before an upsert uses it. Creating a table takes about a minute.
|
|
74
|
+
- `metadata get`: compact by default; add `--attributes`, `--relationships` or `--keys`, or `--raw` for the full definition. `attribute` shows a column's choice options.
|
|
75
|
+
|
|
76
|
+
## Views, forms and web resources: `dv view`, `form`, `webresource`
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
ppdo-cli dv view list <table> [--type public|advanced-find|associated|quick-find|lookup|…] [--name <pattern>] [--limit n] [--all]
|
|
80
|
+
ppdo-cli dv view get <view> [--table <table>] [--save-fetchxml <file>] [--save-layoutxml <file>]
|
|
81
|
+
ppdo-cli dv view create <table> --name <name> [--copy <view>] [--fetchxml @file] [--layoutxml @file] [--description <text>]
|
|
82
|
+
[--solution <name>] [--no-publish]
|
|
83
|
+
ppdo-cli dv view update <view> [--table <table>] [--name <name>] [--description <text>] [--fetchxml @file] [--layoutxml @file]
|
|
84
|
+
[--no-publish]
|
|
85
|
+
ppdo-cli dv form list <table> [--type main|quick-create|quick-view|card|…] [--limit n] [--all]
|
|
86
|
+
ppdo-cli dv form get <form> [--table <table>] [--save <file>]
|
|
87
|
+
ppdo-cli dv form create <table> --name <name> [--type main|quick-create|quick-view|card] [--copy <form>] [--description <text>]
|
|
88
|
+
[--solution <name>] [--no-publish]
|
|
89
|
+
ppdo-cli dv form update <form> [--table <table>] [--name <name>] [--description <text>] [--state active|inactive] [--body @form.xml]
|
|
90
|
+
[--no-publish]
|
|
91
|
+
ppdo-cli dv webresource list [--solution <a,b>] [--name <pattern>] [--type js|html|css|png|svg|…] [--hidden] [--limit n] [--all]
|
|
92
|
+
ppdo-cli dv webresource get <name> [--save <file>]
|
|
93
|
+
ppdo-cli dv webresource push <file> --name <prefix_/path> [--display-name <text>] [--description <text>] [--type <type>]
|
|
94
|
+
[--solution <name>] [--no-publish]
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
- Views and forms are edited as files: `view get <view> --save-fetchxml v.fetch.xml --save-layoutxml v.layout.xml` (or `form get <form> --save f.xml`), edit the files, then `view update <view> --fetchxml @v.fetch.xml --layoutxml @v.layout.xml` (or `form update <form> --body @f.xml`). `get` reads the unpublished draft, so an edit builds on the latest version. `get` without `--save` summarises: a view's columns, sort, filter and joins; a form's tabs, sections, fields, header and script libraries.
|
|
98
|
+
- Writes check the XML first: well-formed, the right root, every view column present in the query (or its link-entity alias), a query that actually runs, unique form control ids and form fields that exist on the table. Then they publish the table (or the web resource); `--no-publish` leaves the change as a draft to publish later with `dv solution publish --entity <table>`. `--solution` adds a new view, form or web resource to that unmanaged solution.
|
|
99
|
+
- `<view>`/`<form>` is an id or a name; pass `--table` when the name isn't unique. `view create` makes a public view: empty (the primary name column), `--copy` another view, or from your XML files. `form create` is empty (one tab, one section, the primary name column) or `--copy`. Only main forms can be made inactive.
|
|
100
|
+
- `webresource push` creates or updates from a file (type from the extension, or `--type`) and skips an unchanged file; the name needs a publisher prefix (`contoso_/scripts/app.js`). `get` shows text content inline and needs `--save` for images.
|
|
101
|
+
|
|
102
|
+
## Solutions: `dv solution`
|
|
103
|
+
|
|
104
|
+
Each environment is a ppdo-cli environment, and its group sets the account and mode. Confirm both with `ppdo-cli env list` and `ppdo-cli whoami --env <name>` before starting, and tell the user which source and target you'll use. Imports and publishing are writes: the target's group must be `read-write` or `full`. If it is `read-only`, stop and tell the user.
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
ppdo-cli dv solution list [--unmanaged] [--managed] [--publisher <prefix>] [--limit n] [--all]
|
|
108
|
+
ppdo-cli dv solution get <solution>
|
|
109
|
+
ppdo-cli dv solution components <solution> [--type <componenttype>] [--limit n] [--all]
|
|
110
|
+
ppdo-cli dv solution dependencies <solution> [--for-uninstall]
|
|
111
|
+
ppdo-cli dv solution export <solution> [--managed | --both] [--save <file.zip>] [--unpack <folder> [--allow-delete]]
|
|
112
|
+
ppdo-cli dv solution import [<file.zip> | --path <file.zip>] [--settings @settings.json] [--overwrite-unmanaged] [--activate-plugins] [--activate-workflows] [--activate-flows] [--publish-changes] [--skip-dependency-check] [--skip-lower-version] [--holding | --upgrade] [--async]
|
|
113
|
+
ppdo-cli dv solution promote <solution> [--async]
|
|
114
|
+
ppdo-cli dv solution import-results <importjob|solution> [--components]
|
|
115
|
+
ppdo-cli dv solution history [<solution>] [--state failed|succeeded] [--operation import|uninstall|export|publish|publish-all] [--since <when>] [--limit n] [--all]
|
|
116
|
+
ppdo-cli dv solution publish --all | --entity <table>…
|
|
117
|
+
ppdo-cli dv solution create <solution> --publisher <prefix|name> [--version <x.y.z.w>] [--display-name <text>] [--description <text>]
|
|
118
|
+
ppdo-cli dv solution update <solution> [--version <x.y.z.w> | --bump major|minor|build|revision] [--display-name <text>] [--description <text>]
|
|
119
|
+
ppdo-cli dv solution patch <parent> [--version <x.y.z.w>] [--display-name <text>]
|
|
120
|
+
ppdo-cli dv solution add-component <solution> <type> <component> [--shell | --no-subcomponents] [--with-required]
|
|
121
|
+
ppdo-cli dv solution remove-component <solution> <type> <component>
|
|
122
|
+
ppdo-cli dv solution clone <solution> [--folder <folder>] [--package-type both|unmanaged|managed] [--no-project] [--async] [--max-wait <minutes>] [--map <map.xml>]
|
|
123
|
+
ppdo-cli dv solution sync [<folder>] [--package-type both|unmanaged|managed] [--keep-stale] [--check] [--async] [--max-wait <minutes>] [--map <map.xml>]
|
|
124
|
+
ppdo-cli dv solution unpack <file.zip> --folder <folder> [--package-type unmanaged|managed|both] [--managed-zip <file.zip>] [--allow-delete] [--check] [--map <map.xml>]
|
|
125
|
+
ppdo-cli dv solution pack <folder> --save <file.zip> [--package-type unmanaged|managed|both] [--map <map.xml>] [--remap-plugins] [--configuration <name>] [--no-build]
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
- `components`: each row shows its type and whether a table is included in full or as a shell. `--type` filters by component type number (1 table, 61 web resource).
|
|
129
|
+
- `dependencies`: missing dependencies by default; `--for-uninstall` lists what blocks removing the solution.
|
|
130
|
+
- `export` waits for the async export and writes the zip. `--both` exports unmanaged to `<file.zip>` and managed to `<file>_managed.zip`. `--unpack <folder>` then unpacks it into a source folder (both types with `--both`); without `--save` the zips are temporary. Files of components no longer in the solution stay unless `--allow-delete`.
|
|
131
|
+
- `import` stages first and stops (exit 6) on missing dependencies, then starts the system job, prints its id with `status: started` and exits. That says nothing about whether the import worked: pass `--async` to poll the job until it finishes, or run `ppdo-cli dv job wait <id>` afterwards. With no file, a folder holding one `.cdsproj` imports the newest `.zip` under it. `--settings` applies a deployment-settings file (`{"EnvironmentVariables":[{"SchemaName","Value"}],"ConnectionReferences":[{"LogicalName","ConnectionId","ConnectorId"}],"Workflows":[{"Name","WorkflowId","UserEmail"}]}`); settings for components that aren't in the solution are reported on stderr. `--overwrite-unmanaged` replaces unmanaged customizations, and `--holding` stages an upgrade as a holding solution.
|
|
132
|
+
- `import` activation: on a new install workflows and flows arrive on or off as the file has them, and plug-in steps arrive off; on an update or upgrade all of them stay as they were. After the import, and so only with `--async`, `--activate-plugins` turns on the solution's plug-in steps, `--activate-workflows` every process that isn't a cloud flow (workflows, business rules, actions, business process flows), and `--activate-flows` the cloud flows, each as the user its `Workflows` entry names if it has one. No option turns anything off. A component that won't turn on is listed with its error under `activated`, and the command exits 1 although the import succeeded.
|
|
133
|
+
- `import` other options: `--publish-changes` publishes all customizations afterwards, and also needs `--async`. `--skip-lower-version` reports `status: skipped` and exits 0 if the same or a newer version is installed. `--skip-dependency-check` doesn't enforce dependencies flagged as product updates; staging can't tell those from others, so it also goes on past any missing dependency and leaves the import to decide.
|
|
134
|
+
- `import` of a newer managed version: by default an update, so components the new version dropped stay. `--upgrade` deletes them (and their data) in one step, so confirm with the user first; `--holding` stages the new version as `<solution>_Upgrade` and `promote` applies it, deleting them then. `promote` counts as a delete and needs a `full` group; like `import`, it prints the job id and exits unless given `--async`. `--dry-run` stages the file (reporting missing dependencies) and prints the import request.
|
|
135
|
+
- `import-results`: `<importjob>` is the `import_job_id` from `dv solution import`; a solution name picks its latest import. Returns `result`, counts per status, and `failed` components with their error text; `--components` adds every component.
|
|
136
|
+
- `history` (solution): imports, upgrades, exports, uninstalls and publishes, newest first, with the error message for failures.
|
|
137
|
+
- `create`/`update`/`patch`: unmanaged solutions only. `--bump` raises one part of the version and zeroes the rest. `patch` takes the next build number after the parent and its patches unless `--version` (same major.minor, higher).
|
|
138
|
+
- `add-component`/`remove-component`: `<type>` is `table`, `column` (`<table>.<column>`), `choice`, `relationship`, `role`, `view`, `form`, `process`, `webresource`, `sitemap`, `app`, `assembly`, `step`, `canvas-app`, `envvar`, `connref`, `email-template` or a component type number; `<component>` is an id, or a name except for views, forms, relationships and email templates. A table goes in with all its subcomponents unless `--shell` (include as shell only: no table metadata, columns, forms or views) or `--no-subcomponents` (the table's metadata without them). Adding a table that's already there changes how it's included, except one with all its subcomponents: remove that first; `--with-required` adds what it needs too. Removing only takes it out of the solution.
|
|
139
|
+
- Source folders: `clone`, `sync`, `unpack` and `pack` replace `pac solution clone|sync|unpack|pack`; pac is not needed. The folders are byte for byte what pac writes, so a repo can move between the two. `clone` exports into a new project: `<folder>/<solution>.cdsproj`, `.gitignore` and the unpacked solution in `src` (`--no-project`: just the unpacked solution in `<folder>`); its default type is `both`, exported unmanaged and managed at the same time (as two plain export requests; one that times out is redone as an export job, and `--async` uses jobs from the start, for very large solutions; `--max-wait` sets how long to wait for a job, 60 minutes by default). `sync` re-exports into a folder made by `clone`, `unpack` or pac (a `.cdsproj` folder or an unpacked one), as `both` unless `--package-type` (as pac does); only changed files are written, and files of removed components are deleted unless `--keep-stale`; components built by the project's `.pcfproj` and plug-in `.csproj` references are left out. `--check` (sync, unpack) writes nothing, prints what would change and exits 6 if anything would, for "is the repo up to date with the environment" checks. Each prints `files` counts (`added`, `changed`, `deleted`, `stale`, `unchanged`) and up to 100 paths of each.
|
|
140
|
+
- `unpack`: the type is read from the zip unless `--package-type`; `both` takes the unmanaged zip and finds `<file>_managed.zip` beside it (or `--managed-zip`). `pack`: a folder unpacked as `both` packs unmanaged unless `--package-type`; `both` writes `<file.zip>` and `<file>_managed.zip`. Packing the same folder twice gives the same bytes. Like pac, `pack` stops (exit 2) when a component in the folder isn't a root component in `Other/Solution.xml`, because the import would fail; add the component to the solution in the environment and sync again.
|
|
141
|
+
- A `.cdsproj` folder packs the way `dotnet build` does: `pack` first builds the project's PCF (`.pcfproj`) and plug-in (`.csproj`) references with dotnet (`--configuration`, default `Debug`; `--no-build` uses their last build) and packs their output with `src`: each control into `Controls/<prefix>_<namespace>.<constructor>/` with its root component, each plug-in `.dll` over the assembly registered with the same full name (name, version and key must match a `PluginAssemblies/**/*.dll.data.xml`; register a new assembly in the environment and sync first). The package type is the project's `SolutionPackageType`, else managed for `Release` and unmanaged otherwise; `--package-type` overrides. Nothing is written into `src`. Needs the .NET SDK, and Node for PCF.
|
|
142
|
+
- `--map <map.xml>` is a SolutionPackager mapping file (`<Mapping>` with `FileToFile`, `FileToPath` and `Folder` elements; `map` is the path in the folder, `to` where the file is, both relative to the folder; `%NAME%` takes an environment variable). `pack` reads a mapped file from where it points and adds files mapped into other folders; `unpack`, `clone` and `sync` don't write mapped files and never delete them as stale. A `.cdsproj`'s `SolutionPackageMapFilePath` is the default.
|
|
143
|
+
- `pack --remap-plugins`: when a plug-in `.dll`'s version or key differs from its record, the assembly, its root component, plug-in types, steps and workflow activity references take the `.dll`'s full name. pac does this only with `--disablePluginRemap` (the switch is wired backwards), so it is off by default.
|
|
144
|
+
|
|
145
|
+
## Publishers: `dv publisher`
|
|
146
|
+
|
|
147
|
+
```
|
|
148
|
+
ppdo-cli dv publisher list [--name <pattern>] [--limit n] [--all]
|
|
149
|
+
ppdo-cli dv publisher create <prefix> --name <uniquename> [--display-name <text>] [--option-prefix <n>]
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
- `publisher create`: the prefix is 2-8 lower-case letters or digits; the choice value prefix is derived from it unless `--option-prefix`.
|
|
153
|
+
|
|
154
|
+
## Components and dependencies: `dv component`, `dependency`
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
ppdo-cli dv component layers <type> <component> [--values]
|
|
158
|
+
ppdo-cli dv component dependencies <type> <component> [--dependents | --blocking-delete] [--limit n] [--all]
|
|
159
|
+
ppdo-cli dv component names [<type> <component>] [--file <file.ndjson|->] [--save <file>]
|
|
160
|
+
ppdo-cli dv dependency list [--solution <a,b> | --required <type> <component> | --dependent <type> <component>] [--type n] [--include-system] [--limit n] [--all] [--save <file>]
|
|
161
|
+
ppdo-cli dv component customizable <type> <component>
|
|
162
|
+
ppdo-cli dv component unpublished <type> <component> [--show]
|
|
163
|
+
ppdo-cli dv component remove-active <type> <component>
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
- `component …`: `<type>` and `<component>` as for `add-component`. `layers` lists the layers bottom to top (the top one wins; `Active` is the unmanaged layer); the bottom layer is the whole definition, so it shows a property count, and each layer above lists the properties it sets (`--values` adds what it sets them to). `dependencies` shows what the component requires, `--dependents` what uses it, `--blocking-delete` what stops it being deleted; each row has the type, name, id and the solution it came from. `customizable` answers whether it can be edited. `unpublished` (forms, views, web resources, apps) says whether there are unpublished changes and which properties (`--show` adds the draft values).
|
|
167
|
+
- `component names`: names many components in one go, for reports and for joining environments. `--file` takes NDJSON lines of `{"type", "id", "parent_id"}`, `solutioncomponents` rows, or `dependency list` rows (both sides; `.gz` read as gzip), so `dependency list --save deps.ndjson` then `component names --file deps.ndjson` names everything in a solution's rows. Each component gets `name_status` `resolved`, `not-found` (no such component) or `type-unsupported` (an internal part such as a relationship role or choice value), never dropped; `logical_name` and `schema_name` (an exported `Solution.xml` uses the logical name for tables and columns); and the parent table for columns, keys, forms and views, or the column for a local choice. Hidden components resolve. A local choice with no column given makes it search every table's choice columns (about a minute).
|
|
168
|
+
- `dependency list`: the rows of the `dependencies` table itself, for many components at once. `--solution` takes rows where either side is in the solutions, counting a table included with all subcomponents together with its columns, keys, relationships (and many-to-many intersect tables), local choices, forms and views. Where a solution is managed, rows whose base solution it is are added too, which brings internal parts (relationship roles, ribbon parts) that nothing else lists; where it is unmanaged those parts can't be told apart from other components', so a few percent of rows are missed there. Each row's `found_by` says how it was found (`membership`, `base-solution`, `component`). stderr says how many subcomponents were added, and names any table the solution lists that no longer exists. `--required X` gives rows where X is the required component (what depends on X), `--dependent X` rows where X is the dependent (what X requires). `--type n` keeps rows whose component at the other end has type n. Each row has both sides' type, id, parent id, base solution and top (winning layer) solution, as ids and unique names; names of the components themselves are not looked up. `--all` with no filter is refused unless `--include-system` (a bare environment has about 200,000 rows). `--save` writes NDJSON (gzip for `.gz`) and prints a summary. Use it rather than `component dependencies` for a whole solution: the functions behind that command rename internal component types and leave out structural rows.
|
|
169
|
+
- `component remove-active`: deletes the unmanaged layer, so the managed definition applies again and those changes are lost. It counts as a delete (`full` group); confirm with the user first.
|
|
170
|
+
|
|
171
|
+
## Environment variables, connection references and connections: `dv envvar`, `connref`, `connection`
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
ppdo-cli dv envvar list [--solution <a,b>] [--name <pattern>] [--limit n] [--all]
|
|
175
|
+
ppdo-cli dv envvar get <name>
|
|
176
|
+
ppdo-cli dv envvar set <name> --value <text|@file|->
|
|
177
|
+
ppdo-cli dv connref list [--solution <a,b>] [--name <pattern>] [--unbound] [--limit n] [--all]
|
|
178
|
+
ppdo-cli dv connref get <name>
|
|
179
|
+
ppdo-cli dv connref set <name> --connection <id|connector/id|url>
|
|
180
|
+
ppdo-cli dv connection list [--connector <name>] [--unused] [--limit n] [--all]
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
- `envvar`: `value` is what runs (`current` if set, else `default`); `current: null` means no value row. `set` creates or updates the current value and checks it against the type: number, JSON, or yes/no for a boolean (true/false are stored as yes/no).
|
|
184
|
+
- `connref`: `connection` is the connection id bound to it (null when unbound); `--unbound` lists only those. `set --connection` takes the connection's id, `<connector>/<id>`, or its URL from Power Automate > Connections; it must be for the same connector and be yours or shared with you.
|
|
185
|
+
- `connection list`: the connections the signed-in account can use in the environment (its own and those shared with it), with `id` (what `connref set --connection` takes), `connector`, `status` and the connection `references` bound to each; `--unused` shows only those nothing uses. Connections are not in Dataverse: this calls the Power Apps API with the same account. If the one you need isn't listed, ask the user to create or share it.
|
|
186
|
+
- `envvar` and `connref`: `<name>` is the schema or logical name, or the id.
|
|
187
|
+
|
|
188
|
+
## Flows and processes: `dv workflow`
|
|
189
|
+
|
|
190
|
+
```
|
|
191
|
+
ppdo-cli dv workflow list [--solution <a,b>] [--category flow,workflow,business-rule,action,bpf] [--state on|off] [--name <pattern>] [--limit n] [--all]
|
|
192
|
+
ppdo-cli dv workflow summary [--solution <a,b>] [--category <a,b>] [--limit n] [--all]
|
|
193
|
+
ppdo-cli dv workflow enable <process>… [--solution <a,b>] [--category <a,b>]
|
|
194
|
+
ppdo-cli dv workflow disable <process>… [--solution <a,b>] [--category <a,b>]
|
|
195
|
+
ppdo-cli dv workflow swap-connref <flow> --from <connref> --to <connref>
|
|
196
|
+
ppdo-cli dv workflow runs <flow> [--state succeeded|failed|cancelled] [--since <when>] [--limit n] [--all]
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
- `workflow`: cloud flows (`flow`), classic workflows, business rules, actions and business process flows (`bpf`); `--category workflow` narrows to classic workflows only. `state` is `on` or `off`. `<process>` and `<flow>` are an id, a name, or a pasted make.powerautomate.com flow URL. `summary` gives per solution the totals, counts per category and the names of those that are off; without `--solution` it covers every solution with processes.
|
|
200
|
+
- `workflow enable`/`disable`: the processes named, or every one in `--solution` (narrowed by `--category`). Each is tried again after the others, so parent flows can follow their child flows. One result per process (`changed`, `error`); exits 1 if any failed. Dataverse turns a flow on even when a connection reference it uses has no connection, so check `connref list --unbound` first.
|
|
201
|
+
- `workflow swap-connref`: rewrites the flow on the server, replacing exactly that logical name (not longer names that start with it). Both references must use the same connector; it warns if the new one has no connection. Use it when a flow uses another solution's connection reference.
|
|
202
|
+
- `workflow runs`: a cloud flow's runs, newest first, with `status`, `trigger`, `duration_ms` and, for failures, `error_code` and `error`. `<flow>` is an id, a name, or a pasted make.powerautomate.com flow URL. Runs appear a few minutes after they finish and are kept 28 days by default. The error is the run-level message (often just "An action failed"); which action failed is only in the run's page in Power Automate.
|
|
203
|
+
|
|
204
|
+
## Plug-ins: `dv plugin`
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
ppdo-cli dv plugin trace list [--type <pattern>] [--message <name>] [--table <table>] [--correlation <id>] [--state failed] [--since <when>] [--limit n] [--all]
|
|
208
|
+
ppdo-cli dv plugin trace get <id>
|
|
209
|
+
ppdo-cli dv plugin tracing get
|
|
210
|
+
ppdo-cli dv plugin tracing set off|exception|all
|
|
211
|
+
ppdo-cli dv plugin stats [--type <pattern>] [--limit n] [--all]
|
|
212
|
+
ppdo-cli dv plugin assembly list [--solution <a,b>] [--name <pattern>] [--hidden] [--limit n] [--all]
|
|
213
|
+
ppdo-cli dv plugin assembly get <assembly> [--save <file.dll>] [--compare <file.dll>]
|
|
214
|
+
ppdo-cli dv plugin step list [--assembly <name>] [--type <pattern>] [--message <name>] [--table <table>] [--solution <a,b>] [--state on|off]
|
|
215
|
+
[--hidden] [--limit n] [--all]
|
|
216
|
+
ppdo-cli dv plugin step enable <step>… [--assembly <name>]
|
|
217
|
+
ppdo-cli dv plugin step disable <step>… [--assembly <name>]
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
- Plugin `--type` patterns use `*` as a wildcard, and also match anywhere in the name without one.
|
|
221
|
+
- `plugin trace list`: each row has the plugin `type`, `message`, `table`, `duration_ms`, `correlation_id`, the `error` message and the first lines of the `trace`; `trace get` returns the full exception and trace. `--correlation` shows everything one request triggered.
|
|
222
|
+
- `plugin tracing`: traces are only written while tracing is `exception` or `all`. `set` is a write; ask the user before turning it on, and suggest turning it off afterwards.
|
|
223
|
+
- `plugin stats`: executions, failures, crashes and average time per plugin type. Microsoft says it fills in 30–60 minutes after plugins run, but it can stay empty for longer or have no rows at all; use `plugin trace list` for recent runs.
|
|
224
|
+
- `plugin assembly list` / `plugin step list`: what is registered. Steps show `message`, `table`, `stage` (pre-validation, pre-operation, post-operation), `mode` (sync/async), `rank`, `filtering_attributes` and whether they're `on`. Microsoft's hidden assemblies and steps are left out unless `--hidden`.
|
|
225
|
+
- `plugin assembly get`: one assembly (name or id) with its `version`, `modified`, `size` and `sha256` of the registered DLL. `--compare <file.dll>` says whether a local build is the one registered (`match`), for example a DLL committed in a repo against what was registered after the last export; `--save` writes the registered DLL. An assembly inside a plugin package (`package`) has no content of its own.
|
|
226
|
+
- `plugin step enable`/`disable`: the steps named (id or name), or every step of `--assembly`. Writes: only when the user asks, for example to stop a plugin during a data load, and say which steps you turned off so they get turned back on. One result per step; exits 1 if any failed.
|
|
227
|
+
|
|
228
|
+
## System jobs: `dv job`
|
|
229
|
+
|
|
230
|
+
```
|
|
231
|
+
ppdo-cli dv job list [--state waiting|suspended|running|succeeded|failed|canceled] [--name <pattern>] [--type <n>] [--since <when>] [--limit n] [--all]
|
|
232
|
+
ppdo-cli dv job get <id>
|
|
233
|
+
ppdo-cli dv job wait <id>
|
|
234
|
+
ppdo-cli dv job cancel <id>
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
- `job list`: newest first. `--type` is the operation type number: 1 system event (async plugin), 10 workflow, 13 bulk delete, 54 execute async request (solution import/export), 57 rollup field. `job wait` exits non-zero if the job failed; `job cancel` is a write and exits 6 if the job already finished.
|
|
238
|
+
|
|
239
|
+
## Security: `dv user`, `role`, `team`, `access`, and Entra groups (`graph group`)
|
|
240
|
+
|
|
241
|
+
```
|
|
242
|
+
ppdo-cli dv user get <user>
|
|
243
|
+
ppdo-cli dv user privileges <user> [--table <table>] [--limit n] [--all]
|
|
244
|
+
ppdo-cli dv role list [--name <pattern>] [--limit n] [--all]
|
|
245
|
+
ppdo-cli dv role get <role> [--table <table>] [--limit n] [--all]
|
|
246
|
+
ppdo-cli dv team list [--type owner|access|aad-group|aad-office] [--name <pattern>] [--limit n] [--all]
|
|
247
|
+
ppdo-cli dv team get <team> [--limit n] [--all]
|
|
248
|
+
ppdo-cli dv team add-role <team> <role>
|
|
249
|
+
ppdo-cli dv team remove-role <team> <role>
|
|
250
|
+
ppdo-cli dv access origin <entityset> <id> --user <user> | --team <team>
|
|
251
|
+
ppdo-cli dv access shared <entityset> <id>
|
|
252
|
+
ppdo-cli graph group get <group> [--members] [--limit n] [--all]
|
|
253
|
+
ppdo-cli graph group search <text> [--limit n]
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
- `<user>` is `me`, an id or a sign-in name (UPN); teams and roles are an id or a name. `user get` shows the business unit, direct roles and each team with its roles; `user privileges` and `role get` list privileges (thousands for broad roles, so pass `--table` for one table's create/read/write/delete/append/appendto/assign/share depth: `none`, `Basic`, `Local`, `Deep` or `Global`, the deepest across all roles). Roles exist once per business unit: `role list` shows each once, and `team add-role` gives the team its own business unit's copy. `team remove-role` is classed as a delete (`full` group).
|
|
257
|
+
- `access origin`: `rights` (from `RetrievePrincipalAccess`) is what the user or team can actually do with the record; `origin` is Dataverse's own explanation, passed through as it is. It answers even when there's no access, and it missed a share to a team, so trust `rights` and use `access shared` to see shares.
|
|
258
|
+
- `graph group`: Entra groups, read-only. `get` takes the object id (a group team's `entra_group` from `dv team list`) or the exact display name and shows the name, type, description, member count and, with `--members`, who is in it; `search` matches words in display names. It uses the account of the current environment (or `--env`/`--identity`).
|
|
259
|
+
|
|
260
|
+
## Organization and settings: `dv org`, `setting`
|
|
261
|
+
|
|
262
|
+
```
|
|
263
|
+
ppdo-cli dv org get
|
|
264
|
+
ppdo-cli dv setting list [--name <pattern>] [--limit n] [--all]
|
|
265
|
+
ppdo-cli dv setting get <name> [--app <uniquename>]
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
- `org get`: version, type (as Dataverse names it, for example `Developer` or `CustomerTest`), ids and endpoints. With `--group` or `--env a,b` it compares versions across environments.
|
|
269
|
+
- `setting get`: the value that applies, typed, with `source` `app` (with `--app`), `organization` or `default`, plus the default and any override. `setting list` finds names (`--name` takes `*`).
|
|
270
|
+
|
|
271
|
+
## Any Web API request: `dv api`
|
|
272
|
+
|
|
273
|
+
```
|
|
274
|
+
ppdo-cli dv api <METHOD> <path> [--body @file] [--header k:v]… [--param k=v]… [--annotations] [--paginate] [--limit n] [--save <file>]
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
- `api`: any Web API request. Paths are relative to `/api/data/v9.2/`. `--annotations` adds formatted values, `--paginate` follows every page, `--save` writes the body to a file. `Authorization` and `Host` headers are refused.
|
|
278
|
+
|
|
279
|
+
## Promote a solution
|
|
280
|
+
|
|
281
|
+
1. **Source**: `ppdo-cli dv solution get <name> --env <source>` (note the version), then `ppdo-cli dv solution dependencies <name> --env <source>`.
|
|
282
|
+
2. **Export**: `ppdo-cli dv solution export <name> --managed --save <name>_managed.zip --env <source>`.
|
|
283
|
+
3. **Target**: `ppdo-cli dv solution get <name> --env <target>` to compare versions.
|
|
284
|
+
4. **Settings**: list what the solution needs and what the target already has, then write the settings file:
|
|
285
|
+
- `ppdo-cli dv envvar list --solution <name> --env <source>,<target>`
|
|
286
|
+
- `ppdo-cli dv connref list --solution <name> --env <source>,<target>`
|
|
287
|
+
- `ppdo-cli dv connection list --env <target>` for the connection ids to bind
|
|
288
|
+
5. **Import**: `ppdo-cli dv solution import <name>_managed.zip --settings @settings.json --async --env <target>`, adding `--activate-plugins`, `--activate-workflows` or `--activate-flows` for what the user wants on, then `ppdo-cli dv workflow summary --solution <name> --env <target>`.
|
|
289
|
+
6. **Verify**: `ppdo-cli dv solution get <name> --env <target>` shows the new version; `ppdo-cli dv connref list --solution <name> --unbound --env <target>` should be empty.
|
|
290
|
+
|
|
291
|
+
## Why did it fail?
|
|
292
|
+
|
|
293
|
+
Read the error text before guessing, and quote it when you report.
|
|
294
|
+
|
|
295
|
+
- **Solution import**: the error's hint names the next command: `ppdo-cli dv solution import-results <import_job_id>` lists the failed components with their error text. Missing dependencies stop the import before anything changes; install the required solutions first. For earlier attempts: `dv solution history <solution> --state failed`.
|
|
296
|
+
- **Plugin error** (the user saw a business process error, or an operation failed with a plugin message): `dv plugin trace list --state failed --since 1h`. If nothing comes back and tracing is off, ask the user before running `dv plugin tracing set exception`, reproduce, and list again.
|
|
297
|
+
- **Cloud flow**: `dv workflow runs <flow> --state failed --since 1d`. If the flow has no runs at all, check it's on (`dv workflow list --name <flow>`) and its connection references are bound (`dv connref list --solution <solution> --unbound`).
|
|
298
|
+
- **Background job, async plugin or workflow**: `dv job list --state failed --since 1d`, then `dv job get <id>`.
|
|
299
|
+
- **A change doesn't show up, or an import didn't change a component**: `dv component unpublished <type> <component>` (not published yet?), then `dv component layers <type> <component>` (an `Active` unmanaged layer or a higher solution's layer overriding it?).
|
|
300
|
+
- **A component can't be deleted or a solution can't be uninstalled**: `dv component dependencies <type> <component> --blocking-delete`.
|
|
301
|
+
- **Someone can't see or do something**: `dv access origin <entityset> <id> --user <user>` for one record, then `dv user get <user>` (roles and teams) and `dv user privileges <user> --table <table>`. Check the business unit too: Basic and Local depth only reach the user's own or their business unit's records.
|
|
302
|
+
- **A value changed unexpectedly**: `dv history <entityset> <id> --column <column>`.
|