CLI provider settings descriptor

Status: Proposed, not shipped. The last full contract verification used the checksum-verified official Linux CLI 0.56.2 on 2026-09-01. It rejects config providers --descriptors and has no generic config set or config action. See the pinned audit. The scoped 0.57.0 probes confirm descriptor absence and the unchanged generic-command gap. Track settings delivery and onboarding actions in TODO. All command examples and payloads below describe the proposed contract.

This document defines the CLI contract Plasma needs before it can render real provider settings or onboarding flows without duplicating macOS Swift logic in QML.

The Plasma widget consumes this contract when the upstream codexbar CLI exposes it. If a descriptor is absent or unsupported, Plasma keeps enable/disable, supported single-key setup, docs/dashboard/login links, redacted diagnostics, and CLI command hints available.

Command

The command returns the normal provider list plus a provider-specific descriptor. The descriptor is declarative: it names fields and actions, but the CLI remains the only component that knows how to read, validate, write, import, or redact provider settings.

Descriptor writes use local CLI commands such as codexbar config set --provider amp --field sourceMode --value api --json-only. Descriptor actions use local CLI commands such as codexbar config action --provider openai --action openDashboard --json-only.

Top-level shape

schemaVersion must be incremented for incompatible changes. Plasma should ignore descriptors with an unknown major schema and keep showing CLI command hints.

Fields

Fields are settings the frontend can display or edit. Field order is display order.

Supported field kinds:

• "kind": "text": short non-secret string, such as a base URL or workspace id.
• "kind": "secret": secret input, always written through stdin.
• "kind": "enum": one of a stable option list.
• "kind": "boolean": checkbox/toggle.
• "kind": "number": bounded numeric setting.

Command-like behavior belongs in the descriptor's actions array, not in fields; every field is editable and must provide an allowed writeCommand.

Enum fields include options:

The CLI must validate {value}. Plasma must not infer valid enum values from provider names or config files.

Field, action, and option IDs are machine identifiers. They must match [A-Za-z0-9][A-Za-z0-9._-]* and be no longer than 128 characters. Consumers reject invalid IDs instead of trimming, truncating, or otherwise rewriting them.

Actions

Actions are provider setup flows the CLI knows how to perform.

Useful action categories:

• browser-cookie import
• manual cookie save
• API key save or clear
• OAuth/device-flow handoff
• local app/session probe
• token-account add/edit/remove
• provider diagnostics refresh
• open docs/dashboard/login URL

Actions must report structured JSON with status, optional message, and optional refreshed descriptor. status is ok after a completed action, error after a failed action, or cancelled when the user abandons an interactive flow. A failed action may still exit with code zero, so consumers must inspect the structured status before reporting success.

URL-opening actions should still be local CLI actions. For example, codexbar config action --provider openai --action openDashboard --json-only can return { "status": "ok", "url": "https://..." }; Plasma opens the URL only after the CLI reports it.

Redaction and safety

Do not expose raw secrets.

Rules for the CLI:

• Secret fields must return only redactedValue, never raw values.
• Writes for secrets must use stdin, not command-line arguments.
• Descriptors must not include browser cookie values, bearer tokens, API keys, account IDs that are not already user-visible, or raw diagnostic responses.
• Error messages should be bounded and safe to store in user config.
• Commands must be local codexbar commands, not remote shell snippets.

Rules for Plasma:

• Treat descriptor JSON as a contract, not as raw config.
• Render only supported field kinds.
• Use writeCommand and action command exactly as arrays of argv-like tokens; quote each token when using Plasma's executable data source.
• Reject descriptor commands unless they start with codexbar config and use an allowed local subcommand: set/set-api-key for fields, action for actions.
• Open descriptor-returned URLs only when they are HTTPS URLs.
• Keep secret fields write-only except for redactedValue.
• Fall back to current CLI command hints when a descriptor is missing, unsupported, or invalid.
• Bound rendering work even for malformed descriptors. Plasma inspects at most 32 fields and 32 actions per provider, 64 options per field, and 64 command tokens of at most 2048 characters each. Fields with text values longer than 2048 characters are ignored instead of binding or rewriting the value.

Plasma renderer rules

The first Plasma implementation should be deliberately small:

• Render fields in the Providers page below the redacted diagnostics summary.
• Use native controls: text field, password field, checkbox, combo box, spin box, and buttons.
• Disable controls while their command is in flight.
• After a successful write/action, reload codexbar config providers --descriptors --format json --json-only.
• Keep existing provider enable/disable behavior separate from descriptor fields.
• Do not add provider-specific QML branches for individual settings.

Example descriptor