Add consistent machine-readable output format support across CLI commands

[ScottGuymer]

It would be very useful if all apm CLI commands that produce structured information supported a consistent --format flag, including JSON output.

Some commands already support this. For example, apm audit --format json can output machine-readable JSON, which makes it possible to build automation on top of the command without parsing human-readable text output.

Background

I am currently looking at building GitHub Actions automation around APM usage.

One use case is detecting package drift and reporting on it. This works well with apm audit because the JSON output can be parsed reliably.

Another use case is building an update workflow similar in spirit to Dependabot, where automation can detect outdated APM packages and propose pull requests to update them.

This is currently difficult because commands such as apm outdated and apm update do not appear to provide machine-readable output. That means automation would need to parse the human-readable CLI output, which is brittle and likely to break if the formatting changes.

Requested feature

Add a consistent --format option to CLI commands that output structured data.

For example:

apm outdated --format json
apm update --format json
apm list --format json

Potential supported formats could be:

--format text
--format json

Where text remains the default for human CLI usage, and json provides a stable output contract for automation.

Example usage

A GitHub Action could run:

apm outdated --format json

And receive structured information such as:

{
  "packages": [
    {
      "name": "example-package",
      "currentVersion": "1.2.0",
      "latestVersion": "1.4.0",
      "updateAvailable": true
    }
  ]
}

This would allow automation to:

• detect which packages are outdated
• understand the current and target versions
• generate reports
• open pull requests for updates
• avoid relying on fragile text parsing

Why this matters

Machine-readable CLI output makes APM much easier to use in CI/CD, governance, reporting, and automated maintenance workflows.

The existing JSON support in apm audit is a good example of the value this provides. Extending the same pattern consistently across the CLI would make it much easier to build reliable automation around APM.

[github-actions]

Triage decision

defer-later

Proposed labels

area/cli
type/feature
status/accepted

Milestone

null

Suggested next action

Define the common --format output contract for structured-data commands (which commands are in scope, JSON schema per command, how to handle partial failures in machine-readable mode), using apm audit --format json as the reference pattern and a shared formatter layer to avoid per-command duplication.

Suggested issue comment

Thanks for the well-articulated request, ScottGuymer -- the Dependabot-style automation use case is concrete and compelling.

The use case is real: automation that builds on `apm outdated`, `apm deps list`, and `apm update` currently has to parse human-readable output, which is brittle. `apm audit --format json` already proves the pattern works; extending it consistently is the right direction.

APM accepts this as a confirmed backlog item. The design work needed before code lands:

1. Which commands are in scope (at minimum: `apm outdated`, `apm deps list`, `apm list`; possibly `apm update`)?
2. What does the JSON schema look like per command (field names, types, pagination)?
3. How should partial failures surface in machine-readable mode (exit code + structured error field)?

The `apm audit --format json` implementation is the reference. The recommended approach is a shared `FormattedOutput` protocol or base class so each command implements one interface rather than ad-hoc `--format` handling per command.

There is no open milestone to attach this to right now, so it sits as a confirmed backlog item. If you want to move it forward, the best entry point is a design comment on this issue proposing the command list and JSON schema for one command (e.g., `apm outdated`) -- that gives a concrete starting point for a PR.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Machine-readable output is a core composability requirement (review lens point 3). The apm audit --format json precedent is correct and the user is asking for it to be applied consistently. The feature gap is real: apm outdated and apm deps list in particular are high-value automation targets. The --format text|json interface is already familiar from the audit command, so discoverability is good once the flag is added consistently.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. Structured output does not change what APM does; it changes the output encoding only. JSON output of apm outdated does not expose credentials or internal paths. No theme/security or theme/governance required.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author is a first-time contributor (author_association: NONE) with a concrete automation use case (GitHub Actions Dependabot-style workflow). This is a high-value contributor archetype -- someone who wants to build automation on top of APM. The reply should validate the use case, describe the design work needed before code lands, and give them a clear on-ramp (design comment proposing JSON schema for one command). Nurture this contributor.

Python Architect -- Architecture Reviewer

Activated -- this feature touches multiple command modules and needs a consistent design. The risk of ad-hoc --format handling per command is per-command inconsistency and code duplication. The recommended approach: define a FormattedOutput protocol or thin base class that each structured-output command implements, analogous to how CommandLogger provides a shared lifecycle. This makes the pattern scalable as more commands are added. The apm audit --format json implementation is the reference; extract its output contract into the shared layer rather than copying it.

Doc Writer -- Documentation Reviewer

Activated -- the CLI reference needs to document the --format flag for each in-scope command once implemented. The implementing PR must include docs updates for every command that gains the flag. The suggested comment wording avoids describing unimplemented behavior as if it exists.

APM CEO -- Triage Arbiter

Consistent machine-readable output makes APM composable with GitHub Actions, CI pipelines, and automation tools -- reinforcing the "package manager for AI-native development" frame. The apm audit --format json precedent means the design is already established; the work is applying it consistently. Accept as defer-later: clear direction, needs a milestone and engineering capacity, Python Architect correctly flags the need for a shared formatter layer to avoid per-command duplication. No breaking change risk.

{
  "decision": "defer-later",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/cli"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Define the common --format output contract for structured-data commands (scope, JSON schema per command, partial-failure handling), using apm audit --format json as the reference pattern and a shared formatter layer.",
  "comment_markdown": "The use case is real and APM accepts this as a confirmed backlog item. The apm audit --format json pattern is the reference. Design work needed before code lands: which commands are in scope, JSON schema per command, and how partial failures surface in machine-readable mode."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · 167.5 AIC · ⌖ 15.8 AIC · ⊞ 9.2K · ◷