From 2d5f6c2f1e655a3c21fbccc03638661be483c04e Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Fri, 2 Oct 2026 16:31:43 -0400 Subject: [PATCH 1/5] Document CLI design guidance for contributors --- docs/README.md | 1 + docs/cli-kit/command-guidelines.md | 81 +++++++++++++++---------- docs/cli-kit/ui-kit/guidelines.md | 94 ++++++++++++++++++++++++------ docs/cli/designing-for-cli.md | 33 +++++++++++ 4 files changed, 160 insertions(+), 49 deletions(-) create mode 100644 docs/cli/designing-for-cli.md diff --git a/docs/README.md b/docs/README.md index 5cc37bf77e5..f9e0053871b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,7 @@ The list below contains valuable resources for people interested in contributing * [Get started](./cli/get-started.md) * [Architecture](./cli/architecture.md) +* [Designing for CLI](./cli/designing-for-cli.md) * [Conventions](./cli/conventions.md) * [JSON output contracts](./cli/json-output.md) * [Performance](./cli/performance.md) diff --git a/docs/cli-kit/command-guidelines.md b/docs/cli-kit/command-guidelines.md index 5973e6f9811..a30a0d0e021 100644 --- a/docs/cli-kit/command-guidelines.md +++ b/docs/cli-kit/command-guidelines.md @@ -1,57 +1,78 @@ # Command guidelines +Use [Designing for CLI](../cli/designing-for-cli.md) to choose the command's outcome and flow. These guidelines cover its public syntax and help. Check the [reserved command and flag names](../cli/naming-conventions.md) before you add a name. + ## General command structure -When the CLI is installed via an app package, then commands are structured like this: +Commands move from a broad domain to a specific action: + +| CLI | Topic | Command | Subcommand | Flag and value | +| --- | --- | --- | --- | --- | +| `shopify` | `app` | `deploy` | | | +| `shopify` | `app` | `generate` | `extension` | | +| `shopify` | `theme` | `dev` | | `--live-reload full-page` | + +If a verb applies to more than one object, put the verb before the object: `shopify app generate extension`. Here, `extension` is a subcommand, not a positional argument. Add further subcommands only when they are necessary for clarity. Separate command words with spaces, not hyphens. -| 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: -When the CLI is installed globally, then commands are structured like this: +```sh +npm exec -- shopify app generate extension +``` -|CLI (always Shopify) | Topic | Command | Argument | Flags (with or without options) | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| shopify | hydrogen | add | eslint | _no flag_ | +The command hierarchy stays the same when the CLI is installed globally: -Generic commands that cross domains don't have topics. Examples include help, version, upgrade, and logs: +```sh +shopify app generate extension +``` -| package manager | CLI (always Shopify) | Topic | Command | Argument | Flags (with or without options) | -| :------------- | :------------- | :------------- | :------------- | :------------- | :------------- | -| npm run | shopify | _no topic_ | help | extension | _no flag_ | +### 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). -A new topic should only be created when an entirely new domain is being added to the CLI. Today, topics include adds, themes, and hydrogen. +Commands that apply across domains do not need a domain topic. Examples include `shopify help`, `shopify version`, and `shopify upgrade`. ## Flags -Any given flag needs to be consistent not only within a topic, but also across the main CLI package. A flag always means the same thing, and it can be pre-set to a specific value. +Use flags, rather than positional arguments, to modify command behavior. Named flags make the choice explicit, do not depend on argument order, and are easier to extend without ambiguity. + +A flag must mean the same thing within a topic and across the main CLI package. It can have a pre-set value. Prefer clarity over brevity, especially in scripts and CI environments where a descriptive name documents the developer's intent. + +For example, these names explain both choices: -Flags should be semantically meaningful. When in doubt, optimize for clarity, not brevity. This is particularly important in non-interactive or CI environments, where a command is likely to be a write-once, run-many situation. Verbose flags are better for self-documention. +```sh +shopify theme dev --theme-editor-sync --live-reload full-page +``` -| ✅ | Do: | pnpm add --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. -## Aliases / shortcuts for flags +### Aliases / shortcuts for flags -As a general rule, don't create shortcuts for flags. Create single-letter short-form flag aliases only if the flag is frequently or repetitively used in day-to-day interactive development work. +Use a full name with two hyphens, such as `--store`. As a general rule, do not add a short alias. Add a single-letter alias only for a flag used frequently or repeatedly in daily interactive development. -Shortcuts can leave off the topic keyspace of the command. +Short aliases use one hyphen and can omit context already supplied by the topic. Preserve the reserved meanings of common aliases, such as `-s` for `--store`, and existing topic-specific aliases, such as `-t` for `--theme` in theme commands. -## Booleans +### Booleans -A boolean flag takes the options of either true ('--OPTION') or false ('--no-OPTION'). In general, make the true option the default. That is, `--OPTION` should be the same as not passing the flag at all. Ex: '--tunnel' / '--no-tunnel'. +For a boolean with a supported negated form, `--OPTION` enables the behavior and `--no-OPTION` disables it. In general, make the enabled behavior the default when it is safe and useful for most developers. Do not apply this rule to safety controls or other documented opt-in modes. For example, `shopify theme dev --allow-live` must remain an explicit choice. -## Options +Preserve each existing command's documented defaults and supported flag forms. Do not assume that every boolean automatically supports a `--no-` form. -A flag can accept specific values (called “options”). The CLI should accept either a space or an equals sign: -* generate extension --type checkout_ui -* generate extension --type=checkout_ui +### 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: + +```sh +shopify theme dev --live-reload full-page +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. + +Use a space between the flag and value in documentation. If the value contains spaces, use an equals sign and quote the value so the shell passes it as one value. ## Help -Every command should have a corresponding description in the help directory. The help description should be a sentence fragment in the third-person singular, as if it's a sentence that starts with "This command...' For example: "Adds an extension to your app project" is the description for the command "shopify hydrogen info". +Give every command, flag, and accepted option a description in command help. For a command, write a sentence fragment in the third-person singular, as if it starts with "This command...". For example, describe `shopify app generate extension` as "Generates a new app extension." + +Explain what the command does, not its internal implementation. Keep help, accepted values, and examples consistent with the command definition. Follow the [JSON output contracts](../cli/json-output.md) for result schema documentation. diff --git a/docs/cli-kit/ui-kit/guidelines.md b/docs/cli-kit/ui-kit/guidelines.md index 3daeaaf9e86..60dedd906d1 100644 --- a/docs/cli-kit/ui-kit/guidelines.md +++ b/docs/cli-kit/ui-kit/guidelines.md @@ -1,22 +1,78 @@ -# Content guidelines +# Content and UI guidelines -It's important to be consistent in how we display content to users of the CLI. -These guidelines should guide you when choosing your style of communication with the users. +Use consistent content and visual patterns so developers can focus on their work. Use the [CLI UI Kit](./readme.md) for rendering and [Designing for CLI](../../cli/designing-for-cli.md) for command and flow decisions. ## General content guidelines -- Use contractions (ex: can't instead of cannot). It's the easiest way to sound human. -- Use “we” to refer to Shopify. (This "we" framing acts as a trust signal. In the platform context, Shopify and the developer are building value together. We're not slippery; we're not hiding.) - -## Prompting user inputs with selection and text prompts: -- A full-sentence question (“Have you installed your app on your dev store?”) -- A text prompt with simple noun followed by a colon (“App name:”) -- A list prompt followed by a colon: (“Select extension type:”) - -## Communicating processes with dynamic checkmarks: -- Progress indicators should take this passive voice formula: “Dependencies installed”; “App initialized”; “App deployed”. In other words: 'noun' 'verb' (past participle). - -## Content in banners: -- Each of the banner elements can support robust messaging with a next steps section and a reference section with links. The prompt components can also be customized with, for example, headings to group selection options. -- For info banners: Use present perfect tense to describe a significant display (“The REST API has been deprecated”). -- For error messages: Use the present tense to describe what’s happening in the error message context (“Can’t connect to the Storefront API”) -- More examples in the CLI example page. Run shopify kitchen-sink all + +- Use contractions, such as "can't" instead of "cannot", to sound human. +- Use "we" to refer to Shopify. Make it clear what Shopify does and what the developer controls. +- State what is happening and what the developer can do next. Do not hide consequential decisions behind automatic guesses. + +## 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. + +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. + +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. + +## Prompting user inputs with selection and text prompts + +Use prompts to request information during an interactive session: + +| Prompt | Use | +| --- | --- | +| 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. | + +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. + +Use one of these forms: + +- An explicit question: "Which existing app is this for?" or "Have you installed your app on your dev store?" +- A short question in the context of the flow: "Release a new version of this app?" +- 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. + +## Communicating active and completed work + +For an active progress indicator, describe the work with an *-ing* form, such as "Template downloading" or "App initializing". Put this text with the indicator so the developer knows what is running. + +For completed work shown with dynamic checkmarks, use a noun and past participle: "Dependencies installed", "App initialized", or "App deployed". Do not label an active operation as complete. + +Use the [async task APIs](./readme.md#async-tasks) for consistent progress rendering. If work fails part way through, identify what succeeded and what failed, and give a recovery step when one is known. + +## Content in banners + +Use a banner for information that is usually longer than one line. Choose a success, warning, info, or error banner to match the state. A banner can contain: + +- An optional heading that describes the problem or success state. +- Body text with the details the developer needs. +- Optional **Next steps**: a bulleted list of actions, including specific commands where useful. +- Optional **References**: a list of relevant developer resources. + +See the [static output APIs](./readme.md#static-output) for banner fields. Keep optional sections out when they add no information. + +For info banners, use present perfect tense for a significant change: "The REST API has been deprecated". + +For error headings, use present tense: "Can't connect to the Storefront API". If the recovery is known, give explicit next steps. For example, "View the complete error log at `path/to/file`". Use the Next steps section when there are several actions. Follow the [error handling principles](../../cli/error_handling.md) for the error type and recovery data. + +## Logs + +Logs describe work as it happens. Use present tense for active work, such as "Building GraphQL types…", and past tense for a completed state, such as "order-status successfully built". + +Use grayscale for neutral events that do not require action. Reserve semantic color for errors, warnings, and successes. Stable labels and consistent per-extension colors can connect related entries across a development session. Keep the labels understandable without color. + +Make an error in development-session logs easy to scan: use a heading with an error indicator, then a second line with the problem and the developer's next action. A tree marker can connect the two lines. For example: + +```text +❌ Error +└ Can't connect to the Storefront API. Check your connection and try again. +``` + +This is an illustrative layout, not the exact output of a command. For finite machine-readable output, keep diagnostics and progress separate from the final result as specified by the [JSON output contracts](../../cli/json-output.md). diff --git a/docs/cli/designing-for-cli.md b/docs/cli/designing-for-cli.md new file mode 100644 index 00000000000..0e184cfd13b --- /dev/null +++ b/docs/cli/designing-for-cli.md @@ -0,0 +1,33 @@ +# Designing for CLI + +Design for app, theme, Hydrogen, and merchant developers, and for the machines that run their workflows. Give developers helpful defaults and a clear path from setup to daily work. Use familiar patterns so that learning one command helps them use another. + +Get input from the repository maintainers before you add a command, a topic, or a new flow. Use the [Command Line Interface Guidelines](https://clig.dev/) for questions not covered here. Repository-specific contracts take precedence over that general guidance. + +## Give each command one clear outcome + +A command should do one thing well for the developer. One outcome can require several processes. For example, `shopify app dev` can handle authentication, app setup, builds, validation, and serving a preview. Those steps support one outcome: previewing the developer's work. + +Keep commands simple, powerful, and precise. Use flags to make a command expressive without making developers learn the CLI before they can build. Prefer a small set of commands that cover common workflows, such as `shopify app dev`, `shopify app deploy`, and `shopify app generate extension`. Add a command only when it serves a distinct outcome that existing commands cannot express clearly. + +Use the same term for the same activity across domains. For example, both `shopify app dev` and `shopify theme dev` use `dev` for a development session. Follow the [command guidelines](../cli-kit/command-guidelines.md) for hierarchy, topics, flags, and help text, and the [reserved names](./naming-conventions.md) for shared commands and flags. + +## Choose a clear command lifetime + +Most commands finish a task and exit, such as generating an extension or initializing an app. Commands that run until the developer stops them should be rare. Before you add one, consider whether the work belongs in an existing development session, such as `shopify theme dev`. + +Design for automation as well as interactive use. A finite command returns one final result. A long-lived development session produces an open-ended stream. Follow the [JSON output contracts](./json-output.md) for finite results, streaming exemptions, and the separate roles of output format and interactivity. Do not make scripts parse terminal presentation to obtain a result. + +## Make long operations understandable + +Keep jobs in the foreground unless they are truly long-running (three minutes or more), or the developer explicitly requests background execution through a flag. This is a design guideline for a feature that supports background work, not a claim that every command has a background mode. + +Choose timeout defaults that cover the expected use cases. Aim to cover 95% of cases without making developers guess a timeout. This is a design target, not a measured success rate for existing commands. Use the [performance guide](./performance.md) to investigate slow work. + +Show meaningful progress during longer operations. Make it clear whether work is running, has succeeded, or has failed. If an operation fails part way through, tell the developer what succeeded before the failure and what they can do next. Follow the [error handling principles](./error_handling.md) for error types and recovery details; keep progress separate from the final result as specified by the JSON contract. + +## Keep the terminal experience consistent + +Use the [CLI UI Kit](../cli-kit/ui-kit/readme.md) instead of creating a separate visual language. Keep neutral text quiet, use emphasis and semantic color with purpose, and avoid distractions. Helpful prompts and editable defaults should keep developers moving without hiding consequential choices. + +The [content and UI guidelines](../cli-kit/ui-kit/guidelines.md) cover banners, prompts, active progress, completed states, and logs. Use the [UI Kit contribution guide](../cli-kit/ui-kit/contributing.md) when an existing component does not meet the need. The [architecture](./architecture.md) and [code conventions](./conventions.md) describe where the implementation belongs. From 06eaf85f0d1ce183fd92c0ff96f1a949681c05dd Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Fri, 2 Oct 2026 17:14:20 -0400 Subject: [PATCH 2/5] Route CLI design guidance from agent instructions --- AGENTS.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 809b20882d9..f7a02610d06 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,6 +60,7 @@ If the change is not ready to be public, do not add a changeset. - [docs/README.md](docs/README.md) - [docs/cli/architecture.md](docs/cli/architecture.md) +- [docs/cli/designing-for-cli.md](docs/cli/designing-for-cli.md) — Design command outcomes, lifetimes, and long-running workflows. - [docs/cli/conventions.md](docs/cli/conventions.md) - [docs/cli/cross-os-compatibility.md](docs/cli/cross-os-compatibility.md) - [docs/cli/debugging.md](docs/cli/debugging.md) @@ -73,12 +74,12 @@ If the change is not ready to be public, do not add a changeset. ### CLI kit -- [docs/cli-kit/command-guidelines.md](docs/cli-kit/command-guidelines.md) -- [docs/cli-kit/errors.md](docs/cli-kit/errors.md) +- [docs/cli-kit/command-guidelines.md](docs/cli-kit/command-guidelines.md) — Define command syntax, flags, option values, and help text. +- [docs/cli/error_handling.md](docs/cli/error_handling.md) - [packages/cli/README.md](packages/cli/README.md) ### UI kit - [docs/cli-kit/ui-kit/contributing.md](docs/cli-kit/ui-kit/contributing.md) -- [docs/cli-kit/ui-kit/guidelines.md](docs/cli-kit/ui-kit/guidelines.md) +- [docs/cli-kit/ui-kit/guidelines.md](docs/cli-kit/ui-kit/guidelines.md) — Write prompts, banners, progress, and logs, and use semantic styling. - [docs/cli-kit/ui-kit/readme.md](docs/cli-kit/ui-kit/readme.md) From 510d8a714785b8c81e185f6d8ac7198e7caf43d3 Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Sat, 10 Oct 2026 16:25:53 -0400 Subject: [PATCH 3/5] Address CLI design guidance review feedback --- docs/cli-kit/command-guidelines.md | 18 ++++-------------- docs/cli-kit/ui-kit/guidelines.md | 24 ++++++++++++------------ 2 files changed, 16 insertions(+), 26 deletions(-) diff --git a/docs/cli-kit/command-guidelines.md b/docs/cli-kit/command-guidelines.md index cd1457544e3..c6a1ab114c0 100644 --- a/docs/cli-kit/command-guidelines.md +++ b/docs/cli-kit/command-guidelines.md @@ -14,21 +14,11 @@ Commands move from a broad domain to a specific action: If a verb applies to more than one object, put the verb before the object: `shopify app generate extension`. Here, `extension` is a subcommand, not a positional argument. Add further subcommands only when they are necessary for clarity. Separate command words with spaces, not hyphens. -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: - -```sh -npm exec -- shopify app generate extension -``` - -The command hierarchy stays the same when the CLI is installed globally: - -```sh -shopify app generate extension -``` +Examples use a global installation of Shopify CLI. ### 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). +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`, `theme`, `store`, and `organization`. Hydrogen commands are supplied by a separate plugin; see the [architecture guide](../cli/architecture.md). Commands that apply across domains do not need a domain topic. Examples include `shopify help`, `shopify version`, and `shopify upgrade`. @@ -44,7 +34,7 @@ For example, these names explain both choices: shopify theme dev --theme-editor-sync --live-reload full-page ``` -Do not shorten them to `--sync` and `--reload`: those names remove context. They are not supported alternatives for this command. +Shorter names, such as `--sync` or `--reload`, would not say what is synced or reloaded. For changed dependent or defaulted flags, test omitted, explicit, default, valid, and invalid combinations through actual command parsing. A default value does not prove explicit presence; choose dependency declarations according to the intended behavior, not an “always `dependsOn`” rule. @@ -64,7 +54,7 @@ Preserve each existing command's documented defaults and supported flag forms. D ### Options -A flag can accept specific values, called options. Accept a space or an equals sign between a flag and its value: +A flag can accept specific values, called options. oclif accepts a space or an equals sign between a flag and its value: ```sh shopify theme dev --live-reload full-page diff --git a/docs/cli-kit/ui-kit/guidelines.md b/docs/cli-kit/ui-kit/guidelines.md index 60dedd906d1..891b540d81a 100644 --- a/docs/cli-kit/ui-kit/guidelines.md +++ b/docs/cli-kit/ui-kit/guidelines.md @@ -10,13 +10,13 @@ Use consistent content and visual patterns so developers can focus on their 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. +Use the default text style for most output. Use the `subdued` token as a gray accent that does not suggest highlighting, such as the row-title column of a table. Reserve color for semantic meaning, such as success, warnings, and errors, or to connect related log entries, such as entries from the same extension. 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. +Output must be completely understandable without color or text decoration. This supports accessibility, `--no-color`, and environments such as CI systems where color, bold, italic, or underline may not be available. Developers can also customize their terminal colors, so do not depend on exact hues. Keep the standard associations of red with errors, yellow with warnings, and green with success. -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. +Do not use emojis: not every terminal and environment can display them. Use the limited set of symbols that `@shopify/cli-kit/node/figures` provides. Keep neutral output quiet. An active indicator, such as UI Kit's animated progress bar, should distinguish running work from completed or failed work. ## Prompting user inputs with selection and text prompts @@ -24,20 +24,20 @@ Use prompts to request information during an interactive session: | Prompt | Use | | --- | --- | -| Text entry | A value such as an app name or version name. Offer an editable default when it helps the developer continue. | +| Text entry | A value such as an app name or version name. Offer a 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. | +| Confirmation | A yes-or-no choice before the command continues, such as "Release a new version of this app?" | +| Dangerous confirmation | A one-way door, such as irretrievably deleting information. For example, deploying an app version that removes an extension can permanently delete that extension's data. The developer types a confirmation value. Use sparingly. | -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. +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. Show the choice rather than making an unexplained inference. See the [prompt APIs](./readme.md#prompts) for supported defaults and grouping. Use one of these forms: - An explicit question: "Which existing app is this for?" or "Have you installed your app on your dev store?" - A short question in the context of the flow: "Release a new version of this app?" -- A text prompt with a noun and colon: "App name:" -- A selection prompt followed by a colon: "Select extension type:" +- A text or selection prompt with a noun and colon: "App name:" -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. +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. Follow the [JSON output contracts](../../cli/json-output.md#conventions-and-changesets) for the independent roles of `--json` and `--no-input`. ## Communicating active and completed work @@ -66,12 +66,12 @@ For error headings, use present tense: "Can't connect to the Storefront API". If Logs describe work as it happens. Use present tense for active work, such as "Building GraphQL types…", and past tense for a completed state, such as "order-status successfully built". -Use grayscale for neutral events that do not require action. Reserve semantic color for errors, warnings, and successes. Stable labels and consistent per-extension colors can connect related entries across a development session. Keep the labels understandable without color. +Keep neutral events that do not require action in the default text style. Reserve semantic color for errors, warnings, and successes. Stable labels and consistent per-extension colors can connect related entries across a development session. Keep the labels understandable without color. -Make an error in development-session logs easy to scan: use a heading with an error indicator, then a second line with the problem and the developer's next action. A tree marker can connect the two lines. For example: +Make an error in development-session logs easy to scan: use a heading with an error symbol, then a second line with the problem and the developer's next action. A tree marker can connect the two lines. For example: ```text -❌ Error +✖ Error └ Can't connect to the Storefront API. Check your connection and try again. ``` From d3b674e08907eac99142e56f23099db26d212571 Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Sat, 10 Oct 2026 16:25:53 -0400 Subject: [PATCH 4/5] Clarify help summaries and boolean feature toggles --- docs/cli-kit/command-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cli-kit/command-guidelines.md b/docs/cli-kit/command-guidelines.md index c6a1ab114c0..a953064e110 100644 --- a/docs/cli-kit/command-guidelines.md +++ b/docs/cli-kit/command-guidelines.md @@ -48,7 +48,7 @@ Short aliases use one hyphen and can omit context already supplied by the topic. ### Booleans -For a boolean with a supported negated form, `--OPTION` enables the behavior and `--no-OPTION` disables it. In general, make the enabled behavior the default when it is safe and useful for most developers. Do not apply this rule to safety controls or other documented opt-in modes. For example, `shopify theme dev --allow-live` must remain an explicit choice. +A feature toggle turns a behavior on or off, such as `--watch` and `--no-watch` in `shopify app function replay`. Give a new feature toggle both forms: `--OPTION` enables the behavior and `--no-OPTION` disables it. In general, make the enabled behavior the default when it is safe and useful for most developers. This does not apply to safety controls, destructive actions, output modes such as `--json`, or other documented opt-in modes. For example, `shopify theme dev --allow-live` must remain an explicit choice. Preserve each existing command's documented defaults and supported flag forms. Do not assume that every boolean automatically supports a `--no-` form. @@ -67,6 +67,6 @@ Use a space between the flag and value in documentation. If the value contains s ## Help -Give every command, flag, and accepted option a description in command help. For a command, write a sentence fragment in the third-person singular, as if it starts with "This command...". For example, describe `shopify app generate extension` as "Generates a new app extension." +Give every command, flag, and accepted option a description in command help. For a command, write both the summary and the description as sentence fragments in the third-person singular, as if they start with "This command...". Help shows both. For example, describe `shopify app generate extension` as "Generates a new app extension." Explain what the command does, not its internal implementation. Keep help, accepted values, and examples consistent with the command definition. Follow the [JSON output contracts](../cli/json-output.md) for result schema documentation. From b1349892d01119778666c084028dc2e82c2633e7 Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Sun, 11 Oct 2026 10:11:20 -0400 Subject: [PATCH 5/5] Use hyphens only in multi-word option values --- docs/cli-kit/command-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli-kit/command-guidelines.md b/docs/cli-kit/command-guidelines.md index a953064e110..82136490c52 100644 --- a/docs/cli-kit/command-guidelines.md +++ b/docs/cli-kit/command-guidelines.md @@ -61,7 +61,7 @@ shopify theme dev --live-reload full-page 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. +Separate words in option values with hyphens, such as `full-page`. Do not use or accept underscores. Use a space between the flag and value in documentation. If the value contains spaces, use an equals sign and quote the value so the shell passes it as one value.