scope

func AddScopeFlags ¶

func AddScopeFlags(cmd *cobra.Command, res Resource, section *string)

AddScopeFlags registers --section and the item flags this resource accepts.

Registering only the resource's own categories is what makes `--help` and shell completion honest: a mobile configuration profile no longer offers --computer-group, and restricted software no longer offers a limitations section it has no tab for.

func AddToScope ¶

func AddToScope(s *ScopeXML, section, flagName, name string) bool

AddToScope adds a named item to the given scope section. Returns true if the item was added, false if already present (idempotent no-op).

singularKey is no longer read: the policy-only <limit_to_users> branch this used to carry is gone, the server keeping that element in step with <limitations><user_groups> by itself (see ScopeXML).

func CheckAllFlagConflict ¶ added in v1.30.0

func CheckAllFlagConflict(s *ScopeXML, singularKey, section, flagName string) error

CheckAllFlagConflict refuses a target that the resource's currently-set all-flag makes unreachable. The server accepts such a write with 200 and drops the member, so without this the only signal is the post-write verification failing with a message about the resource type.

func FlattenScope ¶

func FlattenScope(s *ScopeXML) []map[string]any

FlattenScope converts a ScopeXML into a flat list of rows for table output.

Every category the XML model carries is emitted, so what `scope get` shows is exactly what `scope add`/`remove` can address. The two that used to be missing were the ones a caller could see in the admin UI and not here: iBeacon limitations and exclusions, and target classes.

func NewScopeCmd ¶

func NewScopeCmd(ctx *registry.CLIContext, res Resource) *cobra.Command

NewScopeCmd creates the "scope" subcommand group with get, add, and remove subcommands for the given Classic API resource.

Each leaf takes `[<id>]` plus `--name`, matching every other command in this CLI. It used to take the name as a bare positional — the only place in the binary that did — which meant a caller who had an ID in hand from `list` had to go and find the name for it, and a name that looks like an ID could not be addressed at all.

func OutputScope ¶

func OutputScope(out registry.OutputFormatter, s *ScopeXML, format string) error

OutputScope writes the scope to the output formatter. The column formats get the scope flattened into rows; json, yaml, ndjson, xml and raw get the full structure.

The keep-set is named and the flattened shape is the default, rather than the other way round, because the format string is not normalised: this used to match "table", "csv" and "plain" exactly, so any other value — a mis-cased -o Table, or the internal json-multi that means JSON on the wire and a table on the screen — took the nested structure to a table renderer. See output.RendersStructureVerbatim.

func PutScope ¶

func PutScope(ctx context.Context, client registry.HTTPClient, res Resource, id string, s *ScopeXML) error

PutScope writes an updated scope back to the Classic API, sending a body that carries nothing but the <scope> element.

Two properties of the Classic API make this the right shape, both wire-checked 2026-09-12 against Jamf Pro 11.31.1 on a direct instance and through the platform gateway:

• A PUT is a partial update at top-level-section granularity: a body of just <scope> applies the scope and leaves general, self_service, packages, payloads and every other section byte-identical.
• <scope> itself is replaced wholesale. A body carrying only some scope categories wipes the rest, so the whole block has to be sent — which is what the caller's ScopeXML, read from the server and edited in place, already is. An empty category element is what clears a category.

The body is marshalled by encoding/xml rather than spliced into the document the server returned, and the element ORDER that produces is load-bearing. The Classic API's XML binding is sequence-ordered: it reads scope children in schema order and silently ignores what arrives out of order, answering 200 either way. The order a GET returns is not that order — macapplications, for one, answers <exclusions> as buildings, departments, mobile_device_groups, users, ... — so echoing the server's own bytes back is accepted and applied to nothing. ScopeXML's field order is the schema order; keep it that way.

The /subset/Scope shortcut is not used: the Jamf Platform Gateway's Classic proxy forwards only top-level Classic paths, so it answers 403 there while working on a direct instance (re-probed 2026-09-12). One code path that works on both beats two that disagree. CLASS TARGETS NEED TWO WRITES. Jamf Pro's Classic API stores <classes> only while the stored category is EMPTY. A write made while it already holds a member clears it — carrying the identical value or omitting it both clear it, and the child's identifier shape makes no difference (wire-checked 2026-09-12 on Jamf Pro 11.31.1, 5/5 each way). Since a scope PUT replaces <scope> wholesale, no single request can preserve an existing class across any other scope change.

So a scope with class members is delivered in two requests: the first carries every intended change with <classes> emptied, leaving the category empty; the second carries the same scope with the classes populated, which the server now accepts. Verified 5/5 — a department added to an ebook that already had a class ends up with both.

Three properties make that safe rather than clever:

• It is never worse than one request. The first PUT already carries the caller's real change, so an interruption between the two leaves exactly what a single PUT would have left: the change applied, the classes gone.
• It is keyed on the CATEGORY, not the resource. Only ebooks carry <classes> today, but the rule is a property of the element, so a resource that gains one is handled with no edit here.
• A scope with no class members takes the single-request path, so the common case is unchanged and the extra write happens only where it is the difference between working and silently losing data.

func RemoveFromScope ¶

func RemoveFromScope(s *ScopeXML, section, flagName, name string) bool

RemoveFromScope removes a named item from the given scope section. Returns true if removed, false if not found (idempotent no-op).

func ScopeFlagsFor ¶ added in v1.30.0

func ScopeFlagsFor(singularKey string) []string

ScopeFlagsFor returns the flags a resource accepts anywhere, so a command registers only the flags its own resource can use. Sorted for stable help.

func SectionsFor ¶ added in v1.30.0

func SectionsFor(singularKey string) []string

SectionsFor returns the sections a resource actually has, so --section's help and completion do not offer a limitations tab to restricted software.

func ValidateScopeCombination ¶

func ValidateScopeCombination(singularKey, section, flagName string) error

ValidateScopeCombination checks that a section/flag pair is one the resource actually carries, refusing before anything is sent.

The refusal names the flags that would have worked for this resource and section, because the two axes a caller gets wrong are "wrong section for a valid category" (--computer-group as a limitation) and "wrong category for this resource type" (--computer-group on a mobile profile), and a message listing one global vocabulary cannot distinguish them.

func VerifyScopeWrite ¶ added in v1.30.0

func VerifyScopeWrite(ctx context.Context, client registry.HTTPClient, res Resource, id string, sent *ScopeXML, touched ScopeTarget, touchedSection string, expectPresent bool) error

VerifyScopeWrite re-reads a resource's scope after a write and reports every member that was sent and did not come back.

It compares the WHOLE scope rather than only the item the command changed, which the single-item check it replaced could not do — and collateral loss is real, not hypothetical. An ebook's <classes> target can only be set while it is empty: once populated, any later scope write clears it, whether the body carries the identical value or omits it (wire-checked 2026-09-12, 5/5 each way). So `scope add --building` on an ebook that has a class destroys the class, and a check scoped to --building sees a clean write.

Because <scope> is replaced wholesale, that shape of loss can appear on any category the server decides not to store, so the guard is general rather than a rule about ebooks. `touched` is named separately only so the message can lead with the member the caller asked about.