Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: recommend npm run xds script alias for reliable CLI invocation (#2181)

Cindy Zhangd424f076b6f0
diff --git a/README.md b/README.md
index 93b5ec0dbc..46a1564ec5 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,16 @@ yarn add @xds/core @xds/theme-default
yarn add -D @xds/cli
```
+For reliable CLI access, add this script to your `package.json`:
+
+```json
+"scripts": {
+ "xds": "node node_modules/@xds/cli/bin/xds.mjs"
+}
+```
+
+Then use the CLI as `npm run xds -- component --list`. This avoids path errors when AI assistants or new developers invoke the CLI directly.
+
Then follow the [setup guide](packages/core/README.md#quick-start) to import styles, configure the theme provider, and start using components.
## Packages
diff --git a/packages/cli/docs/getting-started.doc.mjs b/packages/cli/docs/getting-started.doc.mjs
index 02564e55c4..d23e657ec6 100644
--- a/packages/cli/docs/getting-started.doc.mjs
+++ b/packages/cli/docs/getting-started.doc.mjs
@@ -148,17 +148,29 @@ yarn dev`,
content: [
{
type: 'prose',
- text: 'The CLI is your reference for components, tokens, templates, and docs. Use it to discover what\u2019s available.',
+ text: 'The CLI is your reference for components, tokens, templates, and docs. For reliable invocation (especially with AI assistants), add this script to your package.json:',
+ },
+ {
+ type: 'code',
+ lang: 'json',
+ label: 'package.json',
+ code: `"scripts": {
+ "xds": "node node_modules/@xds/cli/bin/xds.mjs"
+}`,
+ },
+ {
+ type: 'prose',
+ text: 'Then discover what\'s available:',
},
{
type: 'code',
lang: 'bash',
label: 'Terminal',
- code: `npx xds component # list all components
-npx xds component Button # props, usage, theming for Button
-npx xds docs # list all doc topics
-npx xds template --list # available page templates
-npx xds docs tokens # spacing, color, radius reference`,
+ code: `npm run xds -- component # list all components
+npm run xds -- component Button # props, usage, theming for Button
+npm run xds -- docs # list all doc topics
+npm run xds -- template --list # available page templates
+npm run xds -- docs tokens # spacing, color, radius reference`,
},
],
},
diff --git a/packages/cli/docs/working-with-ai.doc.mjs b/packages/cli/docs/working-with-ai.doc.mjs
index d739d9aaa7..863897af1a 100644
--- a/packages/cli/docs/working-with-ai.doc.mjs
+++ b/packages/cli/docs/working-with-ai.doc.mjs
@@ -111,6 +111,36 @@ If you don't know all three, run \`npx xds init --features agents\` to generate
},
],
},
+ {
+ title: 'The npm run xds Pattern',
+ content: [
+ {
+ type: 'prose',
+ text: 'AI agents frequently invoke the CLI with incorrect paths (e.g. node_modules/@xds/cli/bin/docs.mjs instead of xds.mjs), leading to silent failures. Adding an npm script alias with the correct path eliminates this entirely.',
+ },
+ {
+ type: 'code',
+ lang: 'json',
+ label: 'package.json',
+ code: `"scripts": {
+ "xds": "node node_modules/@xds/cli/bin/xds.mjs"
+}`,
+ },
+ {
+ type: 'prose',
+ text: 'With this alias, agents use `npm run xds -- component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ label: 'Reliable CLI invocation',
+ code: `npm run xds -- component --list
+npm run xds -- component Dialog --dense
+npm run xds -- docs styling --dense
+npm run xds -- docs tokens --dense`,
+ },
+ ],
+ },
{
title: 'The --dense Flag',
content: [