Source: ViewEdit

CLI Dispatch conformance

This page defines how a tool shows that it meets CLI Dispatch. The key words MUST, SHOULD and MAY follow BCP 14. It complements the general Certification Program.

Who grants certification, whether a third-party review is required, and the final name and artwork of any badge are open decisions. Until they are recorded here, only self-declared conformance (below) is available, and it MUST NOT be presented as OSO certification.

Levels

Level Meaning

Migrating

The tool is in a current-major migration release: CD-11, CD-13, CD-14 and CD-15 are met (warnings in the fixed format, strict opt-in, announced flip version), and with strict enabled every self-test below passes.

Strict

Every rule CD-1 to CD-17 is met with default settings. This is the level that conforms; Migrating is a time-limited step towards it and lapses when the announced major version ships.

A tool that keeps implicit behaviour as its default after the announced major version has neither level.

Self-test

Run each case with default settings (and again with --strict for the Migrating level), in a sandbox with no network access. "stderr contains" means the listed text appears on stderr; stdout MUST be empty in every error case. <tool> is the tool under test; zzqx is any word that is not a command.

Command Exit stderr contains Rules

<tool> zzqx

2

unknown command 'zzqx' and a help pointer or command list

CD-1, CD-3

<tool> <known command with one letter swapped> (e.g. biuld)

2

unknown command and did you mean: <known command>

CD-1

<tool> zzqx with network disabled and a file-write monitor

2

no network or file activity is observed

CD-2

<tool>

0

help or usage on stdout/stderr, or running default: <action>

CD-5, CD-6

<tool> --zzqx

2

--zzqx named as unknown

CD-8

<no-argument tool or GUI launcher> zzqx

2

takes no arguments (or equivalent) naming zzqx

CD-7

<wrapper> <command only the underlying tool has>

2

does not implement '<command>' and the tool that does

CD-10

<tool> zzqx in a migration release, strict off

per legacy behaviour

the three CD-13 lines, before any other output

CD-11, CD-13

<tool> --strict zzqx and <TOOL>_STRICT=1 <tool> zzqx

2

unknown command 'zzqx'

CD-14

<tool> --help

0

every command the dispatcher accepts is listed

CD-16

<tool> -h and (for a tool with subcommands) <tool> help; stdout captured

0

nothing on stderr except help-system notices; stdout is the same help as <tool> --help; help is not run as a target

CH-1, CH-2, CH-4, CH-17

<tool> help <command>, <tool> ? <command> and <tool> <command> --help for every command

0

help for that command on stdout, the same for all three forms

CH-15

<tool> help zzqx (or <tool> ? zzqx)

2

zzqx named as unknown, a pointer to top-level help; stdout empty

CH-16, CH-18

<tool> --help | cat

0

no colour or terminal control sequences in stdout

CH-19

<tool> --help and <tool> <command> --help for every command, plus --json results

0

one and the same declared style (strict if none is declared) for every command and subcommand; no command declares or behaves in another style

CS-9

Help rows above cover the parts of CLI Help that a black-box test can see; the full list is its conformance checklist (CH-1 to CH-24).

Style checklist (CLI Styles):

  • The tool declares exactly one style for its whole command surface (CS-9).

  • No command or subcommand uses a different style; the other style’s behaviour, if wanted, ships as a separate tool (CS-9).

  • Advisory (SHOULD): if the tool uses the resolver style, its name is a verb; a noun-named tool uses the strict style with verb subcommands (CS-10).

Example script (POSIX shell):

t=pkg
out=$($t zzqx 2>err.txt); code=$?
[ "$code" -eq 2 ] || echo "FAIL CD-1: exit $code"
[ -z "$out" ] || echo "FAIL CO-20: stdout not empty"
grep -q "unknown command 'zzqx'" err.txt || echo "FAIL CD-1: message"

Claiming conformance

A project that passes the self-test MAY state conformance in its README or reference docs. The statement MUST name the level, the standard page, the date it was checked and the tool version, for example:

Conforms to OpenShellOrg CLI Dispatch (level: Strict), checked 2026-10-26 against pkg 3.0.0.
https://docs.opensh.org/open-shell-org/standard-cli-dispatch.html

A Migrating statement MUST also name the major version in which strict becomes the default. A project MAY link a self-test transcript. A badge is planned; its name and artwork are pending (see the note at the top).

Reporting non-conformance

Report non-conformance to the tool’s own issue tracker first. A report SHOULD contain:

  1. the tool name and exact version;

  2. the exact command, its stdout, stderr and exit code;

  3. the rule ids it violates (for example CD-3, CD-2);

  4. the conforming behaviour expected, quoting the rule;

  5. for tools with implicit behaviour, a pointer to CD-11 to CD-15 so the maintainer sees the migration path, not just the complaint.

Keep reports factual and neutral: describe what the tool did, not the maintainers. Reports about the standard itself (an unclear or wrong rule) go to the openshellorg/docs issue tracker.