Platform API Commands

Platform API Commands

Platform API commands operate on shared Jamf Platform services — blueprints, compliance benchmarks, DDM reports, and unified device management. These services are not specific to Jamf Pro; they are platform-level capabilities that span tenants. As the Jamf Platform evolves, a single set of API credentials will be able to manage resources across Jamf Pro, Jamf Protect, and Jamf School tenants.

Today, Platform API commands are accessed via jamf-cli pro and require platform gateway authentication (auth-method: platform). See Setup Guide#Jamf Pro Quick Start — Platform Gateway (Recommended) for setup instructions.

For shared CLI patterns (apply, scaffold, pagination, dry-run), see CLI Patterns.

Note: The Platform API is currently in beta. See the Platform API documentation for details.

Platform commands are always visible in pro --help, but return a clear error with setup instructions when platform auth is not configured.

Identifiers: positional <id>, names via --name. Unlike Protect and School (which take a positional <name>), Platform commands take the resource ID positionally and resolve names through a --name flag. Passing a name positionally sends it to the API as an ID and 404s; passing both <id> and --name is rejected. The exceptions are blueprints clone <source-name> <new-name>, compliance-benchmarks export <title> / clone <source-title> <new-title>, and platform-device-groups add-members / remove-members <name> (all names positionally), platform-devices get/delete <id|serial> (either, auto-detected), and ddm-reports device <deviceId> (ID only, no --name).

Aliases

Command	Alias
blueprints	bp
compliance-benchmarks	cb
platform-devices	pdev
platform-device-groups	pdg
ddm-reports	ddm

Blueprints (bp)

Manage deployment blueprints — define configurations and deploy them to device groups.

# List all blueprints
jamf-cli pro blueprints list
jamf-cli pro blueprints list --sort name:asc --search "staging"

# Get a blueprint — by UUID, or by name with --name
jamf-cli pro blueprints get 0f0e6b0c-1f2a-4c3d-9e8f-7a6b5c4d3e2f
jamf-cli pro blueprints get --name "macOS Standard"

# Create or update a blueprint
jamf-cli pro blueprints apply --from-file blueprint.json --yes

# Print a JSON scaffold template
jamf-cli pro blueprints apply --scaffold

# Export a blueprint (round-trippable to apply)
jamf-cli pro blueprints export --name "macOS Standard" -o yaml > blueprint.yaml

# Clone a blueprint (the one command that takes names positionally)
jamf-cli pro blueprints clone "macOS Standard" "macOS Standard - Test"

# Deploy / undeploy
jamf-cli pro blueprints deploy --name "macOS Standard"
jamf-cli pro blueprints undeploy --name "macOS Standard"

# Get deployment status report
jamf-cli pro blueprints report --name "macOS Standard"

# Delete a blueprint
jamf-cli pro blueprints delete --name "macOS Standard" --yes

Blueprint Scope Management

# List device groups in a blueprint's scope (positional UUID, or --name)
jamf-cli pro blueprints scope list 0f0e6b0c-1f2a-4c3d-9e8f-7a6b5c4d3e2f
jamf-cli pro blueprints scope list --name "macOS Standard"

# Add device groups to scope (--computer-group / --mobile-device-group by name, or --group-id by UUID; all repeatable)
jamf-cli pro blueprints scope add --name "macOS Standard" --computer-group "All Macs"

# Remove device groups from scope
jamf-cli pro blueprints scope remove --name "macOS Standard" --computer-group "Test Devices"

Blueprint Components

Blueprint components are the DDM declarations that make up a blueprint step. Each component has a unique identifier (e.g. com.jamf.ddm.passcode-settings).

# List all available components
jamf-cli pro blueprints components list

# Get a component's current API definition by identifier
jamf-cli pro blueprints components get "com.jamf.ddm.passcode-settings"

# Print a ready-to-use JSON scaffold for a component (no auth required)
# Accepts full identifiers or short names
jamf-cli pro blueprints components scaffold passcode-settings
jamf-cli pro blueprints components scaffold com.jamf.ddm.software-update-settings

# Convert a .mobileconfig file to a configuration-profile component
jamf-cli pro blueprints components configuration-profile --from-file profile.mobileconfig

# Download an existing profile from Jamf Pro and convert it
jamf-cli pro blueprints components configuration-profile --name "My Restrictions"
jamf-cli pro blueprints components configuration-profile --name "Managed Restrictions" --type mobile

# Strip Apple default values before converting (reduces noise from UI-generated profiles)
jamf-cli pro blueprints components configuration-profile --from-file profile.mobileconfig --strip-defaults

# Convert a raw preference domain plist to a configuration-profile component
jamf-cli pro blueprints components configuration-profile-plist \
  --from-file com.apple.dock.plist --payload-type com.apple.dock

Import Classic Profile as Blueprint

import-profile downloads a Classic API configuration profile from Jamf Pro, automatically converts compatible payloads to native DDM components, and creates a blueprint. This is the fastest path from a legacy mobileconfig to a modern DDM blueprint.

# Import a macOS config profile (DDM conversion happens automatically)
jamf-cli pro blueprints import-profile "Passcode Policy"

# Import a mobile device config profile
jamf-cli pro blueprints import-profile "Managed Restrictions" --type mobile

# Override the blueprint name
jamf-cli pro blueprints import-profile "FileVault Settings" --blueprint-name "FV Blueprint"

# Strip Apple defaults from payloads (useful for profiles with many UI-set keys)
jamf-cli pro blueprints import-profile "My Restrictions" --strip-defaults

# Skip DDM conversion — wrap everything in a single configuration-profile component
jamf-cli pro blueprints import-profile "My Restrictions" --legacy

# Set (or override) the blueprint scope — blueprints require at least one device group (repeatable)
jamf-cli pro blueprints import-profile "Software Update" --computer-group "All Managed Macs"
jamf-cli pro blueprints import-profile "Managed Restrictions" --type mobile --mobile-device-group "Student iPads"

# Send payloads that blueprints hard-disables anyway (the API will reject them)
jamf-cli pro blueprints import-profile "My Restrictions" --include-unsupported

Supported DDM conversions (automatically applied when payloads are detected):

Legacy Payload	DDM Component
com.apple.mobiledevice.passwordpolicy	com.jamf.ddm.passcode-settings
com.apple.applicationaccess (safari keys)	com.jamf.ddm.safari-settings
com.apple.applicationaccess (deferral keys)	com.jamf.ddm.software-update-settings
com.apple.applicationaccess (RSR keys)	com.jamf.ddm.software-update-settings
com.apple.SoftwareUpdate	com.jamf.ddm.software-update-settings

Payloads without a DDM mapping are wrapped in a com.jamf.ddm-configuration-profile component. Some of these "Legacy payload" components can only be managed through the blueprints API — they appear read-only in the Jamf Pro UI. Scope is carried over (target device groups only — individual computers, buildings, departments, limitations, and exclusions are not importable to blueprints).

Since v1.24.0:

• Scope override + empty-scope guard. --computer-group / --mobile-device-group (both repeatable) set the blueprint scope, overriding the profile's own. Because blueprints require at least one device group, a profile whose scope resolves to no groups (all computers, individual devices, buildings, or departments) fails fast with an actionable error instead of a 400 from the API — supply one of these flags to fix it.
• Disabled payload types are skipped, not sent. Blueprints hard-disables a fixed set (certificates, VPN, SSO, web clips, fonts, and others); those are dropped with a warning. --include-unsupported sends them anyway, and the API will reject them.

How payload types are actually delivered — v1.25.2+

The com.jamf.ddm-configuration-profile component does not accept any Apple payload, despite what the API reference says: it matches payloadType against a fixed registry of types it will take standalone. A type outside that registry is rejected with a message that names only the whole component and no payload, key, or reason:

{"httpStatus":400,"errors":[{"code":"VALIDATION_FAILURE",
  "field":"steps[0].components[2].configuration",
  "description":"Failed to validate configuration."}]}

Before v1.25.2 that meant several stock Jamf Pro profiles — a stock Restrictions profile, a stock Login Window profile — failed outright and created nothing. Wire-probing every payload type Apple publishes (plus Jamf's own spellings) found 74 accepted standalone, 22 explicitly disabled, and 40 unknown to the registry, including well-documented ones: com.apple.MCX, com.apple.Safari, com.apple.SoftwareUpdate, com.apple.Terminal, com.apple.TimeMachine, com.apple.systemuiserver, com.apple.mail.managed, .GlobalPreferences. Apple publishing a schema says nothing about what the registry knows.

Since v1.25.2 import-profile (and components configuration-profile) models that reality:

• Out-of-registry types are wrapped, not dropped. A payload whose type the registry doesn't know is delivered as com.apple.ManagedClient.preferences (Application & Custom Settings), which the API accepts for every domain probed — including third-party ones like com.microsoft.Word — and which is the correct legacy delivery for those domains anyway. No settings are lost.
• Jamf's non-canonical spelling is rewritten. Jamf Pro writes its User Preferences payload as com.apple.preferences.users (Apple's filename); the registry only knows com.apple.preference.users. One character used to fail a whole profile.
• MCX unwrapping is narrower and now offline. An Application & Custom Settings payload is unwrapped to a standalone payload only when a DDM converter will consume its inner domain, or the registry accepts that domain. The previous rule — "Apple publishes a schema for it", checked live from GitHub — turned importable profiles into rejected ones for com.apple.Safari and friends. Classification is now deterministic and needs no network call. --legacy still keeps MCX fully intact.

Result: both previously-failing stock profiles import cleanly (Restrictions wraps 4 payloads and rewrites 1 spelling; Login Window wraps 3).

Note: Missing a type from the registry is benign — it gets MCX-wrapped and still delivered. Guessing one in is not, so the CLI's list is deliberately conservative.

Compliance Benchmarks (cb)

Manage mSCP (macOS Security Compliance Project) compliance benchmarks. compliance-benchmarks handles benchmark CRUD (create/apply, get, list, clone, delete, export). Baseline and rule reference data live under baselines/rules; compliance monitoring lives under benchmark-reports.

# List available mSCP baselines (starting point for new benchmarks — see "Compliance Baselines & Rules" below)
jamf-cli pro baselines list

# List all benchmarks
jamf-cli pro compliance-benchmarks list

# Get a benchmark — by ID, or by title with --name
jamf-cli pro compliance-benchmarks get <benchmark-id>
jamf-cli pro compliance-benchmarks get --name "CIS macOS 15"

# Create a benchmark from a portable JSON/YAML file (group names, not IDs)
jamf-cli pro compliance-benchmarks apply --from-file benchmark.json
jamf-cli pro compliance-benchmarks apply --from-file benchmark.yaml

# Print a JSON scaffold template for the input format
jamf-cli pro compliance-benchmarks apply --scaffold

# Generate a scaffold pre-populated with all rules from a specific baseline
# (pass the baseline ID from 'baselines' list)
jamf-cli pro compliance-benchmarks apply --scaffold-from-baseline "<baseline-id>"

# Export a benchmark as portable JSON/YAML (group IDs replaced with names)
# export/clone are the exceptions — they take titles positionally
jamf-cli pro compliance-benchmarks export "CIS macOS 15"
jamf-cli pro compliance-benchmarks export "CIS macOS 15" -o yaml > benchmark.yaml

# Clone a benchmark with a new title
jamf-cli pro compliance-benchmarks clone "CIS macOS 15" "CIS macOS 15 - Staging"

# Clone and override target device groups
jamf-cli pro compliance-benchmarks clone "CIS macOS 15" "CIS macOS 15 - Test" \
  --computer-group "Test Devices"

# Delete a benchmark (positional ID, or --name for the title)
jamf-cli pro compliance-benchmarks delete --name "CIS macOS 15" --yes

Note: Benchmarks cannot be updated after creation — apply is create-only. To modify a benchmark, export it, delete the old one, edit the exported file, and re-apply. Use clone to copy an existing benchmark with a new title. export produces a portable format where device group IDs are replaced with names, making the output safe to apply to a different instance.

Targeting OS versions (v1.23.0+)

A benchmark definition can pin the OS versions it applies to via a selectedOsVersions list. Each entry has an osType and osVersion. This appears in apply --scaffold output and is preserved by export/clone:

{
  "title": "My Benchmark",
  "sourceBaselineId": "<baseline-id>",
  "rules": [ { "enabled": true, "id": "<rule-id>" } ],
  "selectedOsVersions": [
    { "osType": "MAC_OS", "osVersion": 26 }
  ],
  "target": {
    "deviceGroups": [
      { "name": "<device-group-name>", "deviceType": "COMPUTER", "groupType": "SMART" }
    ]
  },
  "enforcementMode": "MONITOR"
}

Compliance Baselines & Rules (baselines, rules)

The mSCP baselines and their rules are read-only reference data, exposed as their own resources (not subcommands of compliance-benchmarks). Use a baseline ID when scaffolding a benchmark with compliance-benchmarks apply --scaffold-from-baseline.

# List available mSCP baselines
jamf-cli pro baselines list

# List all mSCP rules
jamf-cli pro rules list

# List the rules provided by a specific baseline
jamf-cli pro rules list --baseline-id <baseline-id>

Benchmark Reports (benchmark-reports)

Compliance reporting for existing benchmarks. Each subcommand takes a benchmark ID (from compliance-benchmarks list) as a positional argument, or — since v1.24.0 — a benchmark title via --name (resolved against compliance-benchmarks), so you no longer have to look the ID up first.

# Per-rule compliance stats for a benchmark (passed / failed / unknown counts)
jamf-cli pro benchmark-reports rules <benchmark-id>
jamf-cli pro benchmark-reports rules --name "CIS macOS 15"
jamf-cli pro benchmark-reports rules <benchmark-id> --rule-search "firewall" --sort passed:desc

# Devices for a benchmark, optionally filtered to a single rule
jamf-cli pro benchmark-reports devices <benchmark-id>
jamf-cli pro benchmark-reports devices --name "CIS macOS 15" --rule-id <rule-id> --sort deviceName:asc

# Overall compliance percentage for a benchmark
jamf-cli pro benchmark-reports compliance-percentage <benchmark-id>
jamf-cli pro benchmark-reports compliance-percentage --name "CIS macOS 15"

Platform Devices (pdev)

Unified device inventory and management via the Platform API. Devices are identified by UUID or serial number — serial numbers are auto-detected (UUIDs contain hyphens, serials don't).

# List all devices
jamf-cli pro platform-devices list
jamf-cli pro platform-devices list --sort name:asc --filter "osType==MACOS"

# Get a device by serial number or UUID
jamf-cli pro platform-devices get C02X1234
jamf-cli pro platform-devices get "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Update device attributes
jamf-cli pro platform-devices update C02X1234 --from-file device-update.json

# Delete a device (destructive)
jamf-cli pro platform-devices delete C02X1234 --yes

# List installed applications
jamf-cli pro platform-devices applications C02X1234

# List group memberships
jamf-cli pro platform-devices groups C02X1234

# List devices for a user
jamf-cli pro platform-devices user user-id-here

# Request a device check-in (non-destructive)
jamf-cli pro platform-devices check-in C02X1234

# Device actions (destructive — require --yes)
jamf-cli pro platform-devices erase C02X1234 --yes
jamf-cli pro platform-devices restart C02X1234 --yes
jamf-cli pro platform-devices shutdown C02X1234 --yes
jamf-cli pro platform-devices unmanage C02X1234 --yes

Platform Device Groups (pdg)

Manage device groups via the Platform API. Static groups support member management; smart groups are defined by filter criteria.

# List all device groups
jamf-cli pro platform-device-groups list
jamf-cli pro platform-device-groups list --sort name:asc

# Get a device group — by ID, or by name with --name
jamf-cli pro platform-device-groups get <group-id>
jamf-cli pro platform-device-groups get --name "All macOS Devices"

# Create or update a device group
jamf-cli pro platform-device-groups apply --from-file group.json --yes

# Print a JSON scaffold template
jamf-cli pro platform-device-groups apply --scaffold

# Export a group as YAML (round-trippable to apply)
jamf-cli pro platform-device-groups get --name "All macOS Devices" -o yaml

# Delete a device group
jamf-cli pro platform-device-groups delete --name "Test Group" --yes

# List group members (positional <id>, or --name)
jamf-cli pro platform-device-groups members --name "All macOS Devices"

# Add/remove members from a static group — these two take the group NAME
# positionally; --id is the repeatable device ID
jamf-cli pro platform-device-groups add-members "Manual Group" --id <device-id-1> --id <device-id-2>
jamf-cli pro platform-device-groups remove-members "Manual Group" --id <device-id-1>

# Disambiguate by device type when a computer group and a mobile device group share a name (v1.18.0+)
jamf-cli pro platform-device-groups get --name "Engineering" --device-type COMPUTER
jamf-cli pro platform-device-groups get --name "Engineering" --device-type MOBILE

--device-type (v1.18.0+): A computer group and a mobile device group can have the same name, which makes a bare name lookup ambiguous. Pass --device-type COMPUTER or --device-type MOBILE to narrow it. The flag is available on the subcommands that resolve a group by name: get, delete, members, add-members, remove-members, patch, and patch-members.

Identifier shapes differ within this group: get, delete, members, patch, and patch-members take a positional <id> with --name for lookup; add-members and remove-members take the group <name> positionally.

DDM Reports (ddm)

Declarative Device Management reporting — check declaration deployment status across your fleet.

# Get the declaration report for a specific device (by device ID) — --filter is required
jamf-cli pro ddm-reports device declarations <device-id> --filter 'active==true'

# List devices reporting a specific declaration — --filter is required
jamf-cli pro ddm-reports declaration devices "com.apple.configuration.passcode" --filter 'active==true' --sort declarationType,asc

# List devices with failed/invalid declarations and error reasons
jamf-cli pro ddm-reports errors "com.apple.configuration.passcode"

--filter is required on device declarations and declaration devices — the API has no "return everything" mode for these reports, so running them without --filter fails with required flag(s) "filter" not set. Filters use RSQL and apply only to declarations already on the device (PENDING declarations are excluded). Allowed fields:

• device declarations: declarationIdentifier, active, validityState, declarationType, dateUpdated, channel
• declaration devices: deviceId, channel, lastReportTime, active, validityState, declarationType, dateUpdated

For example, --filter 'validityState=="INVALID"' returns only the failing declarations. The errors subcommand takes no --filter — it already scopes to failed/invalid declarations.

Platform Reports

Report commands that aggregate Platform API data. These nest under pro report alongside existing Pro reports.

# Blueprint deployment status across all blueprints
jamf-cli pro report blueprint-status

# Per-rule compliance stats for a benchmark
jamf-cli pro report compliance-rules "CIS macOS 15"

# Non-compliant devices for a benchmark
jamf-cli pro report compliance-devices "CIS macOS 15"

# DDM declaration health across all devices
jamf-cli pro report ddm-status

Auth Token

Print a valid Jamf Platform Gateway access token. The token is automatically refreshed if expired.

# Print token as JSON (includes expiry)
jamf-cli platform auth token

# Extract just the token string for scripting
jamf-cli platform auth token --field token

# Force a fresh token exchange (ignores cache)
jamf-cli platform auth token --refresh

Output:

{
  "token": "eyJhbGciOi...",
  "expires_at": "2026-04-15T15:30:00Z"
}

Flag	Description
--refresh	Force a new token exchange, ignoring any cached token

Platform Audit Checks

When platform gateway auth is active, pro audit automatically includes platform-specific checks:

# Run all audit checks (includes platform when configured)
jamf-cli pro audit

# Run only platform checks
jamf-cli pro audit --checks platform

Platform checks include: undeployed blueprints, deployment failures, stale blueprints, benchmark updates needed, monitor-only benchmarks, empty platform scope, and failed DDM declarations.