@kolatts/pncli 2.0.0 → 3.0.0

package/copilot-instructions.md

@@ -1,1351 +0,0 @@
-# pncli — The Paperwork Nightmare CLI
-
-> One command does what three meetings couldn't.
-
-## What is pncli?
-
-pncli is a CLI tool that provides structured JSON access to the enterprise tools your org runs — Jira, Bitbucket, Confluence, SonarQube, SDElements, Azure DevOps Server, Jenkins, JFrog Artifactory, Checkmarx, and local git state, among others. Use it for all interactions with these services. It exists because MCP servers aren't available in this environment — pncli is your agent-friendly shim layer.
-
-## Important
-
-- All commands return JSON to stdout. Parse the JSON to get results.
-- Errors are also JSON with `"ok": false`. Always check the `ok` field.
-- Run all commands from the repository root.
-- Project and repo are auto-detected from git remotes. You rarely need `--project` or `--repo` flags.
-
-## Provider Detection
-
-Before running provider-specific commands, ask the user which tools this repository uses:
-
-1. **Work item tracking:** "Does this repo use **Jira** or **Azure DevOps** for work items and tickets?" — this determines whether to use `pncli jira ...` or `pncli ado work ...` commands.
-2. **Source control:** "Does this repo use **Bitbucket** or **Azure DevOps** for pull requests and code review?" — this determines whether to use `pncli bitbucket ...` or `pncli ado repo ...` commands.
-
-Cache the answers for the session. If the user doesn't know, run `git remote -v` — if a URL contains `/_git/` it's Azure DevOps; if it contains `/scm/` it's Bitbucket.
-
-## Installing Skills
-
-pncli installs agent skills — step-by-step workflow guides for GitHub Copilot and Claude Code — from git-hosted skills marketplaces: plain git repos of plugins that your team publishes. Register a marketplace once:
-
-```
-pncli skills marketplace setup <git-clone-url>
-```
-
-This clones the marketplace repo to `~/.agents/marketplaces/<repo-name>`, registers it in your global pncli config, and installs every plugin's skills into your user-level skills folder — `~/.copilot/skills` for GitHub Copilot (the default), or `~/.claude/skills` with `--claude`. Use `--branch` to pin a specific branch and `--token` for repos that require an HTTP access token (GitHub PAT or Bitbucket token). Run `setup` (or its equivalent, `marketplace add`) again with a different URL to register additional marketplaces.
-
-From then on, one command keeps your skills current:
-
-```
-pncli skills marketplace sync
-```
-
-Sync works because every installed skill carries provenance: pncli writes a `pncli-origin.json` into each skill directory recording which marketplace and plugin it came from, the source URL and branch, and when it was installed, plus a `.pncli-installed.json` index in the skills folder. On each run, sync does a `git pull` on the marketplace clone, then:
-
-- **No new commits upstream** — it skips reinstalling and changes nothing locally (pass `--force` to reinstall anyway).
-- **New commits** — it re-copies the plugin's skills over the installed versions and refreshes their origin records.
-
-Only pncli-managed skills are ever replaced or purged; skills you wrote yourself are left untouched. Run `sync` whenever your marketplace publishes new or updated skills — after a teammate merges a skill change, everyone else just runs `pncli skills marketplace sync` (with the same `--claude` flag they used for setup) to pick it up. With one marketplace registered, sync prompts you to pick a plugin; with several, it first asks which marketplace. Skip the prompts:
-
-```
-pncli skills marketplace sync my-plugin              # skip the plugin picker
-pncli skills marketplace sync all                    # every plugin in the marketplace
-pncli skills marketplace sync --marketplace all      # every plugin from every marketplace
-```
-
-To list registered marketplaces and browse their plugins without installing anything, use `pncli skills marketplace list` and `pncli skills marketplace plugins <name>`. To see what's installed locally, run `pncli skills list --scope user`.
-
-The skills bundled with pncli itself can still be installed straight into a repo with `pncli skills install` (default target: `.agents/skills/`; add `--agent claude-code` for Claude Code).
-
-## Common Workflows
-
-> These workflows are also available as skills — run `pncli skills install` (Copilot default) or `pncli skills install --agent claude-code` (Claude Code) to download them into your repo. Add `--scope user` for global access.
-
-### Review a Pull Request
-
-1. Find the PR for the current branch:
-   `pncli git current-pr`
-2. Get the full diff:
-   `pncli bitbucket diff --pr <id>`
-3. List existing comments:
-   `pncli bitbucket list-comments --pr <id>`
-4. Add review comments:
-   `pncli bitbucket add-inline-comment --pr <id> --file <path> --line <n> --body "..."`
-5. Approve or request changes:
-   `pncli bitbucket approve --pr <id>` or `pncli bitbucket needs-work --pr <id>`
-
-### Address PR Feedback
-
-1. Get the PR and its comments:
-   `pncli bitbucket get-pr --id <id>`
-   `pncli bitbucket list-comments --pr <id>`
-2. Check which comments are unresolved (filter JSON where `resolved: false`)
-3. After making code changes, check local state:
-   `pncli git status`
-   `pncli git diff --staged`
-4. Reply to resolved comments:
-   `pncli bitbucket reply-comment --pr <id> --comment-id <cid> --body "Fixed in <commit>"`
-5. Resolve the comment:
-   `pncli bitbucket resolve-comment --pr <id> --comment-id <cid>`
-
-### Create a Bug from a PR Review Finding
-
-1. Create the Jira issue:
-   `pncli jira create-issue --project <key> --type Bug --summary "..." --description "Found during PR review of PR-<id>"`
-2. Link it to the original story if applicable:
-   `pncli jira link-issue --key <new-key> --link-type "is caused by" --target <original-key>`
-3. Add a PR comment referencing the issue:
-   `pncli bitbucket add-comment --pr <id> --body "Created <new-key> to track this separately"`
-
-### Pre-Merge Quality Check
-
-1. Check quality gate status for the current branch:
-   `pncli sonar quality-gate --branch <branch-name>`
-2. If gate fails, inspect which issues are blocking:
-   `pncli sonar issues --types BUG,VULNERABILITY --statuses OPEN --branch <branch-name>`
-3. Check coverage and key metrics:
-   `pncli sonar measures --branch <branch-name>`
-4. Review security hotspots that need attention:
-   `pncli sonar hotspots --status TO_REVIEW --branch <branch-name>`
-
-### Check Build Status Before Merging
-
-1. Get PR build status:
-   `pncli bitbucket list-builds --pr <id>`
-2. If all green, merge:
-   `pncli bitbucket merge-pr --id <id> --strategy squash --delete-branch`
-
-### Daily Standup Prep
-
-1. Get your open PRs:
-   `pncli bitbucket list-prs --state OPEN --author <your-username>`
-2. Get your assigned Jira issues:
-   `pncli jira search --jql "assignee = currentUser() AND status != Done ORDER BY priority DESC"`
-3. Check recent commits:
-   `pncli git log --count 5`
-
-<!-- COMMAND-REFERENCE:START -->
-## Command Reference
-
-### Git
-
-```
-pncli git status
-
-pncli git diff
-  --staged       Show staged changes only
-  --file <path>  Limit diff to a specific file
-
-pncli git log
-  --count <n>     Number of commits to show (default: "10")
-  --since <date>  Show commits since date (e.g. "2 weeks ago")
-
-pncli git branch
-
-pncli git report
-  --branch <name>  Branch to report on (defaults to current branch)
-  --base <ref>     Base ref to compare against, e.g. "main" (base..branch, or
-  base..HEAD if --branch is omitted)
-  --since <date>   Include commits on or after this date (e.g. "2024-01-01")
-  --until <date>   Include commits on or before this date (e.g. "2024-12-31")
-  --csv            Output as CSV instead of JSON
-
-pncli git current-pr
-```
-
-### Jira
-
-```
-pncli jira get-issue
-  --key <issue-key>  Issue key (e.g. PROJ-123)
-
-pncli jira create-issue
-  --project <key>         Project key
-  --type <type>           Issue type (Bug, Story, Task, ...)
-  --summary <text>        Issue summary (required, unless supplied via
-  --input-file)
-  --description <text>    Issue description
-  --priority <name>       Priority name
-  --assignee <accountId>  Assignee account ID
-  --labels <labels>       Comma-separated labels
-  --parent <key>          Parent issue key — sets fields.parent in the create
-  payload
-  --field <Name=value>    Custom field value; use Name=@file.json to read value
-  from file (repeatable) (default: [])
-  --fields-file <path>    Path to a JSON file mapping field names/IDs to their
-  Jira API values
-  --input-file <path>     JSON file describing the whole issue ({ project,
-  issueType, fields: {...} }); '-' = stdin. CLI flags
-  override matching keys. See: pncli jira schema
-
-pncli jira update-issue
-  --key <issue-key>       Issue key
-  --summary <text>        New summary
-  --description <text>    New description
-  --priority <name>       New priority
-  --assignee <accountId>  New assignee account ID
-  --labels <labels>       Comma-separated labels
-  --field <Name=value>    Custom field value; use Name=@file.json to read value
-  from file (repeatable) (default: [])
-  --fields-file <path>    Path to a JSON file mapping field names/IDs to their
-  Jira API values
-  --input-file <path>     JSON file describing fields to update ({ fields: {...}
-  }); '-' = stdin. CLI flags override matching keys.
-  See: pncli jira schema
-
-pncli jira schema
-  --example-only  Print only the runnable example JSON (no envelope) — pipeable
-  straight into --input-file
-
-pncli jira transition-issue
-  --key <issue-key>          Issue key
-  --transition <name-or-id>  Transition name or ID
-
-pncli jira list-transitions
-  --key <issue-key>  Issue key
-
-pncli jira add-comment
-  --key <issue-key>  Issue key
-  --body <text>      Comment text
-
-pncli jira list-comments
-  --key <issue-key>  Issue key
-
-pncli jira search
-  --jql <query>      JQL query string
-  --jql-file <path>  Path to a file containing the JQL query ('-' = stdin)
-  --max-results <n>  Maximum number of results
-
-pncli jira add-label
-  --key <issue-key>  Issue key
-  --labels <labels>  Comma-separated labels to add
-
-pncli jira remove-label
-  --key <issue-key>  Issue key
-  --labels <labels>  Comma-separated labels to remove
-
-pncli jira assign
-  --key <issue-key>       Issue key
-  --assignee <accountId>  Assignee account ID
-
-pncli jira link-issue
-  --key <issue-key>     Source issue key
-  --link-type <type>    Link type name or ID
-  --target <issue-key>  Target issue key
-
-pncli jira add-attachment
-  --key <issue-key>  Issue key (e.g. PROJ-123)
-  --file <path>      Path to the file to upload
-
-pncli jira list-attachments
-  --key <issue-key>  Issue key (e.g. PROJ-123)
-
-pncli jira download-attachment
-  --key <issue-key>     Issue key (e.g. PROJ-123)
-  --attachment-id <id>  Attachment ID from list-attachments output
-  --dir <path>          Output directory (default: .pncli relative to cwd)
-
-pncli jira fields
-  --discover           Fetch field metadata from Jira API
-  --custom-only        Show only custom fields (requires --discover)
-  --project <key>      Project key — fetches allowedValues for select fields via
-  createmeta (requires --discover)
-  --issue-type <type>  Filter allowedValues to a specific issue type (requires
-  --project)
-
-pncli jira list-boards
-  --project <key>  Project key
-
-pncli jira list-sprints
-  --board <id>      Board ID
-  --project <key>   Project key — resolves to that project's board(s)
-  --state <states>  Comma-separated states to filter (active,future,closed)
-
-pncli jira set-sprint
-  --key <issue-key>  Issue key
-  --sprint <id>      Sprint ID (from list-sprints)
-```
-
-### Bitbucket
-
-```
-pncli bitbucket create-repo
-  --name <name>         Repository name (slug)
-  --description <desc>  Repository description
-  --project <key>       Bitbucket project key (overrides parent --project)
-
-pncli bitbucket list-prs
-  --state <state>        PR state: OPEN|MERGED|DECLINED|ALL (default: "OPEN")
-  --author <username>    Filter by author username
-  --reviewer <username>  Filter by reviewer username
-
-pncli bitbucket get-pr
-  --id <pr-id>  Pull request ID
-
-pncli bitbucket create-pr
-  --title <title>       PR title
-  --source <branch>     Source branch
-  --target <branch>     Target branch (defaults to config)
-  --description <desc>  PR description
-  --reviewers <users>   Comma-separated reviewer usernames
-  --project <key>       Bitbucket project key (overrides parent --project; use
-  ~username for personal repos)
-  --repo <slug>         Bitbucket repository slug (overrides parent --repo)
-
-pncli bitbucket update-pr
-  --id <pr-id>          Pull request ID
-  --title <title>       New title
-  --description <desc>  New description
-  --reviewers <users>   Comma-separated reviewer usernames
-
-pncli bitbucket merge-pr
-  --id <pr-id>           Pull request ID
-  --strategy <strategy>  Merge strategy: merge|squash|ff
-  --delete-branch        Delete source branch after merge
-
-pncli bitbucket decline-pr
-  --id <pr-id>  Pull request ID
-
-pncli bitbucket list-comments
-  --pr <pr-id>       Pull request ID
-  --no-with-replies  Exclude replies; return top-level comments only
-  --inline-only      Return only inline file comments
-  --general-only     Return only general (non-inline) PR comments
-
-pncli bitbucket add-comment
-  --pr <pr-id>   Pull request ID
-  --body <text>  Comment text
-
-pncli bitbucket add-inline-comment
-  --pr <pr-id>        Pull request ID
-  --file <path>       File path
-  --line <n>          Line number
-  --body <text>       Comment text
-  --line-type <type>  Line type: ADDED|REMOVED|CONTEXT (default: "ADDED")
-
-pncli bitbucket reply-comment
-  --pr <pr-id>       Pull request ID
-  --comment-id <id>  Comment ID to reply to
-  --body <text>      Reply text
-
-pncli bitbucket resolve-comment
-  --pr <pr-id>       Pull request ID
-  --comment-id <id>  Comment ID
-  --version <n>      Comment version (default: "0")
-
-pncli bitbucket delete-comment
-  --pr <pr-id>       Pull request ID
-  --comment-id <id>  Comment ID
-  --version <n>      Comment version (default: "0")
-
-pncli bitbucket diff
-  --pr <pr-id>         Pull request ID
-  --file <path>        Limit diff to a specific file
-  --context-lines <n>  Lines of context around changes
-
-pncli bitbucket list-files
-  --pr <pr-id>  Pull request ID
-
-pncli bitbucket approve
-  --pr <pr-id>  Pull request ID
-
-pncli bitbucket unapprove
-  --pr <pr-id>  Pull request ID
-
-pncli bitbucket needs-work
-  --pr <pr-id>  Pull request ID
-
-pncli bitbucket list-reviewers
-  --pr <pr-id>  Pull request ID
-
-pncli bitbucket add-reviewer
-  --pr <pr-id>       Pull request ID
-  --user <username>  Username to add as a reviewer
-
-pncli bitbucket list-builds
-  --pr <pr-id>  Pull request ID
-
-pncli bitbucket get-build-status
-  --commit <sha>  Commit SHA
-```
-
-### Github
-
-```
-pncli github create-repo
-  --name <name>         Repository name
-  --description <desc>  Repository description
-  --private             Create as a private repository
-  --auto-init           Initialize with a README
-
-pncli github create-issue
-  --title <title>     Issue title
-  --body <body>       Issue body (markdown)
-  --body-file <path>  Read issue body from a file (use - for stdin); overridden
-  by --body
-  --label <label>     Label to apply (repeatable) (default: [])
-  --assignee <login>  Assignee login (repeatable) (default: [])
-
-pncli github list-prs
-  --state <state>  PR state (choices: "open", "closed", "all", default: "open")
-  --head <branch>  Filter by head branch (user:branch)
-  --base <branch>  Filter by base branch
-
-pncli github get-pr
-  --number <n>  Pull request number
-
-pncli github create-pr
-  --title <title>     PR title
-  --head <branch>     Source branch (or user:branch for forks)
-  --base <branch>     Target branch (defaults to config or main)
-  --body <body>       PR description
-  --body-file <path>  Read PR description from a file (use - for stdin);
-  overridden by --body
-  --draft             Create as draft PR
-  --owner <owner>     GitHub owner (overrides parent --owner)
-  --repo <repo>       GitHub repository name (overrides parent --repo)
-
-pncli github update-pr
-  --number <n>     Pull request number
-  --title <title>  New title
-  --body <body>    New description
-  --base <branch>  New base branch
-
-pncli github merge-pr
-  --number <n>            Pull request number
-  --method <method>       Merge method (choices: "merge", "squash", "rebase",
-  default: "merge")
-  --commit-title <title>  Commit title for merge/squash
-  --commit-message <msg>  Commit message for merge/squash
-
-pncli github close-pr
-  --number <n>  Pull request number
-
-pncli github list-comments
-  --number <n>  Pull request number
-
-pncli github add-comment
-  --number <n>   Pull request number
-  --body <text>  Comment text
-
-pncli github list-review-comments
-  --number <n>  Pull request number
-
-pncli github add-inline-comment
-  --number <n>    Pull request number
-  --commit <sha>  Commit SHA the comment is on
-  --file <path>   File path
-  --line <n>      Line number
-  --body <text>   Comment text
-  --side <side>   Comment side (choices: "LEFT", "RIGHT", default: "RIGHT")
-
-pncli github reply-comment
-  --number <n>       Pull request number
-  --comment-id <id>  Review comment ID to reply to
-  --body <text>      Reply text
-
-pncli github delete-comment
-  --comment-id <id>  Comment ID
-
-pncli github delete-review-comment
-  --comment-id <id>  Review comment ID
-
-pncli github diff
-  --number <n>  Pull request number
-
-pncli github list-files
-  --number <n>  Pull request number
-
-pncli github list-reviews
-  --number <n>  Pull request number
-
-pncli github approve
-  --number <n>   Pull request number
-  --body <text>  Review body text
-
-pncli github request-changes
-  --number <n>   Pull request number
-  --body <text>  Review feedback text
-
-pncli github list-reviewers
-  --number <n>  Pull request number
-
-pncli github get-status
-  --ref <ref>  Git ref (branch, tag, or commit SHA)
-
-pncli github list-checks
-  --ref <ref>  Git ref (branch, tag, or commit SHA)
-```
-
-### Confluence
-
-```
-pncli confluence get-page
-  --id <page-id>     Page ID
-  --expand <fields>  Comma-separated fields to expand (default:
-  "body.storage,version,space,ancestors")
-
-pncli confluence get-page-by-title
-  --space <key>    Space key
-  --title <title>  Page title
-
-pncli confluence list-pages
-  --space <key>  Space key
-  --limit <n>    Max total pages to return (default: all)
-  --start <n>    Offset for first result
-
-pncli confluence get-page-children
-  --id <page-id>  Parent page ID
-
-pncli confluence get-labels
-  --id <page-id>  Page ID
-
-pncli confluence search
-  --cql <query>      CQL query string (e.g. "space=PROJ AND type=page")
-  --limit <n>        Maximum number of results (default: "25")
-  --start <n>        Offset for first result (default: "0")
-  --expand <fields>  Comma-separated fields to expand
-
-pncli confluence create-page
-  --space <key>              Space key
-  --title <title>            Page title
-  --body <html>              Page body (storage format HTML or Markdown when
-  --markdown is set)
-  --body-file <path>         Path to a file containing the page body ('-' =
-  stdin)
-  --markdown                 Convert body from Markdown to storage format via
-  Confluence API
-  --parent-id <id>           Parent page ID (to nest under a page)
-  --representation <format>  Body format: storage (default) or wiki (default:
-  "storage")
-
-pncli confluence update-page
-  --id <page-id>             Page ID
-  --title <title>            New page title
-  --body <html>              New page body (storage format HTML or Markdown when
-  --markdown is set)
-  --body-file <path>         Path to a file containing the new page body ('-' =
-  stdin)
-  --markdown                 Convert body from Markdown to storage format via
-  Confluence API
-  --status <status>          Page status: current (default) or draft (default:
-  "current")
-  --representation <format>  Body format: storage (default) or wiki (default:
-  "storage")
-
-pncli confluence delete-page
-  --id <page-id>  Page ID
-
-pncli confluence list-comments
-  --id <page-id>  Page ID
-
-pncli confluence add-comment
-  --id <page-id>             Page ID
-  --body <text>              Comment body (storage format HTML)
-  --representation <format>  Body format: storage (default) or wiki (default:
-  "storage")
-
-pncli confluence add-label
-  --id <page-id>    Page ID
-  --labels <names>  Comma-separated label names
-
-pncli confluence remove-label
-  --id <page-id>  Page ID
-  --label <name>  Label name to remove
-
-pncli confluence list-spaces
-  --type <type>  Space type: global or personal
-  --limit <n>    Max total spaces to return (default: all)
-
-pncli confluence get-space
-  --key <space-key>  Space key
-
-pncli confluence list-attachments
-  --id <page-id>  Page ID
-
-pncli confluence upload-attachment
-  --id <page-id>    Page ID
-  --file <path>     Path to the file to upload
-  --comment <text>  Optional comment to attach to the file version
-
-pncli confluence download-attachment
-  --id <attachment-id>  Attachment content ID
-  --dir <path>          Output directory (default: .pncli relative to cwd)
-
-pncli confluence delete-attachment
-  --id <attachment-id>  Attachment content ID
-
-pncli confluence get-page-history
-  --id <page-id>  Page ID
-```
-
-### Sonar
-
-```
-pncli sonar quality-gate
-  --project <key>  SonarQube project key (or set defaults.sonar.project in
-  config)
-  --branch <name>  Branch name
-
-pncli sonar issues
-  --project <key>      SonarQube project key (or set defaults.sonar.project in
-  config)
-  --severities <list>  Filter by severity: BLOCKER,CRITICAL,MAJOR,MINOR,INFO
-  (comma-separated)
-  --types <list>       Filter by type: BUG,VULNERABILITY,CODE_SMELL
-  (comma-separated)
-  --statuses <list>    Filter by status: OPEN,CONFIRMED,REOPENED,RESOLVED,CLOSED
-  (comma-separated)
-  --branch <name>      Branch name
-  --resolved <bool>    Filter resolved issues: true or false
-  --page <n>           Page number (1-based) (default: "1")
-  --page-size <n>      Results per page (max 500) (default: "100")
-  --all                Fetch all pages (consider --output-file for large
-  results; ignores --page/--page-size)
-
-pncli sonar measures
-  --project <key>   SonarQube project key (or set defaults.sonar.project in
-  config)
-  --metrics <list>  Comma-separated metric keys (default:
-  "coverage,duplicated_lines_density,bugs,vulnerabilities,code_smells,sqale_rating,reliability_rating,security_rating,ncloc")
-  --branch <name>   Branch name
-
-pncli sonar projects
-  --query <text>   Search query
-  --page <n>       Page number (1-based) (default: "1")
-  --page-size <n>  Results per page (default: "100")
-  --all            Fetch all pages (consider --output-file for large results)
-
-pncli sonar hotspots
-  --project <key>      SonarQube project key (or set defaults.sonar.project in
-  config)
-  --status <status>    Filter: TO_REVIEW or REVIEWED
-  --resolution <list>  Filter: FIXED,SAFE,ACKNOWLEDGED (comma-separated)
-  --branch <name>      Branch name
-  --page <n>           Page number (1-based) (default: "1")
-  --page-size <n>      Results per page (default: "100")
-  --all                Fetch all pages (consider --output-file for large
-  results)
-```
-
-### Sde
-
-```
-pncli sde server-info
-
-pncli sde whoami
-
-pncli sde users
-  --email <email>      Filter by email address
-  --first-name <name>  Filter by first name
-  --last-name <name>   Filter by last name
-  --active <bool>      Filter by active status: true or false
-  --page <n>           Page number (1-based) (default: "1")
-  --page-size <n>      Results per page (default: "100")
-  --all                Fetch all pages (consider --output-file for large
-  results)
-
-pncli sde projects
-  --name <name>       Filter by project name
-  --search <text>     Text search on name and profile
-  --active <val>      Filter by active status: true, false, or all
-  --ordering <field>  Sort by: name, created, updated (prefix with - for
-  descending)
-  --expand <fields>   Expand nested fields (comma-separated):
-  application,business_unit,creator
-  --include <fields>  Include extra fields (comma-separated):
-  task_counts,permissions
-  --page <n>          Page number (1-based) (default: "1")
-  --page-size <n>     Results per page (default: "100")
-  --all               Fetch all pages (consider --output-file for large results)
-
-pncli sde project
-  --id <id>           Project ID (or set defaults.sde.project in config)
-  --expand <fields>   Expand nested fields (comma-separated):
-  application,business_unit,creator
-  --include <fields>  Include extra fields (comma-separated):
-  task_counts,permissions
-
-pncli sde tasks
-  --project <id>         Project ID (or set defaults.sde.project in config)
-  --phase <slug>         Filter by phase slug (e.g. development,
-  architecture-design)
-  --priority <n>         Filter by priority (1-10)
-  --status <id>          Filter by status ID (e.g. TS1, TS2)
-  --assigned-to <email>  Filter by assignee email
-  --source <val>         Filter by source: default, custom, manual, project
-  --verification <val>   Filter by verification: pass, fail, partial, none
-  --tag <name>           Filter by tag name
-  --accepted <bool>      Filter by accepted status: true or false
-  --relevant <bool>      Filter by relevant status: true or false
-  --expand <fields>      Expand nested fields (comma-separated):
-  status,phase,problem,text
-  --include <fields>     Include extra fields (comma-separated):
-  how_tos,last_note,references,regulation_sections
-  --page <n>             Page number (1-based) (default: "1")
-  --page-size <n>        Results per page (default: "100")
-  --all                  Fetch all pages (consider --output-file for large
-  results)
-
-pncli sde task
-  --project <id>      Project ID (or set defaults.sde.project in config)
-  --task <id>         Task ID (e.g. T21)
-  --expand <fields>   Expand nested fields (comma-separated):
-  status,phase,problem,text
-  --include <fields>  Include extra fields (comma-separated):
-  how_tos,last_note,references
-
-pncli sde threats
-  --project <id>       Project ID (or set defaults.sde.project in config)
-  --severity <n>       Filter by severity (1-10)
-  --search <text>      Full-text search on title and threat ID
-  --ordering <field>   Sort by: threat__severity, threat_id, status (prefix -
-  for descending)
-  --capec-id <id>      Filter by CAPEC attack pattern ID
-  --component-id <id>  Filter by component ID
-  --page <n>           Page number (1-based) (default: "1")
-  --page-size <n>      Results per page (default: "100")
-  --all                Fetch all pages (consider --output-file for large
-  results)
-```
-
-### Deps
-
-```
-pncli deps frisk
-  --ecosystem <ecosystem>  Filter to one ecosystem: npm, nuget, maven, all
-  (default: "all")
-  --direct-only            Only scan direct dependencies (default: include
-  transitive) (default: false)
-  --include-dev            Include dev/test dependencies (default: false)
-  --source <source>        Vulnerability source (choices: "osv", "sonatype",
-  "sonatypeiq", "all", default: "osv")
-  --application-id <id>    Sonatype IQ Server application ID (required when
-  --source sonatypeiq)
-
-pncli deps scan
-  --ecosystem <ecosystem>  Filter to one ecosystem: npm, nuget, maven, all
-  (default: "all")
-  --include-transitive     Include transitive dependencies (default: false)
-  --include-dev            Include dev/test dependencies (default: false)
-
-pncli deps diff
-  --from <ref>             Base git ref (commit, tag, or branch)
-  --to <ref>               Target git ref (default: working tree)
-  --ecosystem <ecosystem>  Filter to one ecosystem: npm, nuget, maven, all
-  (default: "all")
-  --include-dev            Include dev/test dependencies (default: false)
-
-pncli deps outdated
-  --ecosystem <ecosystem>  Filter to one ecosystem: npm, nuget, maven, all
-  (default: "all")
-  --major                  Only show major version bumps
-  --minor                  Only show minor version bumps or higher
-  --patch                  Only show patch version bumps or higher
-
-pncli deps license-check
-  --ecosystem <ecosystem>  Filter to one ecosystem: npm, nuget, maven, all
-  (default: "all")
-  --include-dev            Include dev/test dependencies (default: false)
-
-pncli deps connectivity
-```
-
-### Config
-
-```
-pncli config init
-  --repo      Write repo config (.pncli.json) instead of global config
-
-pncli config show
-
-pncli config set
-  --repo      Write to repo config (.pncli.json) instead of global config
-
-pncli config test
-
-pncli config check
-  --output <format>  Output format: json or table (default: "json")
-```
-
-### Ado
-
-```
-pncli ado whoami
-
-pncli ado connection-data
-
-pncli ado project list-collections
-
-pncli ado project list
-
-pncli ado project get
-  --name <project>  Project name
-
-pncli ado work get
-  --id <n>    Work item ID
-
-pncli ado work create
-  --type <type>         Work item type (e.g. Bug, Task, User Story) (required,
-  unless supplied via --input-file)
-  --title <title>       Work item title (required, unless supplied via
-  --input-file)
-  --description <text>  Description
-  --assignee <user>     Assigned to (display name or email)
-  --priority <n>        Priority (1-4)
-  --parent <id>         Parent work item ID — creates a parent link after
-  creation
-  --field <name=value>  Additional field (repeatable) (default: [])
-  --input-file <path>   JSON file describing the work item ({ type, fields:
-  {...} }); '-' = stdin. CLI flags override matching keys.
-  See: pncli ado work schema
-
-pncli ado work update
-  --id <n>              Work item ID
-  --field <name=value>  Field to update (repeatable) (default: [])
-  --input-file <path>   JSON file describing fields to update ({ fields: {...}
-  }); '-' = stdin. CLI flags override matching keys. See:
-  pncli ado work schema
-
-pncli ado work transition
-  --id <n>         Work item ID
-  --state <state>  New state (e.g. Active, Resolved, Closed)
-
-pncli ado work assign
-  --id <n>     Work item ID
-  --to <user>  User display name or email
-
-pncli ado work link
-  --id <a>      Source work item ID
-  --to <b>      Target work item ID
-  --type <rel>  Link type (related|parent|child|duplicate|duplicate-of)
-  (default: "related")
-
-pncli ado work search
-  --wiql <query>  WIQL query string
-
-pncli ado work list-comments
-  --id <n>    Work item ID
-
-pncli ado work add-comment
-  --id <n>       Work item ID
-  --body <text>  Comment text
-
-pncli ado work add-tag
-  --id <n>       Work item ID
-  --tags <tags>  Semicolon- or comma-separated tags to add
-
-pncli ado work remove-tag
-  --id <n>       Work item ID
-  --tags <tags>  Semicolon- or comma-separated tags to remove
-
-pncli ado work list-attachments
-  --id <n>    Work item ID
-
-pncli ado work add-attachment
-  --id <n>          Work item ID
-  --file <path>     Path to the file to upload
-  --comment <text>  Optional comment for the attachment
-
-pncli ado work download-attachment
-  --id <n>                Work item ID
-  --attachment-id <guid>  Attachment ID from work list-attachments output
-  --dir <path>            Output directory (default: .pncli relative to cwd)
-
-pncli ado work list-areas
-  --depth <n>  Depth of the area tree to retrieve (default: "10")
-
-pncli ado work list-iterations
-  --depth <n>  Depth of the iteration tree to retrieve (default: "10")
-
-pncli ado work types
-  --discover  Fetch from server (always true for this command)
-  --save      Save discovered types to ~/.pncli/config.json
-
-pncli ado work list-states
-  --type <type>  Work item type name (e.g. Bug)
-
-pncli ado work fields
-  --type <type>  Scope to fields for a specific work item type (e.g. Bug)
-  --custom-only  Exclude System.* and Microsoft.VSTS.* fields
-  --discover     Fetch from server (always true for this command)
-  --save         Save discovered fields and aliases to ~/.pncli/config.json
-
-pncli ado work schema
-  --example-only  Print only the runnable example JSON (no envelope) — pipeable
-  straight into --input-file
-
-pncli ado repo list
-
-pncli ado repo create
-  --name <name>  Repository name
-
-pncli ado repo get
-
-pncli ado repo list-prs
-  --state <state>     PR state: active|abandoned|completed|all (default:
-  "active")
-  --creator <alias>   Filter by creator
-  --reviewer <alias>  Filter by reviewer
-
-pncli ado repo get-pr
-  --id <n>    Pull request ID
-
-pncli ado repo create-pr
-  --title <title>       PR title
-  --source <branch>     Source branch
-  --target <branch>     Target branch (default: main) (default: "main")
-  --description <text>  PR description
-  --reviewers <ids>     Comma-separated reviewer IDs or display names
-  --draft               Create as a draft pull request
-
-pncli ado repo update-pr
-  --id <n>              Pull request ID
-  --title <title>       New title
-  --description <text>  New description
-  --reviewers <ids>     Comma-separated reviewer IDs
-  --draft <bool>        Set draft status: true|false
-
-pncli ado repo merge-pr
-  --id <n>         Pull request ID
-  --strategy <s>   Merge strategy: noFastForward|squash|rebase|rebaseMerge
-  (default: "noFastForward")
-  --delete-source  Delete source branch after merge
-
-pncli ado repo abandon-pr
-  --id <n>    Pull request ID
-
-pncli ado repo list-comments
-  --pr <n>        Pull request ID
-  --inline-only   Return only inline file comments
-  --general-only  Return only general PR comments
-
-pncli ado repo add-comment
-  --pr <n>       Pull request ID
-  --body <text>  Comment text
-
-pncli ado repo add-inline-comment
-  --pr <n>            Pull request ID
-  --file <path>       File path
-  --line <n>          Line number
-  --body <text>       Comment text
-  --line-type <side>  Line side: left|right (default: right) (default: "right")
-
-pncli ado repo reply-comment
-  --pr <n>          Pull request ID
-  --thread-id <id>  Thread ID
-  --body <text>     Reply text
-
-pncli ado repo resolve-comment
-  --pr <n>          Pull request ID
-  --thread-id <id>  Thread ID
-
-pncli ado repo delete-comment
-  --pr <n>           Pull request ID
-  --thread-id <id>   Thread ID
-  --comment-id <id>  Comment ID
-
-pncli ado repo list-files
-  --pr <n>    Pull request ID
-
-pncli ado repo diff
-  --pr <n>    Pull request ID
-  --path <p>  Filter diff to a specific file path
-
-pncli ado repo get-build-status
-  --commit <sha>  Commit SHA
-
-pncli ado repo list-reviewers
-  --pr <n>    Pull request ID
-
-pncli ado repo approve
-  --pr <n>    Pull request ID
-
-pncli ado repo unapprove
-  --pr <n>    Pull request ID
-
-pncli ado repo wait-for-author
-  --pr <n>    Pull request ID
-
-pncli ado repo list-builds
-  --pr <n>    Pull request ID
-
-pncli ado pipeline list
-
-pncli ado pipeline get
-  --id <n>    Pipeline definition ID
-
-pncli ado pipeline run
-  --id <n>           Pipeline definition ID
-  --branch <ref>     Source branch (e.g. refs/heads/main or main)
-  --parameter <k=v>  Build parameter (repeatable) (default: [])
-  --wait             Wait for the run to complete before returning
-  --timeout <s>      Max wait time in seconds (default 600) (default: "600")
-  --poll <s>         Poll interval in seconds (default 10) (default: "10")
-
-pncli ado pipeline list-runs
-  --definition <id>  Filter by definition ID
-  --name <name>      Filter by pipeline name (resolved to definition ID; use
-  pipeline list to see names)
-  --branch <ref>     Filter by branch name
-  --status <filter>  Filter by status (inProgress|completed|cancelling|...)
-  --top <n>          Maximum results (default: "50")
-
-pncli ado pipeline get-run
-  --id <n>    Build ID
-
-pncli ado pipeline cancel-run
-  --id <n>    Build ID
-
-pncli ado pipeline logs
-  --build-id <n>  Build (run) ID — from pipeline list-runs or get-run
-  --id <n>        Build (run) ID — alias for --build-id (kept for backwards
-  compatibility)
-  --log-id <n>    Specific log ID (omit to list all logs)
-```
-
-### Jenkins
-
-```
-pncli jenkins pipeline list
-  --folder <name>  Folder name to enumerate (supports nested folders:
-  parentFolder/childFolder)
-
-pncli jenkins pipeline get
-  --name <job>  Job name (use folder/job for folder-scoped jobs)
-
-pncli jenkins pipeline run
-  --name <job>       Job name (use folder/job for folder-scoped jobs)
-  --parameter <k=v>  Build parameter (repeatable) (default: [])
-  --wait             Wait for the build to complete before returning
-  --timeout <s>      Max wait time in seconds per phase (queue-wait and
-  build-wait each get this budget; default 600) (default:
-  "600")
-  --poll <s>         Poll interval in seconds (default 10) (default: "10")
-
-pncli jenkins pipeline list-runs
-  --name <job>  Job name (use folder/job for folder-scoped jobs)
-  --top <n>     Maximum number of builds to return (default 25) (default: "25")
-
-pncli jenkins pipeline get-run
-  --name <job>  Job name (use folder/job for folder-scoped jobs)
-  --number <n>  Build number
-
-pncli jenkins pipeline logs
-  --name <job>  Job name (use folder/job for folder-scoped jobs)
-  --number <n>  Build number
-```
-
-### Artifactory
-
-```
-pncli artifactory ping
-
-pncli artifactory repos
-  --type <type>          Filter by type: local, virtual, remote, federated
-  --package-type <type>  Filter by package type: npm, maven, nuget, docker,
-  pypi, etc.
-
-pncli artifactory artifact-info
-
-pncli artifactory properties-get
-
-pncli artifactory properties-set
-  --recursive  Apply recursively to folder contents (default: false)
-
-pncli artifactory search
-  --repo <name>     Filter by repository key
-  --name <pattern>  Filter by artifact name (supports * and ? wildcards)
-  --path <pattern>  Filter by artifact path (supports * and ? wildcards)
-  --after <date>    Created after this date (ISO 8601, e.g. 2024-01-01)
-  --before <date>   Created before this date (ISO 8601)
-  --limit <n>       Maximum results to return (default: 100) (default: "100")
-  --properties      Include artifact properties in results (default: false)
-
-pncli artifactory builds
-  --timeout <s>  Request timeout in seconds (default 60; increase for large
-  Artifactory instances) (default: "60")
-
-pncli artifactory build-runs
-
-pncli artifactory build-info
-```
-
-### Checkmarx
-
-```
-pncli checkmarx project list
-
-pncli checkmarx project get
-  --id <id>   Project UUID
-
-pncli checkmarx scan list
-  --project <id>  Filter by project UUID
-  --last <n>      Return only the last N scans
-
-pncli checkmarx scan get
-  --id <id>   Scan UUID
-
-pncli checkmarx scan stats
-  --id <id>   Scan UUID
-```
-
-### Servicenow
-
-```
-pncli servicenow change list
-  --state <state>       Filter by state (e.g. -1=Pending, 1=Open, 2=Work in
-  Progress, 3=Closed Complete)
-  --assigned-to <user>  Filter by assigned user sys_id or display name
-  --limit <n>           Maximum number of results (default: "25")
-  --fields <fields>     Comma-separated field names to return
-
-pncli servicenow change get
-  --id <id>   Change request sys_id or number (e.g. CHG0001234)
-
-pncli servicenow change create
-  --short-description <text>  Short description (title)
-  --description <text>        Full description
-  --type <type>               Change type: normal, standard, or emergency
-  (default: "normal")
-  --priority <n>              Priority: 1=Critical, 2=High, 3=Moderate, 4=Low
-  --assigned-to <user>        Assigned user sys_id
-  --assignment-group <group>  Assignment group sys_id
-  --start-date <datetime>     Planned start date (yyyy-MM-dd HH:mm:ss)
-  --end-date <datetime>       Planned end date (yyyy-MM-dd HH:mm:ss)
-
-pncli servicenow change update
-  --id <sys_id>               Change request sys_id
-  --short-description <text>  New short description
-  --description <text>        New description
-  --state <state>             New state value
-  --priority <n>              New priority
-  --assigned-to <user>        New assigned user sys_id
-  --start-date <datetime>     New planned start date
-  --end-date <datetime>       New planned end date
-
-pncli servicenow change close
-  --id <sys_id>         Change request sys_id
-  --close-notes <text>  Closure notes
-  --close-code <code>   Close code (e.g. successful, unsuccessful)
-```
-
-### Contrast
-
-```
-pncli contrast apps list
-  --limit <n>   Maximum number of results (default: "25")
-  --offset <n>  Pagination offset (default: "0")
-
-pncli contrast findings list
-  --app <app-id>      Application ID (UUID)
-  --severity <level>  Filter by severity: CRITICAL, HIGH, MEDIUM, LOW, NOTE
-  --status <status>   Filter by status: REPORTED, CONFIRMED, SUSPICIOUS,
-  NOT_A_PROBLEM, REMEDIATED, FIXED
-  --limit <n>         Maximum number of results (default: "25")
-  --offset <n>        Pagination offset (default: "0")
-
-pncli contrast findings get
-  --app <app-id>      Application ID (UUID)
-  --trace <trace-id>  Trace/finding UUID
-```
-
-### Sonatypeiq
-
-```
-pncli sonatypeiq applications list
-  --organization-id <id>  Filter by organization ID
-
-pncli sonatypeiq applications get
-  --public-id <id>  Application public ID
-
-pncli sonatypeiq organizations list
-
-pncli sonatypeiq policies list
-  --organization-id <id>  Filter by organization ID
-```
-
-### Skills
-
-```
-pncli skills install
-  --agent <agent>  Target agent host: github-copilot | claude-code (default:
-  "github-copilot")
-  --scope <scope>  Installation scope: project | user (default: "project")
-  --target <dir>   Override install directory (ignores --agent and --scope)
-
-pncli skills list
-  --agent <agent>  Target agent host: github-copilot | claude-code (default:
-  "github-copilot")
-  --scope <scope>  Installation scope: project | user (default: "project")
-  --target <dir>   Override skills directory to scan
-
-pncli skills uninstall
-  --agent <agent>  Target agent host: github-copilot | claude-code (default:
-  "github-copilot")
-  --scope <scope>  Installation scope to uninstall from: project | user
-  (default: "user")
-  --claude         Shorthand for --agent claude-code
-  --target <dir>   Override skills directory
-
-pncli skills marketplace add
-  --name <name>      Human-readable name for this marketplace (default: derived
-  from URL)
-  --branch <branch>  Branch to clone (default: remote HEAD)
-  --token <token>    HTTP access token for authenticated clone and pull (GitHub
-  PAT or Bitbucket token)
-  --agent <agent>    Target agent host for plugin install: github-copilot |
-  claude-code (default: github-copilot)
-  --claude           Shorthand for --agent claude-code
-
-pncli skills marketplace setup
-  --name <name>      Human-readable name for this marketplace (default: derived
-  from URL)
-  --branch <branch>  Branch to clone (default: remote HEAD)
-  --token <token>    HTTP access token for authenticated clone and pull (GitHub
-  PAT or Bitbucket token)
-  --agent <agent>    Target agent host for plugin install: github-copilot |
-  claude-code (default: github-copilot)
-  --claude           Shorthand for --agent claude-code
-
-pncli skills marketplace list
-
-pncli skills marketplace plugins
-
-pncli skills marketplace remove
-
-pncli skills marketplace sync
-  --marketplace <name>  Marketplace name to sync, or "all" to sync every
-  registered marketplace (skips interactive selection)
-  --agent <agent>       Target agent host: github-copilot | claude-code
-  (default: github-copilot)
-  --claude              Shorthand for --agent claude-code
-  --force               Reinstall even if a marketplace has no new changes
-  (applies to single-plugin and "all" installs alike)
-
-pncli skills marketplace purge-plugin
-  --marketplace <name>  Restrict purge to skills from this marketplace (by name
-  or repo URL)
-  --agent <agent>       Target agent host: github-copilot | claude-code
-  (default: github-copilot)
-  --claude              Shorthand for --agent claude-code
-  --scope <scope>       Installation scope: project | user (default: user)
-  --target <dir>        Override skills directory
-
-pncli skills marketplace disable
-  --marketplace <name>  Restrict to skills from this marketplace (by name or
-  repo URL)
-  --agent <agent>       Target agent host: github-copilot | claude-code
-  (default: github-copilot)
-  --claude              Shorthand for --agent claude-code
-  --scope <scope>       Installation scope: project | user (default: user)
-  --target <dir>        Override skills directory
-
-pncli skills marketplace enable
-  --marketplace <name>  Restrict to skills from this marketplace (by name or
-  repo URL)
-  --agent <agent>       Target agent host: github-copilot | claude-code
-  (default: github-copilot)
-  --claude              Shorthand for --agent claude-code
-  --scope <scope>       Installation scope: project | user (default: user)
-  --target <dir>        Override skills directory
-
-pncli skills marketplace manage
-  --agent <agent>  Target agent host: github-copilot | claude-code (default:
-  github-copilot)
-  --claude         Shorthand for --agent claude-code
-  --scope <scope>  Installation scope: project | user (default: user)
-  --target <dir>   Override skills directory
-
-pncli skills purge-user
-  --agent <agent>  Target agent host: github-copilot | claude-code (default:
-  github-copilot)
-  --claude         Shorthand for --agent claude-code
-  --force          Skip confirmation — remove all skills without prompting
-```
-
-### Jwt
-
-```
-pncli jwt decode
-```
-
-### Openshift
-
-```
-pncli openshift pods
-  --namespace <ns>             Kubernetes namespace
-  --label-selector <selector>  Label selector (e.g. app=my-app)
-
-pncli openshift events
-  --namespace <ns>             Kubernetes namespace
-  --field-selector <selector>  Additional field selector (e.g.
-  involvedObject.name=my-pod)
-  --all                        Include Normal events in addition to Warning
-  events (default: false)
-
-pncli openshift logs
-  --namespace <ns>    Kubernetes namespace
-  --pod <name>        Pod name
-  --container <name>  Container name (defaults to first container)
-  --lines <n>         Number of most-recent lines to return (default: "100")
-  --previous          Return logs from the previous container instance (default:
-  false)
-
-pncli openshift pod-metrics
-  --namespace <ns>  Kubernetes namespace
-```
-
-### Dynatrace
-
-```
-pncli dynatrace entities list
-  --selector <selector>  Dynatrace entity selector, e.g. type("SERVICE")
-  --from <time>          Start time (ISO 8601 or relative, e.g. now-2h)
-  --to <time>            End time (ISO 8601 or relative)
-  --fields <fields>      Additional entity fields
-
-pncli dynatrace entities get
-  --id <id>          Entity ID, e.g. SERVICE-1234567890ABCDEF
-  --from <time>      Start time
-  --to <time>        End time
-  --fields <fields>  Additional entity fields
-
-pncli dynatrace services
-  --from <time>  Start time
-  --to <time>    End time
-
-pncli dynatrace workloads
-  --from <time>  Start time
-  --to <time>    End time
-
-pncli dynatrace problems list
-  --from <time>                  Start time (default: now-2h)
-  --to <time>                    End time (default: now)
-  --problem-selector <selector>  Dynatrace problem selector
-  --entity-selector <selector>   Affected entity selector
-
-pncli dynatrace problems get
-  --id <id>          Problem ID
-  --fields <fields>  Additional fields
-
-pncli dynatrace trace
-  --id <trace-id>  16- or 32-character hexadecimal trace ID
-```
-
-<!-- COMMAND-REFERENCE:END -->
-
-## Output Format
-
-All commands return:
-- Success: `{ "ok": true, "data": { ... }, "meta": { "service": "...", "action": "...", "timestamp": "...", "duration_ms": N } }`
-- Error: `{ "ok": false, "error": { "status": N, "message": "..." }, "meta": { ... } }`
-
-Always check `ok` before accessing `data`.
-
-## Tips
-
-- Use `--dry-run` to preview API calls without executing
-- Use `--verbose` to see full response metadata for debugging
-- Use `--pretty` when running manually for readable output
-- Use `--output-file <path>` to write JSON output to a file instead of stdout — recommended for commands that produce large payloads (search, logs, `--all` pagination) to avoid flooding agent context
-- Pipe output through `jq` for ad-hoc filtering (if available)
-- Defaults from `.pncli.json` are applied automatically — you rarely need to pass `--project`, `--type`, or `--priority` flags for Jira