CLI accessibility

Command-line interfaces are text-first, but they are not accessible by default. People use them through different terminals, shells, fonts, themes, operating-system settings, and assistive technologies. Output that works in one setup may be confusing, incomplete, or unusable in another.

Use this guidance when designing or building GitHub command-line experiences. It complements the broader Accessibility fundamentals and applies to commands, prompts, progress, help, errors, and output intended for people or scripts.

Design for a variable environment

Do not assume control over how a command-line interface appears or behaves. A person may change their terminal colors, contrast, typeface, text size, cursor, key bindings, shell, or operating-system accessibility settings. Fonts may omit glyphs, terminals may interpret ANSI sequences differently, and assistive-technology support varies by platform and terminal.

Requirements

• Core tasks must remain understandable and operable without a specific color theme, font, terminal size, pointing device, or Unicode glyph.
• Essential values and actions must remain available at every supported terminal width.
• Information must remain available when styling and animation are disabled.
• Commands must not overwrite, clear, or reposition essential output in a way that removes the only record of what happened.

Updating a progress line or using a full-screen interface is not inherently a violation. The important distinction is whether people can still retrieve essential results and errors after that view changes or closes, for example in terminal history or an accessible transcript.

Recommendations

• You should prefer established terminal conventions over custom interaction models. You should provide --help for usage and examples, use named flags such as --output json for options, and support Ctrl+C to interrupt work. For a selection prompt, you should explain keys such as arrow keys to move and Enter to select, and offer a typed choice when a custom selector is not usable. You should avoid undocumented single-key actions or intercepting familiar keys for unrelated behavior. See the Command Line Interface Guidelines for conventions covering help, arguments, output, and interactivity.
• You should keep layouts useful in narrow windows and when text is enlarged. You should choose layouts based on the available character columns, not an assumed pixel width. For example, use stacked, labeled values below 80 columns, fewer table columns at 80-119 columns, and a fuller layout at 120 columns and above. These are example breakpoints, not accessibility thresholds. You should reflow long text and provide a way to read complete values rather than relying on alignment or truncation.
• You should treat terminal features with limited support as enhancements with a plain-text fallback. You should detect support where possible and offer a documented way to disable enhancements when detection is unreliable.

Make text carry the meaning

Screen readers primarily encounter the terminal as a stream of text. Cursor movement, frequently redrawn regions, spinners, ASCII art, and visually aligned columns can produce noisy or incomplete reading experiences. Explicit text also helps people with low vision, color vision differences, cognitive disabilities, or limited familiarity with the command.

Requirements

• Important information must be stated in text. Color, position, punctuation, icons, and symbols must not be the only way to communicate status or meaning.
• Symbols must be paired with explicit labels, such as Success:, Warning:, and Error:. A check mark, cross, or warning icon alone must not convey the result.
• Resources and values must have meaningful labels; spacing or column alignment alone must not communicate relationships.
• Operations must end with a concise text summary that says what completed, failed, changed, or requires attention.
• Commands, options, prompts, states, and outcomes must use stable, descriptive language.

See Color considerations and WCAG 2.2: Use of Color for related guidance.

Recommendations

• You should use descriptive text labels such as Summary: and Next steps: with short sections to make long output easier to scan and understand. Terminals do not expose semantic headings like web pages, so bold text or a heading-like layout does not provide screen-reader heading navigation. You should keep the reading order and labels meaningful as a plain text stream.
• You should put the most important result first, followed by supporting detail and next steps.
• You should avoid decorative output that adds verbosity without information.
• You should use plain language and explain unfamiliar terms. You should follow the Primer content foundations for GitHub terminology and voice. GitHub staff can also refer to the GitHub voice and tone guidance.

Support keyboard and noninteractive operation

A command-line workflow must work without a mouse. Task-oriented commands should also support noninteractive use so people can avoid interaction patterns that conflict with their shell, terminal, assistive technology, or automation. Conversational and full-screen CLIs may depend on an ongoing exchange; they still need an accessible keyboard and text interaction path, but not every conversational turn needs a flag equivalent.

Requirements

• Every core task must be operable with the keyboard alone.
• Prompts in commands intended for noninteractive use must have a documented way to supply the required input without the prompt, such as a flag, argument, standard input, or configuration. For example, a create command can accept a title through --title instead of a text prompt. For inherently interactive workflows, supported noninteractive tasks must be documented and custom controls must have an accessible text alternative. Safety or permission decisions must not be bypassed just to enable automation.
• Commands must not open a browser, editor, pager, or interactive prompt unexpectedly. They must clearly communicate the behavior and provide a way to bypass it.
• Prompts must state the expected input, available choices, and default value in text.
• Destructive or difficult-to-reverse actions must describe the impact and request confirmation unless the person supplied an explicit noninteractive confirmation option.
• Cancellation must stop new work as soon as it is safe and report what is known about the outcome: what completed, what was stopped, and what may still be running. It must not imply that cancellation undoes completed changes. If a remote operation's state cannot be confirmed, the command must say so and provide a way to check before retrying.
• Secrets and credentials must not be echoed, put in logs or transcripts, or retained for convenience after a failed attempt.

For example, after cancelling a batch upload, report Cancelled: 2 of 5 files uploaded. The remaining 3 were not started. Uploaded files were not removed. If a deployment request was already sent but its result is unknown, report Stopped waiting. The deployment may still be running. Check its status before retrying. rather than claiming that the deployment was cancelled.

Recommendations

• You should use familiar keys and document them next to the relevant action rather than relying on a separate help page.
• You should preserve non-sensitive entered data when validation fails, when practical. For example, keep a valid title while asking the person to correct an invalid repository name. Secrets and credentials are an exception. You should explain when a secret needs to be entered again.
• You should offer an explicit browser or editor path when a task is substantially easier there, without making it the only path.

Communicate status and recovery

People need to know what the command is doing, whether it succeeded, and how to recover when it did not.

Progress

• Long-running operations must provide text that identifies the current activity.
• Progress must not depend on animation alone. When using a spinner or updating a line in place, the command must provide a nonanimated mode and a final text result.
• You should avoid rapid, repeated updates that overwhelm terminal history or assistive-technology announcements.
• When exact progress is unavailable, you should describe the activity without presenting invented precision.

Prompts and confirmations

• You should ask only for information that is necessary at that point in the task.
• You should use direct questions and present choices consistently.
• Before consequential actions, you should summarize the target and impact rather than using a generic prompt such as Continue?.
• After confirmation, the command must state the outcome. The absence of an error must not be the only indication of success.

Errors and recovery

• Error messages must identify what failed and provide a specific recovery step when one is known.
• You should preserve actionable diagnostic details, but separate them from the plain-language summary.
• Failures must use nonzero exit codes, and exit-code behavior must remain consistent.
• If an operation partially succeeds, the command must identify what changed, what did not, and whether it is safe to retry.

Empty states

• An empty result must be distinguishable from a loading state, filtered result, permission problem, and failure.
• The command must state what is empty and should suggest a relevant next action when one exists.

Provide scriptable output

Human-readable output and machine-readable output serve different needs. Trying to make one format serve both can create inaccessible interaction for people and fragile parsing for scripts.

Requirements

• Commands that return structured data must provide a documented machine-readable format when the output is expected to be used in automation.
• Machine-readable output must have a stable structure, contain complete values, and exclude ANSI styling, spinners, prompts, and decorative text.
• Noninteractive use must fail clearly instead of waiting indefinitely for input.
• Primary results and diagnostics must go to predictable output streams; exceptions must be documented.
• Machine-readable values must not be truncated. If human-readable output is shortened, the command must provide a way to request the complete value.

Recommendations

• You should keep human-readable output concise by default and provide explicit options for more or less detail.
• You should make state explicit rather than requiring scripts to infer it from color, symbols, or prose.
• You should document schema changes and avoid changing established field meaning.

Respect preferences and customization

Customization lets people adapt the CLI to their access needs and working environment.

Requirements

• Commands must honor the NO_COLOR convention and provide a documented way to disable color.
• Accessibility-critical information must remain available after color, animation, paging, or other presentation features are disabled.
• Commands must respect established environment preferences for editors, pagers, and browsers where they use them.

Recommendations

• You should provide persistent preferences for frequently used presentation options.
• You should let people control verbosity, animation, paging, and interactive behavior independently where practical.
• You should use reasonable defaults, but make those defaults easy to override.
• You should start with the terminal's configured ANSI colors rather than assuming a fixed foreground and background. An implementation may also query the terminal palette and derive colors or gradients from it, as Copilot CLI does with tooling such as Rampa. These are different approaches to respecting a person's theme, not guarantees of sufficient contrast. You should check text contrast against the actual background, retain explicit text labels, and fall back to the configured ANSI palette or unstyled text when queries or true color are unavailable.
• For credentials needed in noninteractive use, you should prefer a secure credential store or a documented protected input mechanism. You should not recommend passing secrets directly as command-line arguments, which can expose them in shell history or process listings.

Test across terminals and assistive technologies

No single test setup can guarantee an accessible experience. Testing should identify barriers across representative combinations and confirm that fallbacks work.

Required checks

• Core tasks must be tested using only the keyboard, including help, cancellation, validation errors, and recovery.
• Testing must cover color disabled, styling disabled, a narrow terminal, enlarged text, and both light and dark themes.
• Human-readable output must be tested in representative supported shells, terminals, and operating systems.
• Redirected and piped output must be tested to confirm that it remains complete and does not contain interactive control sequences.
• Noninteractive and machine-readable modes must be tested in automation.
• Representative workflows must be tested with the screen readers and terminal combinations the product supports. You should include people who use assistive technology in usability testing when possible.

The combinations tested and any known limitations must be documented. Universal screen-reader or cross-terminal support must not be claimed based on one configuration.

Further reading

• Command Line Interface Guidelines
• GitHub CLI Primer foundations
• Making Content Usable for People with Cognitive and Learning Disabilities
• WCAG 2.2: Keyboard Accessible
• WCAG 2.2: Use of Color
• NO_COLOR