tmeckel · tmeckel · Dec 5, 2025 · Nov 25, 2025 · Nov 25, 2025 · Nov 25, 2025
diff --git a/AGENTS.md b/AGENTS.md
@@ -23,6 +23,8 @@ Developer: # Repository Guidelines
 - **Linting:** Follow `golangci-lint` guidance; wrap errors using `%w` for error chains.
 - **Naming:** Packages use lowercase; exported identifiers in CamelCase; files use lower_snake_case.
 - **CLI Flags:** Use kebab-case (e.g., `--organization-url`).
+- **Multi-value flag conventions:** When supporting “remove all” semantics on list flags, reserve `*` as the exclusive sentinel. Commands must reject combinations like `--remove-label foo,*` and treat a lone `*` as “remove every existing entry.”
+- **Editing Tools:** Modify files using git-aware patches (e.g., `apply_patch`). Do not rely on ad-hoc scripts (Python, sed, etc.) to edit tracked files so diffs stay reviewable.
 - **Logging:** Use `zap.L()` with structured messages; prefer `%w` for wrapping errors.
 - **Variables:** Variable names must never collide with any imports or name of GO packages
 - **Indentation During Drafts:** Cosmetic indentation mismatches are acceptable while implementing changes. Final formatting is applied with `gofumpt` after coding is complete, so focus on correctness first.
@@ -199,6 +201,10 @@ To ensure high-quality, production-ready code and prevent common errors, adhere
 
 - **Detail:** Ensure imports for standard library packages (e.g., `fmt`, `strings`, `context`), third-party libraries (e.g., `github.com/spf13/cobra`, `github.com/MakeNowJust/heredoc`), and internal project modules (e.g., `github.com/tmeckel/azdo-cli/internal/cmd/util`, `github.com/tmeckel/azdo-cli/internal/azdo`) are present. If unsure, err on the side of including common imports for the context.
 
+### Reuse Existing Helpers
+
+- Prefer the generic helpers in `internal/types` (e.g., `MapSlice`, `MapSlicePtr`) when transforming SDK slices instead of rewriting mapping loops. These helpers already handle nil pointers and keep slice code consistent across commands.
+
 ### Idiomatic Go Code & Error Handling
 
 - **Context & IOStreams:** When interacting with `util.CmdContext`, always retrieve `IOStreams` and `Prompter` into local variables to handle potential errors immediately.

diff --git a/TESTING.md b/TESTING.md
@@ -94,6 +94,7 @@ Acceptance tests (`*_acc_test.go`) run against a live Azure DevOps organization
 | `AZDO_ACC_ORG`     | Organization name used for the session.                                                                |
 | `AZDO_ACC_ORG_URL` | Optional explicit organization URL; defaults to `https://dev.azure.com/<org>`.                         |
 | `AZDO_ACC_PAT`     | Personal Access Token with the scopes required by the test steps.                                      |
+| `AZDO_ACC_PROJECT` | Project name used by acceptance tests that operate on project-scoped resources.                        |
 | `AZDO_ACC_TIMEOUT` | Optional override for the default 60 s timeout. Accepts Go durations (`45s`, `2m`) or integer seconds. |
 
 ### Step-by-step skeleton
@@ -114,6 +115,12 @@ go test ./internal/cmd/security/permission/delete -run TestAccDeletePermission
 ```
 Acceptance tests are not run in CI; execute them manually before publishing features that depend on live Azure DevOps behavior.
 
+### TestContext helpers & utilities
+
+- `inttest.TestContext` now exposes `Project()` alongside `Org`, `OrgUrl`, and `PAT`. Set `AZDO_ACC_PROJECT` when a test needs to target a specific project and fail fast in `PreRun` if it is missing.
+- Use `TestContext.SetValue(key, value)`/`Value(key)` to propagate data across `PreRun`, `Run`, `Verify`, and `PostRun` without relying on package-level variables. Keys can be simple strings or typed aliases; mimic `context.Context` usage.
+- The helper `inttest.WriteTestFile(path, contents)` creates or truncates files with `0600` permissions and ensures parent directories exist, which is useful for acceptance tests that need temporary credentials or certificates.
+
 ### Updating Mocks
 
 All mocks in this project are generated and managed by a single script.

diff --git a/docs/azdo_help_reference.md b/docs/azdo_help_reference.md
@@ -328,16 +328,15 @@ View changes in a pull request
 Edit a pull request
 
 ```
-    --add-label strings                  Add labels (comma-separated)
-    --add-optional-reviewer strings      Add optional reviewers (comma-separated)
-    --add-required-reviewer strings      Add required reviewers (comma-separated)
--B, --base string                        Change the base branch for this pull request
--b, --body string                        Set the new body.
--F, --body-file string                   Read body text from file (use "-" to read from standard input)
-    --remove-label strings               Remove labels (comma-separated)
-    --remove-optional-reviewer strings   Remove optional reviewers (comma-separated)
-    --remove-required-reviewer strings   Remove required reviewers (comma-separated)
--t, --title string                       Set the new title.
+    --add-label strings               Add labels (comma-separated)
+    --add-optional-reviewer strings   Add or demote optional reviewers (comma-separated)
+    --add-required-reviewer strings   Add or promote required reviewers (comma-separated)
+-B, --base string                     Change the base branch for this pull request
+-b, --body string                     Set the new body.
+-F, --body-file string                Read body text from file (use "-" to read from standard input)
+    --remove-label strings            Remove labels (comma-separated, use * to remove all)
+    --remove-reviewer strings         Remove reviewers (comma-separated, use * to remove all)
+-t, --title string                    Set the new title.
 ```
 
 ### `azdo pr list [[organization/]project/repository] [flags]`
@@ -393,16 +392,16 @@ View a pull request
     --comment-type string   Filter comments by type; defaults to 'text': {text|system|all} (default "text")
 -c, --comments              View pull request comments
 -C, --commits               View pull request commits
-    --format string         Output format: {json}
 -q, --jq expression         Filter JSON output using a jq expression
+    --json fields[=*]       Output JSON with the specified fields. Prefix a field with '-' to exclude it.
 -r, --raw                   View pull request raw
 -t, --template string       Format JSON output using a Go template; see "azdo help formatting"
 ```
 
 Aliases
 
 ```
-show
+show, status
 ```
 
 ### `azdo pr vote [<number> | <branch> | <url>] [flags]`
@@ -442,7 +441,7 @@ Create a new Azure DevOps Project
 Aliases
 
 ```
-cr
+cr, c, new, n, add, a
 ```
 
 ### `azdo project delete [ORGANIZATION/]PROJECT [flags]`
@@ -933,7 +932,43 @@ Work with Azure DevOps service connections.
 Aliases
 
 ```
-service-endpoints, serviceendpoint, serviceendpoints, se, sep
+service-endpoints, serviceendpoints, se
+```
+
+### `azdo service-endpoint create`
+
+Create service connections
+
+#### `azdo service-endpoint create azurerm [ORGANIZATION/]PROJECT --name <name> --authentication-scheme <scheme> [flags]`
+
+Create an Azure Resource Manager service connection
+
+```
+    --authentication-scheme string        Authentication scheme: {ServicePrincipal|ManagedServiceIdentity|WorkloadIdentityFederation} (default "ServicePrincipal")
+    --certificate-path string             Path to service principal certificate file (PEM format)
+    --description string                  Description for the service endpoint
+    --environment string                  Azure environment: {AzureCloud|AzureChinaCloud|AzureUSGovernment|AzureGermanCloud|AzureStack} (default "AzureCloud")
+    --grant-permission-to-all-pipelines   Grant access permission to all pipelines to use the service connection
+-q, --jq expression                       Filter JSON output using a jq expression
+    --json fields[=*]                     Output JSON with the specified fields. Prefix a field with '-' to exclude it.
+    --management-group-id string          Azure management group ID
+    --management-group-name string        Azure management group name
+    --name string                         Name of the service endpoint
+    --resource-group string               Name of the resource group (for subscription-level scope)
+    --server-url string                   Azure Stack Resource Manager base URL. Required if --environment is AzureStack.
+    --service-principal-id string         Service principal/application ID (e.g., GUID)
+    --service-principal-key string        Service principal key (secret value)
+    --subscription-id string              Azure subscription ID (e.g., GUID)
+    --subscription-name string            Azure subscription name
+-t, --template string                     Format JSON output using a Go template; see "azdo help formatting"
+    --tenant-id string                    Azure tenant ID (e.g., GUID)
+-y, --yes                                 Skip confirmation prompts
+```
+
+Aliases
+
+```
+cr, c, new, n, add, a
 ```
 
 ### `azdo service-endpoint list [ORGANIZATION/]PROJECT [flags]`

diff --git a/docs/azdo_pr_edit.md b/docs/azdo_pr_edit.md
@@ -8,7 +8,17 @@ Edit an existing pull request.
 
 Without an argument, the pull request that belongs to the current branch is selected.
 If there are more than one pull request associated with the current branch, one pull request will be selected based on the shared finder logic.
-%!(EXTRA string=`)
+
+The command can:
+- Add reviewers as optional or required, promoting/demoting existing reviewers when needed.
+- Remove reviewers regardless of their current required/optional state.
+- Add or remove labels
+
+Examples:
+  `azdo pr edit --add-required-reviewer alice@example.com bob@example.com`
+  `azdo pr edit --add-optional-reviewer alice@example.com --remove-reviewer bob@example.com`
+  `azdo pr edit --add-label bug --remove-label needs-review`
+
 
 ### Options
 
@@ -19,11 +29,11 @@ If there are more than one pull request associated with the current branch, one
 
 * `--add-optional-reviewer` `strings`
 
-	Add optional reviewers (comma-separated)
+	Add or demote optional reviewers (comma-separated)
 
 * `--add-required-reviewer` `strings`
 
-	Add required reviewers (comma-separated)
+	Add or promote required reviewers (comma-separated)
 
 * `-B`, `--base` `string`
 
@@ -39,15 +49,11 @@ If there are more than one pull request associated with the current branch, one
 
 * `--remove-label` `strings`
 
-	Remove labels (comma-separated)
-
-* `--remove-optional-reviewer` `strings`
-
-	Remove optional reviewers (comma-separated)
+	Remove labels (comma-separated, use * to remove all)
 
-* `--remove-required-reviewer` `strings`
+* `--remove-reviewer` `strings`
 
-	Remove required reviewers (comma-separated)
+	Remove reviewers (comma-separated, use * to remove all)
 
 * `-t`, `--title` `string`
 

diff --git a/docs/azdo_pr_view.md b/docs/azdo_pr_view.md
@@ -29,14 +29,14 @@ is displayed.
 
 	View pull request commits
 
-* `--format` `string`
-
-	Output format: {json}
-
 * `-q`, `--jq` `expression`
 
 	Filter JSON output using a jq expression
 
+* `--json` `fields`
+
+	Output JSON with the specified fields. Prefix a field with &#39;-&#39; to exclude it.
+
 * `-r`, `--raw`
 
 	View pull request raw
@@ -49,6 +49,11 @@ is displayed.
 ### ALIASES
 
 - `show`
+- `status`
+
+### JSON Fields
+
+`author`, `commits`, `createdOn`, `description`, `id`, `isDraft`, `labels`, `mergeStatus`, `reviewers`, `sourceBranch`, `status`, `targetBranch`, `threads`, `title`, `url`
 
 ### See also
 

diff --git a/docs/azdo_project_create.md b/docs/azdo_project_create.md
@@ -60,6 +60,11 @@ If the organization name is omitted from the project argument, the default confi
 ### ALIASES
 
 - `cr`
+- `c`
+- `new`
+- `n`
+- `add`
+- `a`
 
 ### JSON Fields
 

diff --git a/docs/azdo_service-endpoint.md b/docs/azdo_service-endpoint.md
@@ -5,15 +5,14 @@ Manage Azure DevOps service endpoints (service connections) for projects.
 
 ### Available commands
 
+* [azdo service-endpoint create](./azdo_service-endpoint_create.md)
 * [azdo service-endpoint list](./azdo_service-endpoint_list.md)
 
 ### ALIASES
 
 - `service-endpoints`
-- `serviceendpoint`
 - `serviceendpoints`
 - `se`
-- `sep`
 
 ### See also
 

diff --git a/docs/azdo_service-endpoint_create.md b/docs/azdo_service-endpoint_create.md
@@ -0,0 +1,11 @@
+## Command `azdo service-endpoint create`
+
+Create service connections
+
+### Available commands
+
+* [azdo service-endpoint create azurerm](./azdo_service-endpoint_create_azurerm.md)
+
+### See also
+
+* [azdo service-endpoint](./azdo_service-endpoint.md)
-Original file line number
+Diff line change
@@ Expand Up @@
     ### ALIASES
     - `cr`
+    - `c`
+    - `new`
+    - `n`
+    - `add`
+    - `a`
     ### JSON Fields
@@ Expand Down @@