Docs

Getting Started

Workflows, conventions, and tips for using pncli with AI agents and in the terminal.

> One command does what three meetings couldn’t.

What is pncli?

pncli is a CLI tool that provides structured JSON access to Jira, Bitbucket, Confluence, SonarQube, SDElements, and local git state. 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 ships with Claude Code skills — step-by-step workflow guides that agents can follow. To install them into your repo:

pncli skills install

This downloads the latest pncli skills from GitHub. Default installs to .agents/skills/ (GitHub Copilot). For Claude Code, add --agent claude-code. For user-scope, add --scope user. Only pncli-managed skills are replaced — any custom skills you’ve added are left untouched.

To see what’s installed locally:

pncli skills list
First-time setup
1
pncli config init

Set up global auth (Jira, Bitbucket, Confluence, …)

2
pncli config init --repo

Add repo-level defaults — commit this to git

3
pncli config check

Verify all connections are working

Skills

Each workflow is packaged as a Claude Code skill. Run pncli skills install to download them into your repo (default: .agents/skills/ for Copilot; add --agent claude-code for Claude Code). Skills marked /invoke can be called directly by name once installed.

Browse all skills at /skills.

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