Document CLI design guidance for contributors by dmerand · Pull Request #8745 · Shopify/cli

dmerand · 2026-10-02T20:32:10Z

WHY are these changes introduced?

Contributors and coding agents need CLI design guidance that does not depend on internal documentation or design files. Shared guidance helps new commands and flows stay consistent with the rest of Shopify CLI.

WHAT is this pull request doing?

Adapt the internal CLI design article into public contributor guidance and route coding agents to its design, syntax, and UI rules. Keep command outcomes and flows separate from the existing syntax and UI content rules. Replace private references and screenshots with standalone text, and use the existing JSON, error, and UI contracts.

Preserve supported command defaults and accepted option values. This changes contributor docs, not CLI behavior, so no changeset is needed.

How to manually test your changes?

git show HEAD:AGENTS.md # Follow the design, command, and UI routes.
git show HEAD:docs/cli/designing-for-cli.md
git show HEAD:docs/cli-kit/command-guidelines.md # Check Boolean defaults and accepted-value qualifications.
git show HEAD:docs/cli-kit/ui-kit/guidelines.md # Compare active and completed states.

Checklist

I've considered possible cross-platform impacts (Mac, Linux, Windows)
I've considered possible documentation changes
I've considered analytics changes to measure impact
The change is user-facing — I've identified the correct bump type (patch for bug fixes · minor for new features · major for breaking changes) and added a changeset with pnpm changeset add

Copilot

Copilot review overview

🟢 Approval recommended

The documentation is consistent with existing CLI contracts and its new internal links resolve correctly.

Review effort: Balanced
Findings: None

What changed in this PR

Adds public contributor guidance for designing consistent Shopify CLI commands and terminal experiences.

Changes:

Adds CLI outcome, lifetime, automation, and progress guidance.
Expands command syntax, flag, prompt, banner, and logging conventions.
Links the new guidance from the contributor documentation index.

File	Description
`docs/README.md`	Links the new design guide.
`docs/cli/designing-for-cli.md`	Introduces CLI design principles.
`docs/cli-kit/ui-kit/guidelines.md`	Expands content and terminal UI guidance.
`docs/cli-kit/command-guidelines.md`	Clarifies command structure, flags, options, and help text.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

Copilot review overview

🟢 Approval recommended

The documentation is internally consistent, preserves existing contracts, and its new local links resolve correctly.

Review effort: Balanced
Findings: None

amcaplan · 2026-10-06T09:19:15Z

+
+Use UI Kit's semantic tokens for commands, user input, and other styled text. Use its standard banner types rather than assigning your own colors. The [token system](./readme.md#the-token-system) keeps these meanings consistent without requiring commands to manage a palette.
+
+Developers can customize their terminal colors. A terminal mockup can start with a 16-color palette, but do not depend on exact hues. Keep the standard associations of red with errors, yellow with warnings, and green with success. Always communicate the meaning through text as well as color.


I don't think this is worded strongly enough. The point is that the CLI output should be completely understandable in no color mode, both for accessibility reasons and for environments like CI systems where color or other text decorations like bold/italic/underline may not be supported.

Updated in 510d8a7.

Strengthened: "Output must be completely understandable without color or text decoration." It names accessibility, --no-color, and CI environments without color, bold, italic, or underline. I removed the mockup-palette sentence.

amcaplan · 2026-10-06T09:21:17Z

+
+Developers can customize their terminal colors. A terminal mockup can start with a 16-color palette, but do not depend on exact hues. Keep the standard associations of red with errors, yellow with warnings, and green with success. Always communicate the meaning through text as well as color.
+
+Use emojis sparingly to draw attention or clarify meaning, not as decoration. Keep neutral output quiet. An active indicator, such as UI Kit's animated progress bar, should distinguish running work from completed or failed work.


I believe our policy is not to use emojis at all, because not all terminals and environment support them. We do support a limited set of symbols through the figures package.

Updated in 510d8a7.

Changed to "Do not use emojis," and to use the symbols from @shopify/cli-kit/node/figures. I also replaced the ❌ in the log example with ✖ (figures.cross).

One question: the app dev session logger currently prints ❌ Error, ✅ Ready… and ⚠️ (dev-session-logger.ts, dev-session.ts), and app logs polling uses ❌. Should those move to figures symbols, or is dev-session output an intended exception?

amcaplan · 2026-10-06T09:24:47Z

+
+## Use color and emphasis with purpose
+
+Use grayscale text for neutral information. Use brighter foreground text for emphasis. Reserve color for semantic meaning, such as success, warnings, and errors, or to connect related log entries, such as entries from the same extension.


I don't think we actually use grayscale text for neutral information - we could go in that direction, but I don't think it's a standard today. Instead, usually it's used as an accent color that avoids the impression of highlighting, e.g. as the row title column in a table.

Updated in 510d8a7.

Thanks, that matches what I see in the code. The text now says to use the default text style for most output, and the subdued token as a gray accent that does not suggest highlighting, such as a table's row-title column. I made the same change in the Logs section, which repeated the grayscale rule.

amcaplan · 2026-10-06T09:28:32Z

+| --- | --- |
+| Text entry | A value such as an app name or version name. Offer an editable default when it helps the developer continue. |
+| Single select | A list of choices. Group related choices when that makes the list easier to scan. |
+| Confirmation | A high-risk choice. Use sparingly, such as before deploying an app version that removes an extension. |


Technically Dangerous Confirmation - also, I would define it as being for one-way doors, such as irretrievably deleting information (which is why removing an extension is dangerous - because when the app is deployed, there is the potential for information to be lost).

Updated in 510d8a7.

Split into two rows. "Confirmation" is an ordinary yes-or-no choice. "Dangerous confirmation" is for one-way doors, such as irretrievably deleting information. Its example says that deploying a version that removes an extension can permanently delete that extension's data, and that the developer types a confirmation value.

amcaplan · 2026-10-06T09:29:28Z

+| Single select | A list of choices. Group related choices when that makes the list easier to scan. |
+| Confirmation | A high-risk choice. Use sparingly, such as before deploying an app version that removes an extension. |
+
+An editable default lets the developer press Enter to accept a suggested name or type their own. Show the choice rather than making an unexplained inference. See the [prompt APIs](./readme.md#prompts) for supported defaults and grouping.


This isn't true for text prompts - the default is blank, and the user presses Tab to accept the default.

Updated in 510d8a7.

Right, the input starts blank. I checked the code to describe both keys. TextInput inserts the placeholder on Tab (TextInput.tsx L79–82), and TextPrompt also submits the default on Enter when the answer is empty (answerOrDefault, TextPrompt.tsx L62). The text now reads: "A text prompt shows its default as placeholder text in a blank input. The developer presses Tab to insert the default and edit it, presses Enter to accept it, or types another value." Let me know if Enter-to-accept is something we should not advertise.

amcaplan · 2026-10-06T09:30:22Z

+- A text prompt with a noun and colon: "App name:"
+- A selection prompt followed by a colon: "Select extension type:"
+
+Do not require an interactive prompt for automated use. Follow the [JSON output contracts](../../cli/json-output.md#preserve-compatibility) for the independent roles of output format and interactivity.


I'd phrase this a bit differently, as anything that potentially requires a prompts must be specifiable via a flag for non-interactive cases.

Updated in 510d8a7.

Rephrased: "Anything that can require a prompt must also be specifiable with a flag, so non-interactive runs, such as CI and scripts, can supply it." The link also pointed at an anchor that #8754 removed. It now points to json-output.md#conventions-and-changesets, which covers --json vs --no-input.

amcaplan · 2026-10-06T09:36:18Z

-| package manager | CLI (always Shopify) | Topic | Command | Argument | Flags (with or without options) |
-| :------------- | :------------- | :------------- | :------------- |:------------- |:------------- |
-| yarn | Shopify | app | generate | extension | --type checkout_ui
+A global installation is available across projects. A local installation belongs to one project or directory. For a project-local installation, use that project's package-manager invocation. For example, a project with a local Shopify CLI can use:


We can probably trim all this a bunch, given we're fully into global these days.

Updated in 510d8a7.

Trimmed. The section now only says that examples use a global installation.

amcaplan · 2026-10-06T09:37:05Z

+### Topics

-## Topics
+Create a topic only when you add an entirely new domain to the CLI. Get maintainer input before you add one. Domain topics include `app` and `theme`. Hydrogen commands are supplied by a separate plugin; see the [architecture guide](../cli/architecture.md).


and store and organization now!

Updated in 510d8a7.

Added store and organization to the domain topics.

amcaplan · 2026-10-06T09:37:59Z

-| ✅ | Do:  | pnpm add <package> --ignore-workspace-root-check | This flag is long, but it accurately describes the choice the developer is making. |
-| :------------- | :------------- | :------------- | :------------- |
-|  ❌ | Don't: | rsync --owner | Because it’s unnecessarily terse, it’s ambiguous whether this flag means “preserve the current owner” or “assign ownership”.|
+Do not shorten them to `--sync` and `--reload`: those names remove context. They are not supported alternatives for this command.


This is phrased as a concrete instruction instead of the real intent, which is an example.

Updated in 510d8a7.

Reworded as an example: "Shorter names, such as --sync or --reload, would not say what is synced or reloaded."

amcaplan · 2026-10-06T09:39:27Z

+### Options

-By default, two-word options are formatted with hyphens but should also accept underscores.
+A flag can accept specific values, called options. Accept a space or an equals sign between a flag and its value:


Accept a space or an equals sign between a flag and its value isn't the responsibility of a maintainer, it's part of oclif default behavior.

Updated in 510d8a7.

Agreed. It now describes oclif's behavior ("oclif accepts a space or an equals sign…") instead of a maintainer task.

…cli-20261002 # Conflicts: # AGENTS.md # docs/cli-kit/command-guidelines.md

dmerand · 2026-10-10T20:26:49Z

Thanks for the review, Ariel. I replied in each thread. Other changes in this update:

76c8f18 merges main. It resolves conflicts with Clarify contributor and agent guidance from PR feedback #8744 in AGENTS.md and command-guidelines.md, and keeps Clarify contributor and agent guidance from PR feedback #8744's routes and both of its flag-parsing and JSON/error paragraphs.
510d8a7 also removes the "Select extension type:" example, because the prompt-message-format lint rule rejects "select". It folds that form into the noun-and-colon form.
d3b674e adds two small clarifications that you have not seen yet:
- Help: both the summary and the description are third-person sentence fragments, because help shows both.
- Booleans: the enabled-by-default guidance applies to feature toggles, and a new feature toggle gets both the --OPTION and --no-OPTION forms. Safety controls, destructive actions, output modes such as --json, and other documented opt-in modes are excluded. Existing defaults and forms stay as they are.

Happy to split d3b674e into a separate PR if you prefer.

amcaplan

One additional comment. Sorry I missed it earlier. I trust you'll address before merging.

amcaplan · 2026-10-11T09:16:13Z

+shopify theme dev --live-reload=full-page
+```
+
+For new multi-word option values, use hyphens by default and accept underscore aliases where appropriate. Define and document those aliases explicitly. Existing commands' accepted-value contracts remain authoritative: do not assume an underscore spelling works for every existing option.


and accept underscore aliases where appropriate

Actually, I'm realizing we don't seem to accept underscores anywhere. So we should probably just indicate that it's hyphens or bust.

Document CLI design guidance for contributors

2d5f6c2

github-actions Bot added the no-changelog This PR doesn't include a changeset entry. Is an internal only change not relevant to end users. label Oct 2, 2026

dmerand requested a balanced review from Copilot October 2, 2026 20:32

Copilot started reviewing on behalf of dmerand October 2, 2026 20:33 View session

Copilot AI reviewed Oct 2, 2026

View reviewed changes

Route CLI design guidance from agent instructions

06eaf85

dmerand requested a balanced review from Copilot October 2, 2026 21:16

Copilot started reviewing on behalf of dmerand October 2, 2026 21:17 View session

Copilot AI reviewed Oct 2, 2026

View reviewed changes

dmerand marked this pull request as ready for review October 2, 2026 21:48

dmerand requested a review from a team as a code owner October 2, 2026 21:48

amcaplan requested changes Oct 6, 2026

View reviewed changes

dmerand added 3 commits October 10, 2026 16:25

Merge remote-tracking branch 'origin/main' into donald/designing-for-…

76c8f18

…cli-20261002 # Conflicts: # AGENTS.md # docs/cli-kit/command-guidelines.md

Address CLI design guidance review feedback

510d8a7

Clarify help summaries and boolean feature toggles

d3b674e

dmerand requested a review from amcaplan October 10, 2026 20:26

amcaplan approved these changes Oct 11, 2026

View reviewed changes


		Use UI Kit's semantic tokens for commands, user input, and other styled text. Use its standard banner types rather than assigning your own colors. The [token system](./readme.md#the-token-system) keeps these meanings consistent without requiring commands to manage a palette.

		Developers can customize their terminal colors. A terminal mockup can start with a 16-color palette, but do not depend on exact hues. Keep the standard associations of red with errors, yellow with warnings, and green with success. Always communicate the meaning through text as well as color.


		Developers can customize their terminal colors. A terminal mockup can start with a 16-color palette, but do not depend on exact hues. Keep the standard associations of red with errors, yellow with warnings, and green with success. Always communicate the meaning through text as well as color.

		Use emojis sparingly to draw attention or clarify meaning, not as decoration. Keep neutral output quiet. An active indicator, such as UI Kit's animated progress bar, should distinguish running work from completed or failed work.


		## Use color and emphasis with purpose

		Use grayscale text for neutral information. Use brighter foreground text for emphasis. Reserve color for semantic meaning, such as success, warnings, and errors, or to connect related log entries, such as entries from the same extension.

Conversation

dmerand commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

WHY are these changes introduced?

WHAT is this pull request doing?

How to manually test your changes?

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟢 Approval recommended

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmerand commented Oct 10, 2026

Uh oh!

amcaplan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dmerand commented Oct 2, 2026 •

edited

Loading