Frodo CLI 4.9.0

Added

• Added a frodo settings command for managing local frodo CLI preferences (distinct from frodo config/config-manager, which manage remote Ping/AIC configuration), with theme as its first category:

• Introduced a frodo settings command for managing local frodo CLI preferences, with theme as its first category. This includes commands for listing, showing, setting, and detecting themes, as well as an interactive picker for theme selection. Twelve bundled themes are available, each computed for optimal contrast based on terminal background color. Themes are stored as discoverable JSON files, allowing for user customization. The active preferences persist in ~/.frodo/Theme.json (#901c5ac5).

  • frodo settings theme show -- the active theme, a per-intent color swatch table, and a realistic sample of frodo-cli output (an object table, a schema-property table, a status table, and every message type) rendered in it, the practical way to judge whether a theme actually works on a given terminal background.

• Added a negative intent for styling bad/inactive/disabled status values, distinct from error, and applied it across multiple call sites (#baed6ac3).

  • frodo settings theme background <name> / frodo settings theme contrast <tier> -- the theme model is two independent preferences, not one flat name: background (dark/light/blue/yellow) and contrast (high-contrast/regular/vibrant, default vibrant), combined into a theme name (<background> for high-contrast, <background>-<contrast> otherwise). set <name> still works, parsing a recognized combined name into both preferences.
  • frodo settings theme detect -- best-effort terminal-background auto-detection (OSC 11), setting only the background preference; contrast is never touched by detection. Runs automatically once, only the first time no background has ever been chosen; detect re-runs it on demand (e.g. after switching terminals), and frodo settings theme autodetect on|off disables it entirely.
  • frodo settings and frodo settings theme (called with no subcommand) launch an interactive picker -- a two-step background-then-contrast flow for theme, including an "Auto-detect from my terminal" entry -- built on a custom Escape-aware prompt (the packaged @inquirer/select has no Escape keybinding at all) so Escape backs out a level (contrast step back to background step) instead of requiring Ctrl+C; settings itself skips its own category menu when there's only one category (still just Theme) rather than showing a single-item menu with nowhere further to back out to.

  Twelve bundled themes ship (3 contrast tiers x 4 backgrounds), each computed against its actual background RGB via frodo-lib's TerminalContrastFilter rather than eyeballed -- including blue and yellow, whose reference colors are real macOS Terminal profiles ("Ocean", "Man Page"). Theme files are discoverable files in ~/.frodo/themes/ (JSON, one file per theme), not a single opaque settings blob -- dark/light's high-contrast tier is always guaranteed-readable (resolved from code, never from disk); every other tier is genuinely file-driven, written there as an illustrative, forkable reference copy a user can copy under a new name and edit into a real custom theme. The active preferences persist in ~/.frodo/Theme.json, with FRODO_COLOR_THEME still taking precedence for the underlying dark/light mode, same as before.

• Added a negative intent (ColorTheme.ts) for bad/inactive/disabled status values, distinct from error -- a disabled: true field in a describe table isn't a failure, so it shouldn't have to borrow that intent's color to get styled. Applied across ~48 call sites in 14 ops/ files that had been using muted (too quiet to read as a real status) for the same values.

• Adopted frodo-lib's new semantic color-intent theme (error/warning/command/emphasis), replacing frodo-cli's own previous non-semantic fix (a flat *Bright-to-plain remap in ColorTheme.ts) for the same underlying problem: tinyrainbow's bright ANSI colors are unreadable on light-background terminals. Added frodo-cli-specific intents on top (heading, positive, muted, debug), each color chosen via frodo-lib's new objective TerminalContrastFilter (a WCAG contrast-ratio check) rather than by eye, and migrated all ~500 of frodo-cli's own call sites from raw hue names (c.cyanBright(...)) to the matching semantic name (c.command(...), c.heading(...), etc.) so no code outside ColorTheme.ts references a literal color anymore. Also caught and fixed two latent bugs the stricter typing surfaced: printMessage(msg, 'success') and printMessage(msg, 'warning') (a typo for 'warn') were both silently falling through to plain, uncolored text, since neither matched any of printMessage's actual case values.

  • Added a real MessageType union type for printMessage's type parameter (previously an unenforced string), plus canonical infoMessage/warnMessage/errorMessage/successMessage wrapper functions mirroring the existing verboseMessage/debugMessage pattern. printMessage/printError keep their existing names and signatures otherwise -- printError remains distinct, since it understands and formats an actual Error/FrodoError object, unlike errorMessage's arbitrary error-styled string.

• Added new commands to manage IDM tenant-configuration features (Cloud only) (ca2f90a):

• Adopted frodo-lib's new semantic color-intent theme, replacing previous color mappings. Added frodo-cli-specific intents and migrated call sites to use semantic names, improving readability on light-background terminals (#32ea91b3).

• Added frodo script type describe to print the bindings exposed to scripts running in a given AM scripting context (ca2f90a).

• Restructured frodo idm schema to promote property to a sibling of object and added a new frodo idm schema relationship command tree for managing relationship schemas (8776bd5).

• Added new commands for managing IDM schema objects, properties, and relationships, including create, update, delete, export, import, and list operations. These commands now support flags for detailed configuration, replacing previous JSON payload methods (4939304).

  install is confirmation-gated with an explicit irreversibility warning and is a no-op if the feature is already installed.

• Added frodo script type describe to print the bindings (available objects/APIs) exposed to scripts running in a given AM scripting context (ca2f90a).

• Restructured frodo idm schema: promoted property to a sibling of object (frodo idm schema property ... instead of frodo idm schema object property ...).

• Added a new frodo idm schema relationship command tree (any deployment that runs IDM -- Cloud and ForgeOps), backed by IDM's dedicated v2 relationship-schema API:

• Added --sub-property <path> for managing nested properties of a type: object property, allowing for detailed schema manipulation (4939304).

• Added -l, --long to list commands for detailed output, matching the CLI's convention (4939304).

• Enhanced frodo idm schema object describe with -r, --recursive for expanded nested property details and improved table formatting (4939304).

• Added frodo script type list to discover script types, supporting -l, --long for detailed output (4939304).

  Includes bidirectional (two-managed-object-type) relationship support -- create --reverse-property auto-creates the reverse side in the same write; update/delete --with-reverse infer the reverse side's identity from the property's own existing definition.

• Added new commands filling gaps left when the object/relationship trees were first built (property already had both):

• Added --description <text> to frodo idm schema object create/update for setting type descriptions (4939304).

• Shortened and standardized help text across frodo idm schema and frodo feature command families for consistency and clarity (4939304).

• Revised usage examples for frodo idm schema commands, adding more detailed scenarios and flag combinations (4939304).

  relationship's dedicated v2 API has no bulk-list endpoint, so relationship list falls back to a whole-type schema read filtered to relationship-typed properties.

• frodo idm schema object create/update are now flags-only (-o/--title/--icon), matching relationship's design, instead of taking a -f/--file JSON payload -- export/import remain the file-based round-trip path. create seeds a minimal type (just the _id property, a populated order array, and a default icon if --icon isn't passed) since custom properties are added afterward via property create/relationship create, which already keep order/required in sync.

• frodo idm schema property create/update now take flags (--property-type, --array, --title, --description, --required, --searchable, --user-editable, --not-viewable, --return-by-default) instead of a -f/--file JSON payload, matching object/relationship's design; --property-type supports every type the Admin UI's picker offers (string/number/boolean/date/time/datetime/duration/object).

• Added new commands as the file-based round-trip path the property create/update flags above displace:

• Changed frodo idm schema object export/import flag from -i, --individual-object to -o, --managed-object for consistency (4939304).

• Updated frodo idm schema object create/update to use mat-icon instead of icon for setting icons, aligning with the Ping Identity Platform's Admin UI requirements (4939304).

  import is also the only way to give a new object property its own nested sub-properties in one write, since the flags only build a flat definition.

• Added new commands giving relationship the same file-based round-trip commands object/property already have:

• Refactored schema property and relationship handling to use frodo-lib functions, improving maintainability without changing behavior (4939304).

• Updated usage examples to use short connection-profile aliases for clarity in repeated examples (4939304).

• Added --sub-property <path> for managing nested properties of a type: object property, a dot-path relative to -p/--property (e.g. --sub-property geo with -p address targets address.geo):

• Promoted MCP Server documentation to its own top-level section in the README for better visibility (4939304).

• Corrected exit code handling across CLI commands to ensure non-zero exit codes on errors (28ccff3).

• Fixed heading color for dark themes to ensure visibility against terminal backgrounds (4ffe982).

• Restored color expressiveness lost in the semantic migration, ensuring consistent and readable output (b41817d).

• Resolved issues with terminal-background auto-detection to improve theme matching accuracy (baed6ac).

  Every path segment but the last must already exist and be type: object; list alone takes an optional -p (with --sub-property relative to it) since it has no other property target.

• Added -l, --long, matching the rest of the CLI's list-command convention: names only, one per line, by default; -l prints the full table instead, using the same columns/abbreviations as the corresponding describe command:

• Fixed frodo idm schema relationship to support ForgeOps deployments, correcting previous assumptions about API availability (52ee6c2).

• Ensured frodo idm schema relationship create/update/delete waits for full propagation of writes to avoid race conditions (52ee6c2).

• Improved frodo idm schema object describe output formatting, including cardinality and target details for relationships (4939304).

  property list -l/relationship list -l reuse property describe/object describe's row-building, including cardinality and the extra reverse-lookup reads for relationship list -l. --json is unaffected by -l on all three.

• frodo idm schema object list -l now also shows Icon, Properties, and Relationships columns -- all counted from the same single bulk managed config-entity read list already does, so no extra API calls. Properties and Relationships are each shown as total/required (e.g. 4/1) rather than a separate Required column, since a required entry can be either a property or a relationship; the numerator is right-padded to the widest one in its column so the / lines up down the column. That bulk read doesn't include IDM's auto-injected _meta/_notifications relationship properties (those only appear via the dedicated per-type schema read object describe/relationship list use), so a type's Properties/Relationships counts here can run up to 2 low relative to those commands -- accepted in exchange for staying on one read instead of one per type.

• Added -r, --recursive to frodo idm schema object describe. It now prints Title (name) (or just name with no title), the icon on its own line if configured, a Properties table, and (only if the type has any) a separate Relationships table -- previously just a property/relationship-property count. Flat by default, -r expands nested type: object properties inline using dot-path row names (e.g. address.street) that are valid --sub-property values. Both tables abbreviate their flag columns (REQ/SRH/UED/VIW), with a key line printed underneath (a blank line separating it from the table); Properties omits the Target column, which only Relationships needs, placed right after Title. --json is unaffected by -r -- always the complete definition. property describe leads the same way (Title (name), or just the dot-path if untitled), then -- always, no flag needed -- a Properties table of a type: object property's own children (full nested tree, dot-path rows), then, for a virtual property, a Scripts section with each onRetrieve/onStore script's source printed verbatim instead of mangled into the generic field table one line per row. The Title (name)/Properties/Relationships/Scripts headings are bold (the table column headers keep their existing color-coding, unchanged). frodo idm schema relationship describe's non-recursive output now leads the same way (Title (name.path), bold, title no longer duplicated in the field table below it; the reverse side, with --with-reverse, is suffixed (reverse)).

• Added new flags to frodo idm schema property create/update for default values, enumerated properties, and virtual properties:

• Removed integer from frodo idm schema property create/update --property-type choices, aligning with supported types (4939304).

  • --enum <csv>
  • --enum-titles <csv>
  • --on-retrieve-script <file>
  • --on-store-script <file>
  • --derive-from-relationship <name>
  • --derive-fields <csv>
  • --flatten

  A script-derived property computes its value from a local JavaScript file's contents on read/write, while an RDVP (relationship-derived virtual property) computes it by querying through a relationship instead, with no script at all. Both live entirely inside schema.properties, the same place create/update already read and write -- confirmed against two live examples on alpha_user (custom_availableFactors, script-derived; memberOfOrgIDs, a pure RDVP) -- so no new API surface was needed.

• Added frodo script type list, so frodo script type describe -c <context>'s required context id has a discoverable source -- name only by default, one per line; -l, --long adds Languages/Hidden columns. Reuses the same readScriptTypes() read describe was already adjacent to; a context's own _id (e.g. SCRIPTED_DECISION_NODE) is exactly the value -c/--context expects.

• Added --description <text> to frodo idm schema object create/update, targeting the type's own schema.description (confirmed real via a live type that has one set) -- not in frodo-lib's ManagedObjectSchema type any more than mat-icon is, same reason.

• frodo idm schema property create/update now reject a --derive-from-relationship value that doesn't name an existing relationship property on the type, and reject --enum-titles when its entry count doesn't match --enum's -- both now enforced in frodo-lib (see its own changelog), not just by --property-type's CLI .choices().

Changed

• Shortened the frodo idm schema object/property/relationship and frodo feature command families' help text to match the rest of the CLI's one-line style, following a tracker-wide help-text review.
• Expanded the frodo idm schema object/property/relationship command families' usage examples, especially the commands with the most flag combinations (relationship create/update, property create/update, object export/import) -- object export/import previously had none at all. Added --sub-property, -r/--recursive, --many/--reverse-property-name-only, and multi-flag combo examples where the flag interactions weren't otherwise obvious from a single example.
• frodo idm schema object export/import's -i, --individual-object is now -o, --managed-object, matching every other command in the object/property/relationship families, which all already used -o for the managed object type. import's stays a boolean flag (the type itself still comes from the imported file's own content, same as before) rather than gaining a <type> value with no functional use.
• Revised the frodo idm schema object/property/relationship and frodo feature/script type command families' help text for consistency: flag descriptions are now free of examples (E.g. "...") and use "Managed object type."/"Property name."/"Relationship property name." uniformly, -y/--yes now reads "Answer y/yes to all prompts." everywhere instead of a command-specific phrase, and a few other wording tweaks (e.g. "Property description." instead of "Display description.", "Mark the property searchable in the UI." instead of the longer "omitted if not passed" phrasing).
• frodo idm schema object create/update's --icon now writes mat-icon (a Material Design Icon name, e.g. directions_boat) instead of icon (a Font Awesome name). Confirmed via PingIDM's docs that icon only applies to standalone IDM while mat-icon is what the Ping Identity Platform's own Admin UI reads, and this command only ever targets Cloud/ForgeOps (Platform deployments) -- every live example checked this session had both fields set, with only mat-icon matching what the modern Admin UI actually displays. SampleData's icon example changed from fa-ship to directions_boat to match.
• frodo idm schema property create/update/delete's type definitions (SchemaPropertyFields), payload building (buildSchemaPropertyPayload), current-value parsing (extractSchemaPropertyFields), the --property-type choice list, and the sub-property dot-path navigation helpers now come from frodo-lib (ManagedObjectSchemaPropertyFields/buildManagedObjectSchemaPropertyPayload/extractManagedObjectSchemaPropertyFields/MANAGED_OBJECT_SCHEMA_CREATABLE_PROPERTY_TYPES/navigatePropertyPath and friends) instead of being defined locally in this CLI, along with the actual read-modify-write for create/update/delete (frodo.idm.managed.schema.createManagedObjectSchemaFlatProperty/updateManagedObjectSchemaFlatProperty/removeManagedObjectSchemaFlatProperty) -- this CLI now only handles flag parsing, the confirmation prompt/diff on update/delete, and progress indicators. Pure refactor: no behavior change for create/update/delete/describe/list/export/import, apart from the two new validations noted above.
• frodo idm schema object create/update/delete's type-schema building (buildManagedObjectTypeConfig), the default icon constant, and the actual read-modify-write/existence checks now come from frodo-lib (buildManagedObjectTypeSchema/MANAGED_OBJECT_TYPE_DEFAULT_ICON/frodo.idm.managed.schema.createManagedObjectType/updateManagedObjectType/removeManagedObjectType) instead of being defined locally in this CLI -- this CLI now only handles flag parsing, the confirmation prompt/diff, and progress indicators. Pure refactor: no behavior change.
• frodo idm schema relationship create/update/delete's type definitions (RelationshipPropertyFields/RelationshipReverseCreateFields), payload building/parsing (buildRelationshipPropertyPayload/extractRelationshipFields/toReverseDescriptorFields/inferReverseIdentity), and the actual read-modify-write orchestration -- including the bidirectional reverse-side handling (auto-create on create, the required reverse-descriptor re-supply and second write on update, and the ordered delete-with-cascade-404-as-success handling on delete) -- now come from frodo-lib (ManagedObjectSchemaRelationshipPropertyFields/ManagedObjectSchemaRelationshipReverseFields/buildManagedObjectSchemaRelationshipPropertyPayload/extractManagedObjectSchemaRelationshipPropertyFields/toManagedObjectSchemaRelationshipReverseFields/inferManagedObjectSchemaRelationshipReverseIdentity/frodo.idm.managed.schema.createManagedObjectSchemaRelationshipProperty/updateManagedObjectSchemaRelationshipProperty/removeManagedObjectSchemaRelationshipProperty) instead of being defined locally in this CLI -- this CLI now only handles flag parsing, building the confirmation prompt/diff (describe/update/delete still read the property directly for this preview), and progress indicators. update --with-reverse's two writes (forward, then reverse) now run under a single progress indicator instead of two sequential ones, since a partial failure (forward succeeded, reverse didn't) is now reported as one descriptive error rather than a second indicator's own failure message; the underlying behavior (including no automatic rollback) is unchanged. Otherwise a pure refactor: no other behavior change for create/update/delete/describe/export/import/list.
• frodo idm schema object/property/relationship, frodo feature, and frodo script type's usage examples now use ${connId} (a short connection-profile alias, e.g. matrix) for every example after the first on each command, instead of the full ${amBaseUrl} (e.g. https://openam-matrix.id.forgerock.io/am) on all of them -- the first example on each command still uses the full URL, so both forms stay visible, while the (often long, multi-flag) later examples read far more clearly with the short form.
• README: promoted MCP Server from a ### MCP Server subsection buried under ## Usage to its own top-level ## MCP Server section, added it to the Quick Nav table of contents, and gave it a callout in the top summary -- frodo-cli's MCP server is turn-key (reuses an existing connection profile, no separate server to build or host), so it belongs alongside the other top-level sections instead of nested where it was easy to miss.

Fixed

• program.help() calls process.exit() internally, reading whatever process.exitCode already is at that point (defaulting to 0) -- across 155 command files, every "missing required option"/"unrecognized combination" fallback set process.exitCode = 1 after calling program.help(), so that line never took effect and the command silently exited 0 despite the error it had just printed. Same fix everywhere: set process.exitCode first.
• idm-schema-object-export.e2e.test.js's three "ForgeOps Tests" passed the cloud connection instead of the forgeops one (defined but never actually used) -- one passed by coincidence, the other two (plus the corresponding idm-schema-object-import.e2e.test.js case) have no recorded fixture at all for their exact forgeops scenario and are marked test.skip with an explanatory comment rather than left silently misrepresenting cloud data as forgeops.
• heading's dark-theme color (whiteBright) was indistinguishable from most dark terminals' own default foreground -- e.g. frodo info's table labels ("Host URL", "AM Version", etc.) looked uncolored next to genuinely colored text. Now blueBright (dark) / magentaBright (light), chosen because both clear WCAG's bold-text 3:1 threshold and are visually distinct from typical default text, unlike white on a light-foreground terminal.
• FeatureOps.ts's "not installed" had been turned red by an over-broad muted-to-error(now negative) conversion; it's a neutral, expected state, not a negative one, and is back to muted. JourneyOps.ts's describe-view flags (Inner Tree Only/Must Run/No Session/Transactional Only) now match the list view's existing cautionary framing (warning for the risky "on" state, positive for the safe default) instead of a plain true=positive/false=negative read that contradicted it.
• Terminal-background auto-detection (frodo settings theme detect) could match a genuinely near-white background to the colored yellow/blue presets instead of light, since those presets weren't competing against plain black/white as candidates, only used as a distance-based fallback. Both are now real candidates in the match.
• frodo idm schema relationship no longer rejects ForgeOps deployments. IDM's dedicated v2 relationship-schema API is a standard IDM REST API available since IDM 7.5.0, not Cloud-specific as previously assumed; the command tree is now gated to any deployment that runs IDM (Cloud and ForgeOps), rejecting only classic.
• frodo idm schema relationship create/update/delete now wait for the relationship-property config write to fully propagate before returning (via a frodo-lib default), matching a captured, working Platform Admin UI request for the same endpoint -- avoids an occasional race where an immediately-following read or dependent write (e.g. auto-creating a bidirectional relationship's reverse side) could see IDM's config not yet fully applied.
• frodo idm schema object describe/property describe's Type column no longer shows a raw number,null for a nullable property (IDM represents nullable as type: [x, "null"], not a plain string); Type now renders the plain x, with nullability moved to its own NUL flag column (between Type and REQ, added to the legend) alongside REQ/SRH/UED/VIW, and Title now comes before Type.
• frodo idm schema property describe/export now read via the same raw managed config entity create/update already use, instead of the dedicated per-type schema endpoint, which silently omits a virtual property's onRetrieve/onStore script -- describe was showing an incomplete definition for one, and export was silently dropping the script on an export/import round trip.
• object describe's Relationships table's Type column no longer shows the redundant relationship/relationship[] -- it now shows the relationship's cardinality (1:1/1:n/n:1/n:n/1:-/n:-, - meaning no reverse configured), and Target moved between Title and Type. The reverse side's own cardinality isn't in the whole-type schema read object describe already had in hand, so getting it right costs one extra dedicated-API read per top-level relationship property (parallelized); a failed read, or a relationship nested under --sub-property (unsupported by that API), falls back to what's locally knowable (1:-/n:-) rather than failing the describe. property describe -r shows the same cardinality in Type when describing a relationship property, but -- like its non-recursive view -- never shows a Target column at all, even then: Target is relationship-specific, and relationship describe is the dedicated command for that.
• frodo idm schema property create/update --property-type no longer offers integer as a choice. It was never a real option: the Admin UI's own property-type picker offers only string/number/boolean/date/time/datetime/duration/object (confirmed both by an earlier live screenshot and, now, by live moSample data -- a type built through that same picker -- whose own "Number" property is type: "number", never "integer"); integer could still be written because create/update write with validate: false, which bypasses IDM's server-side schema validation entirely, not because IDM recognizes it as a property type.