apm policy

Diagnostic surface for the policy enforcement layer. Lets admins and CI pipelines verify what apm-policy.yml was discovered, how fresh the cache is, the resolved extends: chain, and the count of effective rules — without running a full apm install or apm audit.

Synopsis

apm policy status [--policy-source SOURCE] [--no-cache]
                  [-o table|json] [--json] [--check]
apm policy explain PACKAGE

Description

apm policy groups diagnostic subcommands for the organization-level policy APM resolves at install / audit time. The group exposes two subcommands: status (the policy-chain view) and explain (the per-package executable-trust decision).

The command is always exit 0 by default. Discovery failures are reported in the output (table or JSON), never via process exit code, so it stays safe for human inspection and SIEM ingestion. Pass --check to opt into a CI-friendly contract that exits 1 when no usable policy is resolved.

For the apm-policy.yml schema and enforcement model, see Policy reference.

Subcommands

`apm policy status`

Render a diagnostic snapshot of the active APM policy: discovery outcome, source, enforcement level, cache age, resolved extends: chain, and effective rule counts.

apm policy status [OPTIONS]

Flag	Description
`--policy-source SOURCE`	Override discovery. Accepts `org` (auto-discover from the project’s git remote), `owner/repo` (defaults to github.com), an `https://` URL, or a local file path.
`--no-cache`	Force a fresh fetch; skip the policy cache.
`-o`, `--output {table,json}`	Output format. Default: `table`.
`--json`	Emit JSON. Alias of `-o json`.
`--check`	Exit `1` when no usable policy is resolved (any `outcome` other than `found`). Default exit is always `0`.

Output fields

The table and JSON renderers expose the same fields:

Field	Meaning
`outcome`	Discovery result: `found`, `absent`, `disabled`, `no_git_remote`, `cache_miss_fetch_fail`, …
`source`	Resolved source label (e.g. `org:owner/repo`, `url:https://...`, `file:./path`).
`enforcement`	Effective enforcement mode: `block`, `warn`, or `off`.
`cache_age_human`	Age of the cached policy entry, with stale / refresh-failure context.
`cache_stale`, `cached`, `cache_age_seconds`	Raw cache state (JSON only).
`extends_chain`	Resolved `extends:` ancestors of the leaf policy.
`rule_summary`	Human one-liners for non-empty rule axes.
`rule_counts`	Per-axis integer counts. `-1` means “no opinion” (allow-list omitted); `0` means “explicitly empty”. JSON only.
`fetch_error`, `error`	Populated when discovery or refresh failed.

Exit codes

Mode	`outcome=found`	Anything else
default	`0`	`0`
`--check`	`0`	`1`

To gate on rule violations rather than resolvability, use apm audit --ci instead.

`apm policy explain`

Explain the effective executable-trust decision for a single installed package. For each executable type the package declares, it prints whether that primitive is allowed, the deciding precedence layer (a compound label such as org-deny, project-allow, or default-deny), and any lower-authority layers that decision shadowed. This is the per-package companion to apm policy status (the policy-chain view) and the fleet-level executable-trust drift check in apm doctor.

apm policy explain PACKAGE

Argument	Description
`PACKAGE`	Package reference (e.g. `owner/repo`) to resolve. Only packages installed in the current project resolve; an uninstalled reference reports no decision.

The effective decision follows the deny-wins precedence: an organization executables.deny / deny_all is the ceiling no project or user grant can widen. See Executable approval for the trust model and apm-policy.yml schema for the executables ceiling.

Examples

# Show resolved policy state for the current project
apm policy status

# Force a fresh fetch (bypass cache)
apm policy status --no-cache

# Machine-readable JSON for SIEM or CI inspection
apm policy status --json

# Inspect a draft policy without committing it
apm policy status --policy-source ./draft-policy.yml

# Inspect an explicit org policy by repo
apm policy status --policy-source acme-corp/apm-policies

# CI pre-check: fail the job when no usable policy is resolved
apm policy status --check

# Explain the effective executable-trust decision for an installed package
apm policy explain owner/repo

Sample table output:

APM Policy Status
-----------------
  Outcome          found
  Source           org:acme-corp/apm-policies
  Enforcement      block
  Cache age        4m ago
  Extends chain    acme-corp/apm-baseline
  Effective rules  3 dependency denies; 2 mcp denies; 1 required manifest fields

apm install — enforces policy during dependency resolution; honors --no-policy to bypass.
apm audit — gate on rule violations with --ci; complements apm policy status --check.
Policy reference — canonical apm-policy.yml schema and enforcement semantics.
Governance deep-dive — how policy fits the broader enterprise governance model.
APM policy: getting started — author and publish your first apm-policy.yml.
Enforce in CI — wire audit and policy status into pipelines.