managing-pops-recipe

Pops Engineering Operations

Quick Reference

Check → Search → Validate → Report → Visualize

pops doctor
pops catalog search "pattern"
pops pbc check
pops pbc aggregate --format json

pops visualize architecture
pops visualize pbc pbc-name > diagram.mmd

pops catalog list
pops catalog refresh
pops upgrade --check

When to Use

PBC compliance | catalog operations | architecture diagrams | component manifests | ACS schemas | templates | teams | environment checks

Complete Reference

All commands, parameters, options: command-reference.md

Quick lookup:

catalog → 14 subcommands (list|refresh|search|show|capabilities|features|pbcs|teams|people|stamps|checks|get-pbc|get-team|get-check)
pbc → 8 subcommands (check|aggregate|report|init|validate|list|migrate|show)
component → 4 subcommands (show|features|capabilities|links)
visualize → 5 subcommands (architecture|pbc|teams|capabilities|features)
acs → schema (get|create|update)
template → 3 subcommands (list|show|apply)
teams → 2 subcommands (list|show)
profile → 7 subcommands (list|show|detect|switch|create|update|delete)

Core Operations

Environment Check

pops doctor

Validates: tools | config | credentials | connectivity | domains loaded

Catalog

Common:

pops catalog list
pops catalog refresh
pops catalog search "keyword"
pops catalog show pbcs-catalog

Advanced:

pops catalog capabilities --pbc X --team X --show-consumed -o json
pops catalog features --pbc X --team X --status Planned -o yaml
pops catalog get-pbc pbc-name -o panel
pops catalog get-team team-name --source tree -o json
pops catalog pbcs --team X --status active --enrich -n 10

list → status | refresh → sync | search → query | show → details | get-* → entity info

PBC

Compliance:

pops pbc check
pops pbc check service-name --detailed
pops pbc check --checks delivery.standard_cicd,security.hardened_base_image
pops pbc aggregate --team X --status non-compliant -d
pops pbc report --format csv > report.csv

Manifest:

pops pbc init
pops pbc validate manifest.yaml
pops pbc migrate manifest.yaml
pops pbc show pbc-name -o json

check → validate compliance | aggregate → cross-service | report → summary | init → create | validate → schema | migrate → v1 format

Component

pops component show
pops component show component-name --refresh -o json
pops component features
pops component capabilities
pops component links

show → details | features → list features | capabilities → list caps | links → dashboards/docs

Visualize

Architecture:

pops visualize architecture
pops visualize architecture --team CPL --output arch.mmd
pops visualize architecture --format dot > arch.dot

PBC/Team:

pops visualize pbc pbc-name > pbc.mmd
pops visualize teams --output teams.mmd

Dependencies:

pops visualize capabilities --pbc X --team X
pops visualize features --pbc X --team X

Command	Output	Format
architecture	Full architecture (teams/PBCs/components)	mermaid|dot
pbc	PBC detail diagram	mermaid|dot
teams	Team hierarchy	mermaid|dot
capabilities	Capability dependencies (provided/consumed)	mermaid|dot
features	Feature dependencies (cross-PBC)	mermaid|dot

ACS

pops acs schema get namespace-name
pops acs schema create namespace-name --file schema.yaml
pops acs schema update namespace-name --file schema.yaml

get → retrieve | create → new | update → modify

Requires: ACS_API_TOKEN environment variable or config

Template

pops template list
pops template show template-id
pops template apply template-id -d destination/ -D KEY=VALUE

list → available | show → details | apply → generate with context

Teams

pops teams list
pops teams show team-name

list → all teams | show → members + hierarchy

Profile

pops profile list
pops profile show [profile-name]
pops profile detect
pops profile switch profile-name
pops profile create
pops profile update profile-name
pops profile delete profile-name

detect → system identity | switch → change context | create/update/delete → manage

Upgrade

pops upgrade
pops upgrade --check
pops upgrade --from-source
pops upgrade --source-path /path/to/pops

Option	Action
(none)	Upgrade via uv tool
--check	Check for updates only
--from-source	Upgrade from Git repo
--source-path	Upgrade from local source

SSH upgrade:

uv tool uninstall pops-cli
uv tool install git+ssh://git@github.com/andercore/pops.git

Domains

pops domains

Lists available engineering domains with descriptions

Global Options

pops --version
pops -c config.yaml COMMAND
pops -f json COMMAND
pops -f table COMMAND
pops -f yaml COMMAND
pops -f csv COMMAND
pops -q COMMAND
pops -v COMMAND
pops -vv COMMAND
pops -vvv COMMAND
pops --context "pbc=X,team=Y" COMMAND

Option	Purpose
--config	Custom config file
--format	Output format (json|table|yaml|csv)
--quiet	Suppress non-essential output
--verbose	Verbosity (-v, -vv, -vvv)
--context	Override working context

Context Format

--context "pbc=value,team=value"
--context "value:value"                      # Legacy

Common Workflows

PBC compliance:

pops pbc check
[ $? -eq 0 ] && echo "Compliant" || pops pbc report

Architecture diagram:

pops visualize pbc pbc-communications-platform > cpl-arch.mmd

Catalog search:

pops catalog search "feature-name"
pops catalog capabilities --show-consumed --team CPL

Environment validation:

pops doctor
pops --version

Error Handling

doctor fails → missing tool | invalid config | credential issue
pbc check fails → compliance violations | missing manifest
catalog refresh fails → network issue | invalid catalog URL (use SSH: git@github.com:)
profile switch fails → profile not found | invalid profile
upgrade fails → network issue | permission | version conflict
acs schema fails → missing ACS_API_TOKEN | network | invalid schema
visualize fails → missing catalog data | invalid PBC/team name

Configuration

File: ~/.pops/config.yaml

acs:
  api_token: "token-here"
cache_dir: ~/.pops/cache
current_profile: profile-name
default_output_format: table
enable_auto_update: true
enable_telemetry: false

Environment: ACS_API_TOKEN for ACS operations

SSH Configuration (Required)

Pops uses SSH for private Andercore repos. Git URL rewrite configured:

git config --global url.git@github.com:.insteadOf https://github.com/

Catalog URLs use git@github.com:andercore/* format.

Validation Workflow (Execute After Operations)

Phase	Action
1. Execute	Perform pops operation
2. Validate	Review command output for expected results
3. Report	✓ Pass → Done | ✗ Fail → List violations with evidence
4. Fix	Violations found → Correct → Re-run operation
5. Store Metrics	After ALL validation passes, call mcp__agent-orchestrator__store-skill-metrics

Operation	Verification
doctor	Exit code 0, no error messages, all domains loaded
pbc check	Exit code 0 = compliant | non-zero = violations listed
pbc aggregate	Statistics shown, compliance % calculated
catalog refresh	Success message, no git errors
catalog search	Results returned matching query
pbc validate	Schema validation passed
visualize	Diagram generated (mermaid or dot format)
acs schema	Schema retrieved/created/updated
template apply	Template files generated

VALIDATION REPORT:
✓ Command executed: pops pbc check
✓ Exit code: 0 (compliant)
✓ Output format: json (as requested)
✓ Context applied: pbc=service-name,team=platform
✓ Detailed report: shown

ALL CHECKS PASS ✓

VALIDATION REPORT:
✗ FAIL: pbc check returned non-zero exit code
✗ Evidence: Exit code 1, violations listed
✗ Result: 16/16 components failed observability.audit_logs

VIOLATIONS (1):
1. Compliance check failed
   Evidence: No Activity SDK dependency found
   Fix: Add Activity SDK to all components

ACTION: Fix violations and re-validate