Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

cli-ux

Design, implement, or review a command-line interface when its user-facing command contract, interaction behavior, automation output, credentials, or mutation safety is the primary concern. For a bounded CLI mismatch or bug, apply only the relevant contract guidance; do not expand it into a full CLI or authentication redesign.

swyxio · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add swyxio/skills --skill cli-ux

About this skill


name: cli-ux description: Design, implement, or review a command-line interface when its user-facing command contract, interaction behavior, automation output, credentials, or mutation safety is the primary concern. For a bounded CLI mismatch or bug, apply only the relevant contract guidance; do not expand it into a full CLI or authentication redesign.

CLI UX

Design one CLI with two deliberate modes:

  • optimize interactive use for discoverability, concise defaults, and safe recovery;
  • optimize automated use for predictability, bounded context, explicit contracts, and defense in depth.

Keep the CLI self-contained. Do not require an MCP server or companion agent skill. Make the installed CLI capable of describing and safely exercising its own exact-version contract.

Apply this skill proportionally. The requested CLI outcome and concrete risks created by the changed command define the blocking criteria. The remaining sections are design options and review lenses, not a demand to redesign every CLI surface. Stop when the named contract is corrected and focused process or contract tests prove it; report adjacent improvements as follow-ups.

Define one typed command contract

For a new CLI or a command family whose contract is duplicated across surfaces, prefer modeling each command once in a checked-in, versioned registry. Derive these surfaces from it where practical:

  • parsing and validation;
  • human-readable help and examples;
  • machine-readable schema or describe output;
  • request construction;
  • structured success and error output;
  • tests.

Keep schema introspection deterministic and available offline. Include command names, inputs, types, constraints, defaults, conflicts, environment variables, output schemas, exit codes, side effects, and stability status. Do not let help text, validation, and machine schemas become independent sources of truth.

Design the input graph before prompts

Classify inputs in dependency order:

  1. execution mode: interactive TTY or non-interactive;
  2. non-secret selectors and identity fields;
  3. mutually exclusive or conditionally required fields;
  4. local files, configuration, and expected-state constraints;
  5. authorization and confirmation inputs;
  6. secrets;
  7. remote reads and external side effects.

Resolve and validate each layer before moving to the next. Never collect a secret only to report an earlier non-secret error.

For a login command accepting exactly one of --username or --email:

parse flags
-> reject both username and email
-> if neither is present:
   interactive: ask for username or email
   non-interactive: fail with usage and remediation
-> normalize and validate the identity
-> only now prompt for the password
-> authenticate

Hard invariant:

Never display Password: before the command knows which account is being authenticated.

Good:

$ sf auth login
Username or email: user@example.com
Password: ********

Do not infer an identity from unrelated machine state unless documented as an explicit precedence rule.

Support human flags and full-fidelity JSON

Offer ergonomic flags for common operations. For complex requests, also accept one raw JSON value or file that maps to the typed request model without losing nested or newly added API fields.

Use a shape such as:

tool resource create --name demo --region iad
tool resource create --json request.json

Reject ambiguous combinations of raw JSON and request-building flags. Do not deep-merge them or invent hidden precedence. Validate both paths with the same schema and construct the same internal request type.

Do not accept passwords, tokens, or other secrets as ordinary command-line arguments when a safer prompt, stdin, environment, credential file, or credential-store path exists.

Separate interactive and automated contracts

Use deterministic input precedence, normally:

explicit flag > documented environment variable > stored non-secret preference > interactive prompt

Never prompt when stdout or stdin is non-interactive, when a machine-readable mode is selected, or when a no-input option is active. Fail before reading secret input if required non-secret inputs are missing.

Use human-readable output on an interactive TTY and stable JSON or NDJSON when output is piped. Provide explicit overrides such as --output human|json|ndjson; preserve compatibility before changing an existing command's default.

For machine-readable output:

  • emit data only on stdout;
  • emit diagnostics on stderr;
  • never include terminal decoration or progress spinners;
  • return documented nonzero exit codes;
  • keep success and error envelopes schema-stable;
  • include actionable remediation without exposing secrets.

Bound output without hiding data

Protect both terminals and agent context windows:

  • use bounded default page sizes;
  • expose opaque continuation cursors;
  • support field selection or projections for large resources;
  • stream multi-page results as NDJSON where appropriate;
  • report truncation and the continuation mechanism explicitly;
  • never silently discard results.

Avoid fetching every page before emitting the first result. Ensure cancellation stops further requests and leaves stdout syntactically valid for the documented format.

Separate human and agent authentication

Share authorization semantics while supporting distinct credential-acquisition paths:

  • allow browser, password, device, or keychain flows for interactive humans as appropriate;
  • allow narrowly scoped tokens, service identities, injected environment variables, credential files, or stdin for automation;
  • never unexpectedly open a browser or prompt during automated execution;
  • report credential source and effective scope without printing the credential;
  • fail closed on expired, revoked, malformed, or insufficiently scoped credentials.

Request the least authority required for the selected command. Do not make a broad human se

Read the complete source ↗