Skip to content

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

TypeScript

fix(cli): scope CLI invocation so bare `npx astryx` never hits the squatter (#4151)

Joey04cd8f736346
diff --git a/.changeset/cli-scoped-invocation-footgun.md b/.changeset/cli-scoped-invocation-footgun.md
new file mode 100644
index 0000000000..a820eb6436
--- /dev/null
+++ b/.changeset/cli-scoped-invocation-footgun.md
@@ -0,0 +1,17 @@
+---
+'@astryxdesign/cli': patch
+'@astryxdesign/core': patch
+---
+
+[fix] Stop suggesting bare `npx astryx` before the CLI is installed — it resolves to an unrelated package on the npm registry.
+
+The CLI now emits an install-aware invocation everywhere it prints a command:
+
+- Installed / global / dev runs suggest `<pm> astryx <cmd>` (e.g. `pnpm exec astryx …`), unchanged.
+- One-off runs (launched via `npx`/`pnpm dlx`/`yarn dlx`/`bunx`) suggest the scoped package `<dlx> @astryxdesign/cli <cmd>`, which always resolves to us.
+
+This is driven by a single source of truth in `package-manager.mjs` (`getCliInvocation`, `formatCliCommand`, `getDlxPrefix`, `isCliOneOff`) and applied to every runtime hint the CLI prints — `search`, `component`, `hook`, `docs`, `build`, `template`, `swizzle`, `discover`, `theme`, `init`, `upgrade`, `doctor`, the update-check notice, the manifest pointer, and the postinstall banner — plus the injected `AGENTS.md`/`CLAUDE.md` index. The postinstall banner also no longer prints a stale `npx xds init`. Structured `--json` fields (e.g. search `command`, upgrade `suggestedCommand`) keep the canonical bare `astryx <cmd>` form; only the human-facing print is rewritten.
+
+Docs are aligned too: bootstrap commands use the scoped package or an explicit install-then-run flow, and reference commands use the bare `astryx <cmd>` form (which fails cleanly if the CLI isn't installed, rather than fetching a look-alike package). The core `<Theme>` runtime warning and the docsite copy-commands now use `npx @astryxdesign/cli …`.
+
+@joeyfarina
diff --git a/.claude/commands/create-theme.md b/.claude/commands/create-theme.md
index b6d5bbf60e..fe63815b66 100644
--- a/.claude/commands/create-theme.md
+++ b/.claude/commands/create-theme.md
@@ -145,7 +145,7 @@ Component overrides generate scoped CSS:
### Distribution
- **Unbuilt**: `Theme` generates CSS and injects `<style>` at runtime
-- **Built**: `npx astryx theme build` pre-compiles to a CSS file
+- **Built**: `astryx theme build` pre-compiles to a CSS file
## Extending an Existing Theme
diff --git a/.claude/skills/writing-component-docs.md b/.claude/skills/writing-component-docs.md
index 9bc537a73d..1375c06465 100644
--- a/.claude/skills/writing-component-docs.md
+++ b/.claude/skills/writing-component-docs.md
@@ -108,12 +108,12 @@ The CLI merges this onto `docs`: compressed descriptions replace English ones, b
## CLI Flags
```bash
-npx astryx component Button # Full docs (default)
-npx astryx --detail compact component Button # Token-optimized format
-npx astryx --detail brief component Button # Minimal one-line summary
-npx astryx --lang zh component Button # Chinese prose, same structure
-npx astryx --lang dense component Button # Compressed prose, same structure
-npx astryx --detail compact --lang dense component Button # Compact + compressed
+astryx component Button # Full docs (default)
+astryx --detail compact component Button # Token-optimized format
+astryx --detail brief component Button # Minimal one-line summary
+astryx --lang zh component Button # Chinese prose, same structure
+astryx --lang dense component Button # Compressed prose, same structure
+astryx --detail compact --lang dense component Button # Compact + compressed
```
`--lang` controls which prose translation is used. `--detail` controls how much detail (full, compact, brief). They compose independently.
@@ -134,9 +134,9 @@ Content is structured as sections with ordered content blocks:
To add a new reference doc: create `packages/cli/docs/mytopic.doc.mjs` exporting a `docs` constant. It auto-discovers.
```bash
-npx astryx docs # list topics
-npx astryx docs tokens # full output
-npx astryx docs tokens spacing # single section
-npx astryx --detail compact docs tokens # agent-friendly
-npx astryx --lang dense docs tokens # compressed prose
+astryx docs # list topics
+astryx docs tokens # full output
+astryx docs tokens spacing # single section
+astryx --detail compact docs tokens # agent-friendly
+astryx --lang dense docs tokens # compressed prose
```
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 30632544e2..76a9ce18ad 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -169,7 +169,7 @@ astryx/
│
├── packages/
│ ├── core/ # Core components (Button, Input, etc.)
-│ ├── cli/ # CLI tooling (npx astryx)
+│ ├── cli/ # CLI tooling (astryx)
│ ├── lab/ # Experimental components (not yet stable)
│ └── themes/ # Theme presets (default, neutral, daily, and more)
│
diff --git a/apps/docsite/src/app/(docs)/docs/[topic]/page.tsx b/apps/docsite/src/app/(docs)/docs/[topic]/page.tsx
index 6b7025c95c..016bbb2453 100644
--- a/apps/docsite/src/app/(docs)/docs/[topic]/page.tsx
+++ b/apps/docsite/src/app/(docs)/docs/[topic]/page.tsx
@@ -42,7 +42,7 @@ function getInstallSteps(pkgName: string): InstallStep[] {
if (pkgName.endsWith('/cli')) {
return [
{label: 'Install the CLI', code: `npm install -D ${pkgName}`},
- {label: 'Run a command', code: `npx astryx component --list`},
+ {label: 'Run a command', code: `npx @astryxdesign/cli component --list`},
];
}
return [
diff --git a/apps/docsite/src/components/TemplatePreviewDialog.tsx b/apps/docsite/src/components/TemplatePreviewDialog.tsx
index e9ae3d221d..48eb5f7403 100644
--- a/apps/docsite/src/components/TemplatePreviewDialog.tsx
+++ b/apps/docsite/src/components/TemplatePreviewDialog.tsx
@@ -165,7 +165,7 @@ function TemplatePreviewHeader({
const copyButton = (
<HStack gap={2} vAlign="center">
- <Code>{`npx astryx template ${item.slug}`}</Code>
+ <Code>{`npx @astryxdesign/cli template ${item.slug}`}</Code>
<Button
variant="ghost"
isIconOnly
@@ -291,7 +291,7 @@ export function TemplatePreviewDialog({
return null;
}
- const useCommand = `npx astryx template ${current.slug} ./src/app/${current.slug}`;
+ const useCommand = `npx @astryxdesign/cli template ${current.slug} ./src/app/${current.slug}`;
const handleCopyCmd = useCallback(() => {
navigator.clipboard.writeText(useCommand).then(() => {
setCmdCopied(true);
diff --git a/apps/docsite/src/components/ThemePackagePage.tsx b/apps/docsite/src/components/ThemePackagePage.tsx
index a4d7be923e..fdc7c39e6e 100644
--- a/apps/docsite/src/components/ThemePackagePage.tsx
+++ b/apps/docsite/src/components/ThemePackagePage.tsx
@@ -69,9 +69,12 @@ const DEFAULT_THEME_PACKAGE = '@astryxdesign/theme-neutral';
// The CLI command that copies a theme into the consumer's project as
// editable source (see `astryx theme add`). The destination defaults to
-// `src/themes/<slug>/`, so the bare command is copy-paste runnable.
+// `src/themes/<slug>/`. We invoke the scoped package (`@astryxdesign/cli`)
+// rather than the bare `astryx` bin so the copy-paste command works even when
+// the CLI isn't installed yet — bare `npx astryx` would resolve to an
+// unrelated package on the npm registry.
function themeScaffoldCommand(slug: string): string {
- return `npx astryx theme add ${slug}`;
+ return `npx @astryxdesign/cli theme add ${slug}`;
}
// Strip "Theme: " prefix and " Theme" suffix from the registered
diff --git a/apps/sandbox/README.md b/apps/sandbox/README.md
index 1a48231c5b..03d496f7a3 100644
--- a/apps/sandbox/README.md
+++ b/apps/sandbox/README.md
@@ -17,7 +17,7 @@ This automatically generates `AGENTS.md` with the Astryx component index via `as
If `AGENTS.md` is missing, regenerate it:
```bash
-npx astryx init --features agents
+npx @astryxdesign/cli init --features agents
```
## How it works
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 5fcd568e02..2e6fa0e059 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -2,15 +2,19 @@
The CLI is the primary interface for working with the design system, for humans and machines alike. It provides component documentation, design tokens, page templates, theming tools, and upgrade codemods, all accessible via terminal commands, a typed JSON API, or programmatic imports. AI agents and build tools use the same API that powers the CLI, enabling end-to-end frontend development loops.
+Run it one-off with the scoped package (works whether or not it's installed):
+
```bash
-npx astryx --help
-npx astryx search button
-npx astryx component Button
-npx astryx docs tokens
-npx astryx docs migration
-npx astryx template --list
+npx @astryxdesign/cli --help
+npx @astryxdesign/cli search button
+npx @astryxdesign/cli component Button
+npx @astryxdesign/cli docs tokens
+npx @astryxdesign/cli docs migration
+npx @astryxdesign/cli template --list
```
+Once it's a project dependency (`npm install -D @astryxdesign/cli`), drop the scope and use the shorter `astryx` — e.g. `npx astryx component Button` or `pnpm exec astryx component Button`. Bare `astryx` resolves to an unrelated npm package until the CLI is installed, so prefer the scoped form above for first-run/one-off use.
+
## Finding things: `astryx search`
When you don't know whether what you need is a component, a hook, a docs topic,
@@ -20,27 +24,29 @@ fuzzy matching for typos) and tagged with their domain plus the follow-up
command to run:
```bash
-$ npx astryx search button
+$ astryx search button
Results for "button" (20):
[component] Button
Button triggers an action when clicked. Use it for form submissions…
- → npx astryx component Button
+ → astryx component Button
[component] IconButton
A button that shows only an icon with no visible text…
- → npx astryx component IconButton
+ → astryx component IconButton
[hook] useClickableContainer
Makes a container element clickable while preserving nested…
- → npx astryx hook useClickableContainer
+ → astryx hook useClickableContainer
[template] Banner — Collapsible
Combine an action button, dismiss control, and expandable detail area…
- → npx astryx template BannerCollapsibleContent
+ → astryx template BannerCollapsibleContent
```
+(The CLI prints the follow-up commands with your actual runner — `npx astryx …` when installed, or `npx @astryxdesign/cli …` when run one-off.)
+
Options:
- `--type <component|hook|doc|template>`: restrict to a single domain
@@ -415,7 +421,7 @@ failures (warnings are fine) and `1` when any check fails. That makes it
usable directly as a CI step:
```yaml
-- run: npx astryx doctor
+- run: npx @astryxdesign/cli doctor
```
Use `--json` for a structured envelope (`{ apiVersion, type: "doctor",
diff --git a/packages/cli/docs/getting-started.doc.mjs b/packages/cli/docs/getting-started.doc.mjs
index 94b9583bef..a2a494a5a6 100644
--- a/packages/cli/docs/getting-started.doc.mjs
+++ b/packages/cli/docs/getting-started.doc.mjs
@@ -21,7 +21,7 @@ export const docs = {
type: 'code',
lang: 'text',
label: 'Paste this into your AI',
- code: 'Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project. Run `npx astryx init` to set up agent docs. Read the generated files to learn the conventions.',
+ code: 'Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.',
},
],
},
@@ -67,11 +67,11 @@ export const docs = {
},
{
type: 'prose',
- text: 'Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See `npx astryx docs theme` for the full theming guide.',
+ text: 'Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See `astryx docs theme` for the full theming guide.',
},
{
type: 'prose',
- text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in `npx astryx docs migration` before building screens.',
+ text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in `astryx docs migration` before building screens.',
},
],
},
@@ -172,11 +172,11 @@ pnpm dev`,
type: 'code',
lang: 'bash',
label: 'Terminal',
- code: `npx astryx component # list all components
-npx astryx component Button # props, usage, theming for Button
-npx astryx docs # list all doc topics
-npx astryx template --list # available page templates
-npx astryx docs tokens # spacing, color, radius reference`,
+ code: `astryx component # list all components
+astryx component Button # props, usage, theming for Button
+astryx docs # list all doc topics
+astryx template --list # available page templates
+astryx docs tokens # spacing, color, radius reference`,
},
],
},
diff --git a/packages/cli/docs/migration.doc.mjs b/packages/cli/docs/migration.doc.mjs
index c302a63166..dc8cfb3837 100644
--- a/packages/cli/docs/migration.doc.mjs
+++ b/packages/cli/docs/migration.doc.mjs
@@ -54,18 +54,18 @@ export const docs = {
type: 'code',
lang: 'bash',
label: 'Migration-oriented CLI pass',
- code: `npx astryx docs migration
-npx astryx docs theme
-npx astryx docs styling
-npx astryx template --list --type block
-npx astryx template AppShellTopNavWithSideNav --skeleton
-npx astryx template PopoverSettingsPanel --skeleton
-npx astryx component AppShell
-npx astryx component SideNav
-npx astryx component TopNav
-npx astryx component CommandPalette
-npx astryx component Button
-npx astryx component TextInput`,
+ code: `astryx docs migration
+astryx docs theme
+astryx docs styling
+astryx template --list --type block
+astryx template AppShellTopNavWithSideNav --skeleton
+astryx template PopoverSettingsPanel --skeleton
+astryx component AppShell
+astryx component SideNav
+astryx component TopNav
+astryx component CommandPalette
+astryx component Button
+astryx component TextInput`,
},
{
type: 'prose',
@@ -75,8 +75,8 @@ npx astryx component TextInput`,
type: 'code',
lang: 'bash',
label: 'Dense and JSON modes',
- code: `npx astryx docs migration --dense
-npx astryx component Button --json`,
+ code: `astryx docs migration --dense
+astryx component Button --json`,
},
],
},
@@ -371,10 +371,10 @@ if (getComputedStyle(button).paddingInline === '0px') {
code: `We are migrating this existing Tailwind/shadcn app to Astryx incrementally.
First run:
-- npx astryx docs migration --dense
-- npx astryx docs theme --dense
-- npx astryx docs styling --dense
-- npx astryx template AppShellTopNavWithSideNav --skeleton
+- astryx docs migration --dense
+- astryx docs theme --dense
+- astryx docs styling --dense
+- astryx template AppShellTopNavWithSideNav --skeleton
Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with Astryx components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
},
diff --git a/packages/cli/docs/principles.doc.dense.mjs b/packages/cli/docs/principles.doc.dense.mjs
index 95dbd9f2c7..8f93fce3b9 100644
--- a/packages/cli/docs/principles.doc.dense.mjs
+++ b/packages/cli/docs/principles.doc.dense.mjs
@@ -9,6 +9,6 @@ export const docsDense = {
{ section: 'Rules', title: 'Rules', content: [{ type: 'list', items: ['use components', 'frame-first layout: shell + region budgets before content (astryx docs layout)', 'dense data = rows (Table, List/Item) not Cards; Card = widgets/galleries/settings groups', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
{ section: 'Styling Approach', title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout. See astryx docs styling.' }] },
{ section: 'Anti-Patterns', title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'no Card-wrapped list items — frame first, rows for dense data (astryx docs layout)', 'no decorative Badge — StatusDot/Token for status', 'read docs before inventing props'] }] },
- { section: 'Design Tokens', title: 'Tokens', content: [{ type: 'prose', text: 'run npx astryx docs tokens for full reference' }] },
+ { section: 'Design Tokens', title: 'Tokens', content: [{ type: 'prose', text: 'run astryx docs tokens for full reference' }] },
],
};
diff --git a/packages/cli/docs/principles.doc.mjs b/packages/cli/docs/principles.doc.mjs
index 1b20c98e74..7893eccc29 100644
--- a/packages/cli/docs/principles.doc.mjs
+++ b/packages/cli/docs/principles.doc.mjs
@@ -39,10 +39,10 @@ export const docs = {
style: 'ordered',
items: [
'Use components for everything they cover',
- 'Layout is frame-first: pick the shell and budget regions before writing content (see \`npx astryx docs layout\`)',
+ 'Layout is frame-first: pick the shell and budget regions before writing content (see \`astryx docs layout\`)',
'Dense data renders as rows (Table, List/Item), edge-to-edge with dividers; Card is for widgets, galleries, and settings groups',
- 'StyleX or Tailwind for custom styling; both are first-class (see \`npx astryx docs styling\`)',
- 'Semantic tokens, not hardcoded values (see \`npx astryx docs tokens\`)',
+ 'StyleX or Tailwind for custom styling; both are first-class (see \`astryx docs styling\`)',
+ 'Semantic tokens, not hardcoded values (see \`astryx docs tokens\`)',
'CSS custom properties for colors, not hex values',
'Form inputs are controlled (value + onChange)',
'Use useLinkComponent() for navigation so consumers can plug in their framework router via LinkProvider',
@@ -60,7 +60,7 @@ export const docs = {
},
{
type: 'prose',
- text: 'See \`npx astryx docs styling\` for the complete guide with examples.',
+ text: 'See \`astryx docs styling\` for the complete guide with examples.',
},
],
},
@@ -76,7 +76,7 @@ export const docs = {
'Hardcoded colors (#fff). Use var(--color-*) or Tailwind semantic classes (text-primary, bg-surface)',
'Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities',
'Hardcoded <a> elements. Use useLinkComponent() so consumers can swap in their framework router via LinkProvider',
- 'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see \`npx astryx docs layout\`)',
+ 'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see \`astryx docs layout\`)',
'Badge as decoration. Reserve Badge for counts and enumerated states; use StatusDot or Token for status',
'Inventing props. Read component docs first',
],
@@ -89,7 +89,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run \`npx astryx docs tokens\` for the full reference with all values.',
+ text: 'The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run \`astryx docs tokens\` for the full reference with all values.',
},
],
},
diff --git a/packages/cli/docs/principles.doc.zh.mjs b/packages/cli/docs/principles.doc.zh.mjs
index 926b7b719f..40d1b42637 100644
--- a/packages/cli/docs/principles.doc.zh.mjs
+++ b/packages/cli/docs/principles.doc.zh.mjs
@@ -9,6 +9,6 @@ export const docsZh = {
{ section: 'Rules', title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '布局采用框架优先:先选定外壳并规划区域尺寸,再编写内容(见 astryx docs layout)', '密集数据使用行(Table、List/Item)通栏渲染;Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌,不使用硬编码值', '使用 CSS 变量设置颜色,不使用十六进制值', '表单输入为受控组件(value + onChange)', '使用 useLinkComponent() 进行导航'] }] },
{ section: 'Styling Approach', title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。详见 astryx docs styling。' }] },
{ section: 'Anti-Patterns', title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架,密集数据用行渲染(见 astryx docs layout)', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },
- { section: 'Design Tokens', title: '设计令牌', content: [{ type: 'prose', text: '运行 npx astryx docs tokens 查看完整参考' }] },
+ { section: 'Design Tokens', title: '设计令牌', content: [{ type: 'prose', text: '运行 astryx docs tokens 查看完整参考' }] },
],
};
diff --git a/packages/cli/docs/styling-libraries.doc.mjs b/packages/cli/docs/styling-libraries.doc.mjs
index ce78a65912..453109b53d 100644
--- a/packages/cli/docs/styling-libraries.doc.mjs
+++ b/packages/cli/docs/styling-libraries.doc.mjs
@@ -24,7 +24,7 @@ export const docs = {
},
{
type: 'prose',
- text: 'For available token names and values, run `npx astryx docs tokens`. Focused references are also available with `npx astryx docs color`, `npx astryx docs spacing`, `npx astryx docs shape`, `npx astryx docs typography`, `npx astryx docs elevation`, and `npx astryx docs motion`.',
+ text: 'For available token names and values, run `astryx docs tokens`. Focused references are also available with `astryx docs color`, `astryx docs spacing`, `astryx docs shape`, `astryx docs typography`, `astryx docs elevation`, and `astryx docs motion`.',
},
],
},
@@ -452,10 +452,10 @@ function RevenueChart({data}: {data: Array<{x: string; y: number}>}) {
type: 'list',
style: 'ordered',
items: [
- 'Import the reset/base CSS and a theme CSS file early enough for first paint. For production SSR, prefer built themes from `npx astryx theme build` or published `/built` theme imports plus `theme.css`.',
+ 'Import the reset/base CSS and a theme CSS file early enough for first paint. For production SSR, prefer built themes from `astryx theme build` or published `/built` theme imports plus `theme.css`.',
'Choose one owner for color mode. Theme uses `data-theme="light|dark"` and `color-scheme` to resolve `light-dark()` tokens.',
'Map the external library\'s semantic layer to system variables by intent, not by exact naming. For example, MUI `background.paper` maps to `--color-background-surface`.',
- 'Use `npx astryx docs tokens` and focused token docs when building mappings. Keep mappings small at first: text, surface/body/card/popover, border, accent, status, spacing, radius, typography, shadow.',
+ 'Use `astryx docs tokens` and focused token docs when building mappings. Keep mappings small at first: text, surface/body/card/popover, border, accent, status, spacing, radius, typography, shadow.',
'Use token resolver APIs only for non-CSS APIs that need resolved values.',
],
},
diff --git a/packages/cli/docs/styling.doc.mjs b/packages/cli/docs/styling.doc.mjs
index 1e11dd8b4c..924fff47d9 100644
--- a/packages/cli/docs/styling.doc.mjs
+++ b/packages/cli/docs/styling.doc.mjs
@@ -30,7 +30,7 @@ export const docs = {
},
{
type: 'prose',
- text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run `npx astryx docs styling-libraries`; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
+ text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run `astryx docs styling-libraries`; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
},
],
},
@@ -118,7 +118,7 @@ const overrides = stylex.create({
},
{
type: 'prose',
- text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run `npx astryx docs styling-libraries`.',
+ text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run `astryx docs styling-libraries`.',
},
],
},
@@ -263,7 +263,7 @@ const overrides = stylex.create({
},
{
type: 'prose',
- text: 'For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run `npx astryx docs theme` for the full theming guide.',
+ text: 'For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run `astryx docs theme` for the full theming guide.',
},
],
},
@@ -334,7 +334,7 @@ const styles = stylex.create({
},
{
type: 'prose',
- text: 'See `npx astryx docs tokens` for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See `npx astryx docs theme` for how to override tokens via defineTheme.',
+ text: 'See `astryx docs tokens` for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See `astryx docs theme` for how to override tokens via defineTheme.',
},
],
},
diff --git a/packages/cli/docs/theme.doc.dense.mjs b/packages/cli/docs/theme.doc.dense.mjs
index b57da8b12e..05e0d41031 100644
--- a/packages/cli/docs/theme.doc.dense.mjs
+++ b/packages/cli/docs/theme.doc.dense.mjs
@@ -10,9 +10,9 @@ export const docsDense = {
{ section: 'Theme Props', title: 'Props', content: [null] },
{ section: 'Creating a Custom Theme', title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },
{ section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },
- { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `npx astryx component <Name>` for details.' }, null, null, null, null] },
+ { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx component <Name>` for details.' }, null, null, null, null] },
{ section: 'Custom Variants', title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. astryx theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },
- { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'npx astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },
+ { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },
{ section: 'Runtime vs Built Themes', title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },
{ section: 'Light/Dark Mode', title: 'Light/Dark', content: [{ type: 'prose', text: 'light-dark() in token values via [light, dark] tuples. mode=system follows OS.' }, null, null] },
{ section: 'Nesting Themes', title: 'Nesting', content: [{ type: 'prose', text: 'wrap sections in separate <Theme> providers' }, null] },
diff --git a/packages/cli/docs/theme.doc.mjs b/packages/cli/docs/theme.doc.mjs
index 274265a085..6ea12ede2f 100644
--- a/packages/cli/docs/theme.doc.mjs
+++ b/packages/cli/docs/theme.doc.mjs
@@ -148,7 +148,7 @@ function App() {
type: 'code',
lang: 'bash',
label: 'Scaffold with CLI',
- code: 'npx astryx theme',
+ code: 'astryx theme',
},
],
},
@@ -287,7 +287,7 @@ const brandTheme = defineTheme({
},
{
type: 'prose',
- text: 'Run `npx astryx component <Name>` to see a component\'s theming targets, public CSS variables, and which standard CSS properties are supported.',
+ text: 'Run `astryx component <Name>` to see a component\'s theming targets, public CSS variables, and which standard CSS properties are supported.',
},
{
type: 'list',
@@ -361,13 +361,13 @@ const brandTheme = defineTheme({
content: [
{
type: 'prose',
- text: '`npx astryx theme build` compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (Next.js, Remix) where styles must be present on first paint.',
+ text: '`astryx theme build` compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (Next.js, Remix) where styles must be present on first paint.',
},
{
type: 'code',
lang: 'bash',
label: 'Build a theme',
- code: 'npx astryx theme build ./src/themes/ocean.ts',
+ code: 'astryx theme build ./src/themes/ocean.ts',
},
{
type: 'prose',
@@ -432,7 +432,7 @@ import './themes/ocean.css';
[
'Import (custom theme)',
'defineTheme() directly',
- "Built .js + .css from `npx astryx theme build`",
+ "Built .js + .css from `astryx theme build`",
],
[
'How it works',
@@ -462,7 +462,7 @@ import './themes/ocean.css';
items: [
'Use the /built subpath + theme.css for production SSR apps.',
'Use runtime themes during development for fast iteration.',
- 'Run `npx astryx theme build` for custom themes to get the built artifacts.',
+ 'Run `astryx theme build` for custom themes to get the built artifacts.',
],
},
{
@@ -610,7 +610,7 @@ function ChartConfig() {
},
{
type: 'prose',
- text: 'See `npx astryx docs styling-libraries` for styling-library interop and `npx astryx docs tokens` for the full token reference.',
+ text: 'See `astryx docs styling-libraries` for styling-library interop and `astryx docs tokens` for the full token reference.',
},
],
},
diff --git a/packages/cli/docs/theme.doc.zh.mjs b/packages/cli/docs/theme.doc.zh.mjs
index fb1f953882..054e445b5e 100644
--- a/packages/cli/docs/theme.doc.zh.mjs
+++ b/packages/cli/docs/theme.doc.zh.mjs
@@ -10,7 +10,7 @@ export const docsZh = {
{ section: 'Theme Props', title: 'Theme 属性', content: [null] },
{ section: 'Creating a Custom Theme', title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导(推荐)或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },
{ section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置(typography、radius、motion)+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },
- { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'npx astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js(__built:true)+ .d.ts。' }, null, null, null, null] },
+ { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js(__built:true)+ .d.ts。' }, null, null, null, null] },
{ section: 'Runtime vs Built Themes', title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时:useInsertionEffect 在客户端注入样式。构建:静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },
{ section: 'Light/Dark Mode', title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'(默认)跟随系统偏好。" }, null, null] },
{ section: 'Nesting Themes', title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },
diff --git a/packages/cli/docs/tokens.doc.mjs b/packages/cli/docs/tokens.doc.mjs
index 9a89604fbb..19f2000b11 100644
--- a/packages/cli/docs/tokens.doc.mjs
+++ b/packages/cli/docs/tokens.doc.mjs
@@ -1068,7 +1068,7 @@ export const docs = {
},
{
"type": "prose",
- "text": "See `npx astryx docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `npx astryx docs theme` for overriding tokens with defineTheme."
+ "text": "See `astryx docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `astryx docs theme` for overriding tokens with defineTheme."
}
]
}
diff --git a/packages/cli/docs/working-with-ai.doc.mjs b/packages/cli/docs/working-with-ai.doc.mjs
index e83e3e4738..3d8f2c6d25 100644
--- a/packages/cli/docs/working-with-ai.doc.mjs
+++ b/packages/cli/docs/working-with-ai.doc.mjs
@@ -34,7 +34,7 @@ export const docs = {
type: 'code',
lang: 'text',
label: 'Paste this into your AI',
- code: 'Install @astryxdesign/cli and run `npx astryx init --features agents` to set up your Astryx context. Read the generated file.',
+ code: 'Install @astryxdesign/cli and run `npx @astryxdesign/cli init --features agents` to set up your Astryx context. Read the generated file.',
},
{
type: 'prose',
@@ -48,9 +48,9 @@ export const docs = {
type: 'code',
lang: 'bash',
label: 'Manual options',
- code: `npx astryx init --features agents --agent claude # CLAUDE.md
-npx astryx init --features agents --agent cursor # .cursorrules
-npx astryx init --features agents --agent codex # AGENTS.md (Copilot, Codex, etc.)`,
+ code: `npx @astryxdesign/cli init --features agents --agent claude # CLAUDE.md
+npx @astryxdesign/cli init --features agents --agent cursor # .cursorrules
+npx @astryxdesign/cli init --features agents --agent codex # AGENTS.md (Copilot, Codex, etc.)`,
},
],
},
@@ -65,9 +65,9 @@ npx astryx init --features agents --agent codex # AGENTS.md (Copilot, Codex,
type: 'list',
style: 'ordered',
items: [
- '`npx astryx template --list`: find a related page pattern to use as reference',
- '`npx astryx template <name> --skeleton`: study the layout structure',
- '`npx astryx component <Name>`: read props and examples for every component used',
+ '`astryx template --list`: find a related page pattern to use as reference',
+ '`astryx template <name> --skeleton`: study the layout structure',
+ '`astryx component <Name>`: read props and examples for every component used',
],
},
{
@@ -88,7 +88,7 @@ npx astryx init --features agents --agent codex # AGENTS.md (Copilot, Codex,
lang: 'bash',
label: 'Install as a Cursor user rule',
code: `mkdir -p ~/.cursor/rules
-npx astryx init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
+npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
},
],
},
@@ -109,12 +109,12 @@ npx astryx init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
2. How do you make an Dialog non-dismissible?
3. What prop does Selector use for its items?
-If you don't know all three, run \`npx astryx init --features agents\` to generate agent docs, then read the generated file.`,
+If you don't know all three, run \`npx @astryxdesign/cli init --features agents\` to generate agent docs, then read the generated file.`,
},
],
},
{
- title: 'The npx astryx Pattern',
+ title: 'The astryx Pattern',
content: [
{
type: 'prose',
@@ -130,16 +130,16 @@ If you don't know all three, run \`npx astryx init --features agents\` to genera
},
{
type: 'prose',
- text: 'With this alias, agents use `npx astryx component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
+ text: 'With this alias, agents use `astryx 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: `npx astryx component --list
-npx astryx component Dialog --dense
-npx astryx docs styling --dense
-npx astryx docs tokens --dense`,
+ code: `astryx component --list
+astryx component Dialog --dense
+astryx docs styling --dense
+astryx docs tokens --dense`,
},
],
},
@@ -154,9 +154,9 @@ npx astryx docs tokens --dense`,
type: 'code',
lang: 'bash',
label: 'Dense output for pasting into AI conversations',
- code: `npx astryx component Dialog --dense
-npx astryx docs styling --dense
-npx astryx docs tokens --dense`,
+ code: `astryx component Dialog --dense
+astryx docs styling --dense
+astryx docs tokens --dense`,
},
],
},
diff --git a/packages/cli/src/api/doctor.mjs b/packages/cli/src/api/doctor.mjs
index 10df4eb1ae..adc94ec156 100644
--- a/packages/cli/src/api/doctor.mjs
+++ b/packages/cli/src/api/doctor.mjs
@@ -26,7 +26,7 @@ import {createRequire} from 'node:module';
import {MIN_NODE_VERSION, isNodeVersionSupported} from '../lib/node-version.mjs';
import {CLI_ROOT, findCoreDir} from '../utils/paths.mjs';
-import {detectPackageManager} from '../utils/package-manager.mjs';
+import {detectPackageManager, getCliInvocation} from '../utils/package-manager.mjs';
import {findConfigPath, Project} from '../lib/project.mjs';
import {semverCompare} from '../utils/semver.mjs';
@@ -343,7 +343,7 @@ export function checkAgentDocs(ctx) {
label: 'AI agent docs',
status: 'info',
message: 'No agent docs (CLAUDE.md / AGENTS.md / .cursorrules) found.',
- fix: 'Generate agent docs with `astryx init --features agents`.',
+ fix: `Generate agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
};
}
@@ -365,7 +365,7 @@ export function checkAgentDocs(ctx) {
label: 'AI agent docs',
status: 'warn',
message: `Agent docs present (${present.join(', ')}) but no Astryx section markers found.`,
- fix: 'Add the Astryx section to your agent docs with `astryx init --features agents`.',
+ fix: `Add the Astryx section to your agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
};
}
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjs
index b1dc97745b..5535efcc2e 100644
--- a/packages/cli/src/commands/agent-docs.mjs
+++ b/packages/cli/src/commands/agent-docs.mjs
@@ -22,7 +22,7 @@ import * as fs from 'node:fs';
import * as path from 'node:path';
import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';
import {assertWithin, PathSafetyError} from '../utils/path-safety.mjs';
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
import {discoverComponents} from '../lib/component-discovery.mjs';
import {humanLog} from '../lib/json.mjs';
import {cliError} from '../lib/cli-error.mjs';
@@ -144,8 +144,8 @@ export function detectStylingSystem(targetDir) {
* configured (see {@link detectStylingSystem}) so the agent never reaches for a
* styling path that isn't compiled here.
*/
-export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPrefix(), stylingSystem = 'css'} = {}) {
- const run = `${runPrefix} astryx`;
+export function generateCompressedIndex(version, {coreDir, invocation = getCliInvocation(), stylingSystem = 'css'} = {}) {
+ const run = invocation;
const lines = [MARKER_START];
// Component count from live discovery
@@ -410,9 +410,9 @@ export function removeAgentDocs(targetDir) {
export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onlyReplace = false} = {}) {
const coreDir = findCoreDir(targetDir);
const version = getXdsVersion(coreDir);
- const runPrefix = getRunPrefix(targetDir);
+ const invocation = getCliInvocation(targetDir);
const stylingSystem = detectStylingSystem(targetDir);
- const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, runPrefix, stylingSystem});
+ const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, invocation, stylingSystem});
const written = [];
// Explicit paths override everything
@@ -538,8 +538,7 @@ export function registerAgentDocs(program) {
throw err;
}
- const runPrefix = getRunPrefix(targetDir);
- const run = `${runPrefix} astryx`;
+ const run = getCliInvocation(targetDir);
for (const t of targets) {
humanLog(`✓ ${t}`);
diff --git a/packages/cli/src/commands/agent-docs.test.mjs b/packages/cli/src/commands/agent-docs.test.mjs
index 56e79317e8..beb2543fcf 100644
--- a/packages/cli/src/commands/agent-docs.test.mjs
+++ b/packages/cli/src/commands/agent-docs.test.mjs
@@ -88,17 +88,24 @@ describe('generateCompressedIndex', () => {
expect(result).toMatch(/after any @astryxdesign\/core bump/);
});
- it('states the runPrefix once in the CLI header', () => {
- const result = generateCompressedIndex('1.0.0', {runPrefix: 'yarn'});
+ it('states the invocation once in the CLI header (yarn)', () => {
+ const result = generateCompressedIndex('1.0.0', {invocation: 'yarn astryx'});
expect(result).toContain('yarn astryx <cmd>');
expect(result).not.toContain('npx astryx');
});
- it('uses pnpm exec prefix', () => {
- const result = generateCompressedIndex('1.0.0', {runPrefix: 'pnpm exec'});
+ it('uses the pnpm exec invocation', () => {
+ const result = generateCompressedIndex('1.0.0', {invocation: 'pnpm exec astryx'});
expect(result).toContain('pnpm exec astryx <cmd>');
expect(result).not.toContain('npx astryx');
});
+
+ it('uses the scoped package for one-off (uninstalled) runs so agents never hit the bare name', () => {
+ const result = generateCompressedIndex('1.0.0', {invocation: 'npx @astryxdesign/cli'});
+ expect(result).toContain('npx @astryxdesign/cli <cmd>');
+ // The header defines the mapping; the bare "run every command as `npx astryx`" footgun must be absent.
+ expect(result).not.toContain('npx astryx <cmd>');
+ });
});
describe('detectStylingSystem', () => {
diff --git a/packages/cli/src/commands/build-theme.mjs b/packages/cli/src/commands/build-theme.mjs
index 6d464db34a..90a583cfbc 100644
--- a/packages/cli/src/commands/build-theme.mjs
+++ b/packages/cli/src/commands/build-theme.mjs
@@ -8,8 +8,8 @@
* - An updated JS module that references the built className
*
* Usage:
- * npx astryx theme build ./src/themes/ocean.ts
- * npx astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css
+ * astryx theme build ./src/themes/ocean.ts
+ * astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css
*/
import * as fs from 'node:fs';
@@ -17,7 +17,7 @@ import * as path from 'node:path';
import {pathToFileURL, fileURLToPath} from 'node:url';
import {spawn} from 'node:child_process';
import {createJiti} from 'jiti';
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
import {
sanitizeName,
PathSafetyError,
@@ -499,7 +499,7 @@ function generateBuiltModule(themeDef, iconInfo) {
.join('\n');
return `${iconImport}/**
- * ${themeDef.name} theme — built by \`${getRunPrefix()} astryx theme build\`
+ * ${themeDef.name} theme — built by \`${getCliInvocation()} theme build\`
* Import the CSS file alongside this module:
*
* import { ${toIdentifier(themeDef.name)}Theme } from './${themeDef.name}';
@@ -1129,7 +1129,7 @@ Or with a <link> tag:
if (t.description) humanLog(` ${t.description}`);
}
humanLog('\nUsage:');
- humanLog(' astryx theme add <slug> [target-path] Scaffold a theme file you own\n');
+ humanLog(` ${getCliInvocation()} theme add <slug> [target-path] Scaffold a theme file you own\n`);
});
theme
@@ -1167,7 +1167,7 @@ Or with a <link> tag:
if (t.description) humanLog(` ${t.description}`);
}
humanLog('\nUsage:');
- humanLog(' astryx theme add <slug> [target-path] Scaffold a theme file you own\n');
+ humanLog(` ${getCliInvocation()} theme add <slug> [target-path] Scaffold a theme file you own\n`);
return;
}
diff --git a/packages/cli/src/commands/build.mjs b/packages/cli/src/commands/build.mjs
index 89259ff910..e83753e889 100644
--- a/packages/cli/src/commands/build.mjs
+++ b/packages/cli/src/commands/build.mjs
@@ -15,7 +15,7 @@
* the whole CLI, use `astryx search <query>` instead.
*/
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation, formatCliCommand} from '../utils/package-manager.mjs';
import {jsonOut, humanLog} from '../lib/json.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {search as searchApi} from '../api/search.mjs';
@@ -47,25 +47,25 @@ function printPlaybook(run) {
'How to build a page with Astryx',
'',
"1. Find a starting point for what you're building:",
- ` ${run} astryx build "<what you're building>"`,
+ ` ${run} build "<what you're building>"`,
' → returns the closest [page] template, the [block]s that cover parts,',
' and the [component]s to fill the gaps, with a "Compose:" suggestion.',
'',
'2. If a [page] template matches → scaffold it and adapt:',
- ` ${run} astryx template <name> [path]`,
+ ` ${run} template <name> [path]`,
'',
'3. If nothing matches exactly → compose:',
- ` ${run} astryx template <name> --skeleton # study a close page's layout`,
- ` ${run} astryx template <BlockName> # drop in each block from the kit`,
- ` ${run} astryx component <Name> # fill remaining gaps (read props)`,
+ ` ${run} template <name> --skeleton # study a close page's layout`,
+ ` ${run} template <BlockName> # drop in each block from the kit`,
+ ` ${run} component <Name> # fill remaining gaps (read props)`,
'',
'4. Rules (keep it on-system):',
' - No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.',
- ' - No style={{}} — use component props; design tokens via `astryx docs tokens`.',
+ ` - No style={{}} — use component props; design tokens via \`${run} docs tokens\`.`,
' - Wrap the app in <Theme theme={...}> and import core reset.css + astryx.css.',
'',
- `Tip: \`${run} astryx build "<idea>"\` is the fastest way in. For a neutral`,
- `lookup of any component/doc/template, use \`${run} astryx search <query>\`.`,
+ `Tip: \`${run} build "<idea>"\` is the fastest way in. For a neutral`,
+ `lookup of any component/doc/template, use \`${run} search <query>\`.`,
'',
];
for (const l of lines) humanLog(l);
@@ -79,7 +79,7 @@ export function registerBuild(program) {
.option('--limit <n>', 'Max candidates to draw from (default 60)')
.option('--detail', 'Verbose output (include import paths and match reason)')
.action(async (query, options) => {
- const run = getRunPrefix();
+ const run = getCliInvocation();
const json = program.opts().json || false;
// No query → print the playbook (the "how to build" skill).
@@ -115,7 +115,7 @@ export function registerBuild(program) {
if (results.length === 0) {
humanLog('');
humanLog(`No matches for "${q}".`);
- humanLog(`Try a broader term, or browse: ${run} astryx component --list`);
+ humanLog(`Try a broader term, or browse: ${run} component --list`);
humanLog('');
return;
}
@@ -138,7 +138,7 @@ export function registerBuild(program) {
humanLog('');
humanLog(` [${label}] ${display}`);
if (r.description) humanLog(` ${r.description}`);
- humanLog(` → ${run} ${r.command}`);
+ humanLog(` → ${formatCliCommand(r.command)}`);
if (options.detail) {
if (r.import) humanLog(` import: ${r.import}`);
humanLog(` match: ${r.reason} (score ${r.score})`);
@@ -151,9 +151,9 @@ export function registerBuild(program) {
// START — the single recommended path.
humanLog('');
if (directMatch) {
- humanLog(`START → Scaffold the \`${pages[0].name}\` page template, then adapt: ${run} astryx template ${pages[0].name} ./src/App.tsx`);
+ humanLog(`START → Scaffold the \`${pages[0].name}\` page template, then adapt: ${run} template ${pages[0].name} ./src/App.tsx`);
} else if (pages.length) {
- humanLog(`START → No exact page template. Use \`${pages[0].name}\` as a layout reference (${run} astryx template ${pages[0].name} --skeleton) and compose the pieces below.`);
+ humanLog(`START → No exact page template. Use \`${pages[0].name}\` as a layout reference (${run} template ${pages[0].name} --skeleton) and compose the pieces below.`);
} else {
humanLog(`START → No page template fits. Frame with AppShell and compose the blocks + components below.`);
}
@@ -168,7 +168,7 @@ export function registerBuild(program) {
// FRAME — always (the page shell).
humanLog('');
humanLog(`FRAME — page shell (always): ${FRAME.join(', ')}`);
- humanLog(` full-page → AppShell; or Layout + SideNav/TopNav. ${run} astryx component AppShell`);
+ humanLog(` full-page → AppShell; or Layout + SideNav/TopNav. ${run} component AppShell`);
// BLOCKS — idea-specific composed patterns.
if (blocks.length) {
diff --git a/packages/cli/src/commands/component/index.mjs b/packages/cli/src/commands/component/index.mjs
index 4b9ecc7640..f8e1c94b9d 100644
--- a/packages/cli/src/commands/component/index.mjs
+++ b/packages/cli/src/commands/component/index.mjs
@@ -18,7 +18,7 @@ import {
formatBriefAll,
} from '../../lib/component-format.mjs';
import {resolveTheme} from '../../lib/resolve-theme.mjs';
-import {getRunPrefix} from '../../utils/package-manager.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
import {jsonOut, humanLog} from '../../lib/json.mjs';
import {cliError} from '../../lib/cli-error.mjs';
import {ERROR_CODES} from '../../lib/error-codes.mjs';
@@ -39,7 +39,7 @@ export function registerComponent(program) {
.option('--blocks', 'List example blocks: showcase, examples, and related')
.option('--package <name>', 'Scope lookup to an external package (e.g. @acme/xds-widgets)')
.action(async (name, options) => {
- const run = getRunPrefix();
+ const run = getCliInvocation();
const zh = program.opts().zh || false;
const dense = program.opts().dense || false;
const lang = program.opts().lang || null;
@@ -142,7 +142,7 @@ export function registerComponent(program) {
}
humanLog('');
humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
- humanLog(`Usage: ${run} astryx component <name>`);
+ humanLog(`Usage: ${run} component <name>`);
humanLog('');
}
break;
@@ -165,7 +165,7 @@ export function registerComponent(program) {
humanLog('');
}
humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
- humanLog(`Usage: ${run} astryx component <name>`);
+ humanLog(`Usage: ${run} component <name>`);
humanLog('');
break;
}
diff --git a/packages/cli/src/commands/discover.mjs b/packages/cli/src/commands/discover.mjs
index 21451079a5..62e27a554a 100644
--- a/packages/cli/src/commands/discover.mjs
+++ b/packages/cli/src/commands/discover.mjs
@@ -14,6 +14,7 @@ import {formatFull, formatBrief, formatCompact} from '../lib/component-format.mj
import {jsonOut, humanLog} from '../lib/json.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {discover as discoverApi} from '../api/discover.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
export function registerDiscover(program) {
program
@@ -25,6 +26,7 @@ export function registerDiscover(program) {
const json = program.opts().json || false;
const lang = program.opts().lang || null;
const zh = program.opts().zh || false;
+ const run = getCliInvocation();
let result;
try {
@@ -80,9 +82,9 @@ export function registerDiscover(program) {
humanLog('');
}
humanLog('Usage:');
- humanLog(' astryx discover <package> Browse a package');
- humanLog(' astryx discover <package>/Component View component docs');
- humanLog(' astryx discover <search> Search all packages');
+ humanLog(` ${run} discover <package> Browse a package`);
+ humanLog(` ${run} discover <package>/Component View component docs`);
+ humanLog(` ${run} discover <search> Search all packages`);
humanLog('');
}
break;
@@ -99,7 +101,7 @@ export function registerDiscover(program) {
humanLog('');
for (const comp of result.data.components) humanLog(' ' + comp);
humanLog('');
- humanLog('Usage: astryx discover ' + result.data.name + '/<ComponentName>');
+ humanLog(`Usage: ${run} discover ` + result.data.name + '/<ComponentName>');
humanLog('');
break;
}
@@ -122,7 +124,7 @@ export function registerDiscover(program) {
humanLog('Found ' + result.data.matches.length + ' matches for "' + result.data.query + '":');
humanLog('');
for (const m of result.data.matches) {
- humanLog(' astryx discover ' + m.package + '/' + m.component);
+ humanLog(` ${run} discover ` + m.package + '/' + m.component);
}
humanLog('');
break;
diff --git a/packages/cli/src/commands/docs.mjs b/packages/cli/src/commands/docs.mjs
index ba2326400d..85c5b1b348 100644
--- a/packages/cli/src/commands/docs.mjs
+++ b/packages/cli/src/commands/docs.mjs
@@ -12,7 +12,7 @@
* astryx docs <topic> <section> Print one section
*/
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
import {jsonOut, humanLog} from '../lib/json.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {docs as docsApi} from '../api/docs.mjs';
@@ -105,7 +105,7 @@ export function registerDocs(program) {
.command('docs [topic] [section]')
.description('Print reference docs')
.action(async (topic, section) => {
- const run = getRunPrefix();
+ const run = getCliInvocation();
const lang = program.opts().lang || null;
const zh = program.opts().zh || false;
const dense = program.opts().dense || false;
@@ -130,8 +130,8 @@ export function registerDocs(program) {
for (const entry of result.data) {
humanLog(` ${entry.topic.padEnd(14)} ${entry.description}`);
}
- humanLog(`\nUsage: ${run} astryx docs <topic>`);
- humanLog(` ${run} astryx docs <topic> <section>\n`);
+ humanLog(`\nUsage: ${run} docs <topic>`);
+ humanLog(` ${run} docs <topic> <section>\n`);
break;
}
diff --git a/packages/cli/src/commands/hook/index.mjs b/packages/cli/src/commands/hook/index.mjs
index e9968b695e..84afb60b3c 100644
--- a/packages/cli/src/commands/hook/index.mjs
+++ b/packages/cli/src/commands/hook/index.mjs
@@ -12,7 +12,7 @@ import {
formatHookBrief,
formatHookParams,
} from '../../lib/hook-format.mjs';
-import {getRunPrefix} from '../../utils/package-manager.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
import {jsonOut, humanLog} from '../../lib/json.mjs';
import {cliError} from '../../lib/cli-error.mjs';
import {ERROR_CODES} from '../../lib/error-codes.mjs';
@@ -27,7 +27,7 @@ export function registerHook(program) {
.option('--category <category>', 'List hooks in a specific category')
.option('--params', 'Print only the parameters table')
.action(async (name, options) => {
- const run = getRunPrefix();
+ const run = getCliInvocation();
const zh = program.opts().zh || false;
const lang = program.opts().lang || null;
const detailSource = program.getOptionValueSource('detail');
@@ -76,7 +76,7 @@ export function registerHook(program) {
for (const h of hookNames) humanLog(` ${h}`);
}
humanLog('');
- humanLog(`Usage: ${run} astryx hook <name>`);
+ humanLog(`Usage: ${run} hook <name>`);
humanLog('');
}
break;
@@ -93,7 +93,7 @@ export function registerHook(program) {
}
humanLog('');
}
- humanLog(`Usage: ${run} astryx hook <name>`);
+ humanLog(`Usage: ${run} hook <name>`);
humanLog('');
break;
}
diff --git a/packages/cli/src/commands/init.mjs b/packages/cli/src/commands/init.mjs
index 1f9e241573..786a55c3d3 100644
--- a/packages/cli/src/commands/init.mjs
+++ b/packages/cli/src/commands/init.mjs
@@ -19,7 +19,7 @@ import * as path from 'node:path';
import * as fs from 'node:fs';
import {CLI_ROOT} from '../utils/paths.mjs';
import {PathSafetyError} from '../utils/path-safety.mjs';
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
import {installAgentDocs, removeAgentDocs} from './agent-docs.mjs';
import {listTemplates} from './template.mjs';
import {humanLog} from '../lib/json.mjs';
@@ -27,7 +27,7 @@ import {cliError} from '../lib/cli-error.mjs';
import {ERROR_CODES} from '../lib/error-codes.mjs';
const VALID_FEATURES = ['agents', 'theme', 'template'];
-const run = getRunPrefix();
+const run = getCliInvocation();
/**
* Build the "Next steps" lines printed at the end of `astryx init`.
@@ -40,10 +40,10 @@ const run = getRunPrefix();
*
* Exported for testing.
*
- * @param {string} runPrefix package-manager run prefix (e.g. `npx`)
+ * @param {string} invocation install-aware CLI invocation stem (e.g. `npx astryx`, `pnpm exec astryx`, or `npx @astryxdesign/cli` for one-off runs)
* @returns {string[]} ordered list of human-facing lines
*/
-export function getNextSteps(runPrefix) {
+export function getNextSteps(invocation) {
return [
'',
' Next steps:',
@@ -54,8 +54,8 @@ export function getNextSteps(runPrefix) {
" import { neutralTheme } from '@astryxdesign/theme-neutral/built'",
" import '@astryxdesign/theme-neutral/theme.css'",
' <Theme theme={neutralTheme}>...</Theme>',
- ` For custom themes, run \`${runPrefix} astryx theme build <file>\` to generate the built artifacts.`,
- ` 4. ${runPrefix} astryx --help for all commands`,
+ ` For custom themes, run \`${invocation} theme build <file>\` to generate the built artifacts.`,
+ ` 4. ${invocation} --help for all commands`,
'',
];
}
@@ -81,14 +81,14 @@ function runAgents(targetDir, {agent, agentDocsPath} = {}) {
process.exitCode = 1;
return;
}
- console.error(`Could not install agent docs. Try again with \`${run} astryx init --features agents\`.`);
+ console.error(`Could not install agent docs. Try again with \`${run} init --features agents\`.`);
}
}
// ─── Feature: theme ──────────────────────────────────────────────────────────
function runTheme() {
- humanLog(`✓ For a custom theme, run \`${run} astryx theme\` (browse) or \`${run} astryx theme add <slug>\` (scaffold).`);
+ humanLog(`✓ For a custom theme, run \`${run} theme\` (browse) or \`${run} theme add <slug>\` (scaffold).`);
}
// ─── Feature: template ───────────────────────────────────────────────────────
@@ -103,9 +103,9 @@ function runTemplate(targetDir, {templateName} = {}) {
// and `build` with no args is the full how-to-build playbook.
humanLog('✓ To build UI, use these commands:');
humanLog('');
- humanLog(` ${run} astryx build "<what you're building>" build a page — kit: closest template + blocks + components`);
- humanLog(` ${run} astryx build the how-to-build workflow (read this first)`);
- humanLog(` ${run} astryx search <query> find anything — components, docs, templates, blocks`);
+ humanLog(` ${run} build "<what you're building>" build a page — kit: closest template + blocks + components`);
+ humanLog(` ${run} build the how-to-build workflow (read this first)`);
+ humanLog(` ${run} search <query> find anything — components, docs, templates, blocks`);
humanLog('');
return;
}
@@ -175,7 +175,7 @@ export function registerInit(program) {
agentDocsPath: options.agentDocsPath,
});
humanLog('');
- humanLog(` Tip: \`${run} astryx init --all\` also points you to the theme and page-building workflows.`);
+ humanLog(` Tip: \`${run} init --all\` also points you to the theme and page-building workflows.`);
for (const line of getNextSteps(run)) {
humanLog(line);
diff --git a/packages/cli/src/commands/init.next-steps.test.mjs b/packages/cli/src/commands/init.next-steps.test.mjs
index c84b96ebe9..72ef640cac 100644
--- a/packages/cli/src/commands/init.next-steps.test.mjs
+++ b/packages/cli/src/commands/init.next-steps.test.mjs
@@ -23,7 +23,7 @@ import {describe, it, expect} from 'vitest';
import {getNextSteps} from './init.mjs';
describe('init Next steps theme guidance', () => {
- const text = getNextSteps('npx').join('\n');
+ const text = getNextSteps('npx astryx').join('\n');
it('mentions the base CSS imports so the app is not left unstyled', () => {
expect(text).toContain("'@astryxdesign/core/reset.css'");
diff --git a/packages/cli/src/commands/search.mjs b/packages/cli/src/commands/search.mjs
index 19b0aa8599..245b03a8ab 100644
--- a/packages/cli/src/commands/search.mjs
+++ b/packages/cli/src/commands/search.mjs
@@ -16,7 +16,7 @@
* astryx search button --json Typed JSON envelope
*/
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation, formatCliCommand} from '../utils/package-manager.mjs';
import {jsonOut, humanLog} from '../lib/json.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {search as searchApi, SEARCH_DOMAINS} from '../api/search.mjs';
@@ -63,7 +63,7 @@ export function registerSearch(program) {
if (json) return jsonOut(result.type, result.data);
// ── Text output ──────────────────────────────────────────────
- const run = getRunPrefix();
+ const run = getCliInvocation();
const {query: q, results} = result.data;
// No matches is a valid, successful outcome — clean message, exit 0.
@@ -71,7 +71,7 @@ export function registerSearch(program) {
humanLog('');
humanLog(`No results for "${q}".`);
humanLog('');
- humanLog(`Try a broader term, or browse: ${run} astryx component --list`);
+ humanLog(`Try a broader term, or browse: ${run} component --list`);
humanLog('');
return;
}
@@ -86,7 +86,7 @@ export function registerSearch(program) {
if (r.description) {
humanLog(` ${r.description}`);
}
- humanLog(` → ${run} ${r.command}`);
+ humanLog(` → ${formatCliCommand(r.command)}`);
if (options.detail) {
if (r.import) humanLog(` import: ${r.import}`);
humanLog(` match: ${r.reason} (score ${r.score})`);
diff --git a/packages/cli/src/commands/swizzle.mjs b/packages/cli/src/commands/swizzle.mjs
index 490514d5c1..c0aa6ff326 100644
--- a/packages/cli/src/commands/swizzle.mjs
+++ b/packages/cli/src/commands/swizzle.mjs
@@ -24,7 +24,7 @@ import {jsonOut, humanLog} from '../lib/json.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {ERROR_CODES} from '../lib/error-codes.mjs';
import {checkGhCli} from '../utils/github.mjs';
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
import {Project} from '../lib/project.mjs';
import {
CORE_PACKAGE,
@@ -180,6 +180,7 @@ export function registerSwizzle(program) {
.action(async (component, options) => {
const coreDir = findCoreDir(process.cwd());
const json = program.opts().json || false;
+ const run = getCliInvocation();
if (!coreDir) {
cliError(
@@ -197,10 +198,10 @@ export function registerSwizzle(program) {
for (const name of components) {
humanLog(` ${name}`);
}
- humanLog(`\nUsage: astryx swizzle <component>\n`);
- humanLog('Example: astryx swizzle Button');
+ humanLog(`\nUsage: ${run} swizzle <component>\n`);
+ humanLog(`Example: ${run} swizzle Button`);
humanLog(
- ' astryx swizzle XDSButton (XDS prefix also works)\n',
+ ` ${run} swizzle XDSButton (XDS prefix also works)\n`,
);
return;
}
@@ -387,7 +388,7 @@ export function registerSwizzle(program) {
humanLog(
' Without one they render unstyled (no error). See setup per framework:',
);
- humanLog(` ${getRunPrefix()} astryx docs styling`);
+ humanLog(` ${run} docs styling`);
humanLog(
' Next.js note: the StyleX Babel plugin disables SWC and breaks next/font —',
);
diff --git a/packages/cli/src/commands/template.mjs b/packages/cli/src/commands/template.mjs
index e591116bf5..0ced4472ed 100644
--- a/packages/cli/src/commands/template.mjs
+++ b/packages/cli/src/commands/template.mjs
@@ -12,6 +12,7 @@ import {ERROR_CODES} from '../lib/error-codes.mjs';
import {template as templateApi} from '../api/template.mjs';
import {Project} from '../lib/project.mjs';
import {warnOnIntegrationIssues} from '../lib/integration-warnings.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
export {discoverTemplates, listTemplates} from '../api/template.mjs';
@@ -26,6 +27,7 @@ export function registerTemplate(program) {
.option('-f, --overwrite', 'Overwrite existing files without prompting')
.action(async (name, targetPath, options) => {
const json = program.opts().json || false;
+ const run = getCliInvocation();
// Non-blocking nudge: if any configured integration has validation
// issues, print one compact line to stderr pointing at
@@ -98,10 +100,10 @@ export function registerTemplate(program) {
for (const t of blocks) renderEntry(t);
}
humanLog('\nUsage:');
- humanLog(' astryx template <id> [target-path] Scaffold page or block');
- humanLog(' astryx template <id> --skeleton Layout reference');
- humanLog(' astryx template --list --type block List only blocks');
- humanLog(' astryx template --list --package <pkg> List from one package\n');
+ humanLog(` ${run} template <id> [target-path] Scaffold page or block`);
+ humanLog(` ${run} template <id> --skeleton Layout reference`);
+ humanLog(` ${run} template --list --type block List only blocks`);
+ humanLog(` ${run} template --list --package <pkg> List from one package\n`);
break;
}
diff --git a/packages/cli/src/commands/upgrade.mjs b/packages/cli/src/commands/upgrade.mjs
index c7e4b19f86..2213adc5ef 100644
--- a/packages/cli/src/commands/upgrade.mjs
+++ b/packages/cli/src/commands/upgrade.mjs
@@ -47,7 +47,7 @@ import {
} from '../codemods/integration-discovery.mjs';
import {runIntegrationCodemods} from '../codemods/integration-runner.mjs';
import {installAgentDocs, discoverAgentDocs} from './agent-docs.mjs';
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation, formatCliCommand} from '../utils/package-manager.mjs';
import {isValidSemver, semverGte} from '../utils/semver.mjs';
import {jsonOut, jsonError} from '../lib/json.mjs';
import {Project} from '../lib/project.mjs';
@@ -176,7 +176,7 @@ export function registerUpgrade(program) {
if (!options.list && !options.from) {
const msg =
- 'Missing required --from. Install the target version first, then run `astryx upgrade --from <old-version>`.';
+ `Missing required --from. Install the target version first, then run \`${getCliInvocation()} upgrade --from <old-version>\`.`;
if (json)
return jsonError(msg, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);
p.log.error(msg);
@@ -237,7 +237,7 @@ export function registerUpgrade(program) {
const installed = detectInstalledTargetVersion();
if (!installed) {
const msg =
- 'Could not find installed @astryxdesign/core (or legacy @xds/core). Install the target version first, then rerun `astryx upgrade --from <old-version>`.';
+ `Could not find installed @astryxdesign/core (or legacy @xds/core). Install the target version first, then rerun \`${getCliInvocation()} upgrade --from <old-version>\`.`;
if (json)
return jsonError(msg, undefined, ERROR_CODES.ERR_VERSION_DETECT);
p.log.error(msg);
@@ -390,6 +390,9 @@ export function registerUpgrade(program) {
const codemodFlags = coreConfigCodemodNames
.map(name => `--codemod ${name}`)
.join(' ');
+ // Canonical (bare) form — this is a structured, machine-executable
+ // field in the --json envelope. The human print below is made
+ // install-aware via formatCliCommand.
const suggestedCommand = `astryx upgrade --from ${currentVersion} ${codemodFlags} --apply`;
const guidance =
'Your astryx.config currently fails strict validation, but a pending ' +
@@ -409,7 +412,7 @@ export function registerUpgrade(program) {
});
}
p.log.warn(guidance);
- p.log.info(` ${suggestedCommand}`);
+ p.log.info(` ${formatCliCommand(suggestedCommand)}`);
p.log.info(
'Integrations are skipped in this preview; they will be processed on the --apply run.',
);
@@ -619,7 +622,7 @@ export function registerUpgrade(program) {
} catch {
if (!json) {
p.log.warn(
- `Could not update agent docs. Run \`${getRunPrefix()} astryx init --features agents\` to update manually.`,
+ `Could not update agent docs. Run \`${getCliInvocation()} init --features agents\` to update manually.`,
);
}
}
diff --git a/packages/cli/src/index.mjs b/packages/cli/src/index.mjs
index 9151fc4ceb..7b7d5a7e69 100644
--- a/packages/cli/src/index.mjs
+++ b/packages/cli/src/index.mjs
@@ -12,7 +12,7 @@ import {fileURLToPath} from 'node:url';
import * as fs from 'node:fs';
import * as path from 'node:path';
import {checkForUpdate} from './utils/update-check.mjs';
-import {getRunPrefix} from './utils/package-manager.mjs';
+import {getCliInvocation} from './utils/package-manager.mjs';
import {API_VERSION, setJsonMode} from './lib/json.mjs';
import {buildManifest} from './lib/manifest.mjs';
import {cliError} from './lib/cli-error.mjs';
@@ -305,15 +305,14 @@ program
console.log(` ${c.name}${tag}`);
if (c.description) console.log(` ${c.description}`);
}
- console.log(`\nRun \`astryx manifest --json\` for the full structured manifest.\n`);
+ console.log(`\nRun \`${getCliInvocation()} manifest --json\` for the full structured manifest.\n`);
});
// Hidden command used by package.json postinstall scripts
program
.command('postinstall', {hidden: true})
.action(() => {
- const run = getRunPrefix();
- const r = `${run} xds`;
+ const r = getCliInvocation();
const pad = (s, len) => s + ' '.repeat(Math.max(0, len - s.length));
const W = 49; // inner width of the box
const line = (s) => ` │ ${pad(s, W)}│`;
diff --git a/packages/cli/src/lib/component-format.mjs b/packages/cli/src/lib/component-format.mjs
index 76e2bb529c..7af7ff4134 100644
--- a/packages/cli/src/lib/component-format.mjs
+++ b/packages/cli/src/lib/component-format.mjs
@@ -6,6 +6,7 @@
import {discoverComponents, findComponentReadme, resolveImportPath} from './component-discovery.mjs';
import {loadDocs} from './component-loader.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
/**
* Derive the `defineTheme` component-override key from a theming target.
@@ -81,7 +82,7 @@ function formatSubComponent(comp) {
if (table) {
out.push(table + '\n');
} else {
- out.push(`See \`astryx component ${comp.name}\` for props and usage.\n`);
+ out.push(`See \`${getCliInvocation()} component ${comp.name}\` for props and usage.\n`);
}
return out;
}
diff --git a/packages/cli/src/utils/package-manager.mjs b/packages/cli/src/utils/package-manager.mjs
index 2440fb8dba..99b653c543 100644
--- a/packages/cli/src/utils/package-manager.mjs
+++ b/packages/cli/src/utils/package-manager.mjs
@@ -72,3 +72,81 @@ export function getRunPrefix(targetDir) {
default: return 'npx';
}
}
+
+/** The published CLI package name — used for one-off (uninstalled) invocations. */
+export const CLI_PACKAGE = '@astryxdesign/cli';
+
+/** The CLI binary name — only resolves once the CLI is installed (or run via CLI_PACKAGE). */
+export const CLI_BIN = 'astryx';
+
+/**
+ * Get the one-off ("dlx") runner for the detected package manager.
+ *
+ * Unlike {@link getRunPrefix} (which runs an *installed* binary), this fetches
+ * and runs a package on demand — so it is always paired with the scoped
+ * {@link CLI_PACKAGE}, never the bare `astryx` bin. Running bare `npx astryx`
+ * without the CLI installed resolves to an unrelated package on the registry.
+ *
+ * @param {string} [targetDir]
+ * @returns {string} e.g. 'npx', 'pnpm dlx', 'yarn dlx', 'bunx'
+ */
+export function getDlxPrefix(targetDir) {
+ const pm = detectPackageManager(targetDir);
+ switch (pm) {
+ case 'yarn': return 'yarn dlx';
+ case 'pnpm': return 'pnpm dlx';
+ case 'bun': return 'bunx';
+ case 'npm':
+ default: return 'npx';
+ }
+}
+
+/**
+ * Heuristic: was the running CLI launched one-off via a package runner
+ * (npx / pnpm dlx / yarn dlx / bunx) rather than from an installed dependency?
+ *
+ * We sniff the entry path (`process.argv[1]`) for well-known runner-cache
+ * markers. This errs safe in both directions: a false negative falls back to
+ * the installed form (`<prefix> astryx`, the historical behavior), and a false
+ * positive emits the always-valid scoped form (`<dlx> @astryxdesign/cli`).
+ *
+ * @returns {boolean}
+ */
+export function isCliOneOff() {
+ const entry = String(process.argv[1] || '').replace(/\\/g, '/');
+ return /\/_npx\/|\/dlx[-/]|\/\.bun\/install\/cache\/|\/bunx-/.test(entry);
+}
+
+/**
+ * The safe, install-aware CLI invocation stem to suggest to users.
+ *
+ * - Installed / global / dev: `<run-prefix> astryx` (e.g. `pnpm exec astryx`).
+ * Bare `astryx` resolves to the local (or global) binary.
+ * - One-off (npx/dlx cache): `<dlx-prefix> @astryxdesign/cli` — the bare
+ * `astryx` name isn't on disk, so npm would fetch an unrelated registry
+ * package; the scoped package always resolves to us.
+ *
+ * @param {string} [targetDir]
+ * @returns {string}
+ */
+export function getCliInvocation(targetDir) {
+ if (isCliOneOff()) return `${getDlxPrefix(targetDir)} ${CLI_PACKAGE}`;
+ return `${getRunPrefix(targetDir)} ${CLI_BIN}`;
+}
+
+/**
+ * Format a full, runnable CLI command from a subcommand string.
+ *
+ * Accepts either `astryx component Button` or `component Button` (a leading
+ * `astryx` token is stripped) and prepends the install-aware invocation stem
+ * from {@link getCliInvocation}.
+ *
+ * @param {string} command e.g. 'astryx component Button' | 'docs tokens'
+ * @param {string} [targetDir]
+ * @returns {string}
+ */
+export function formatCliCommand(command, targetDir) {
+ const sub = String(command).replace(/^\s*astryx\b\s*/, '').trim();
+ const stem = getCliInvocation(targetDir);
+ return sub ? `${stem} ${sub}` : stem;
+}
diff --git a/packages/cli/src/utils/package-manager.test.mjs b/packages/cli/src/utils/package-manager.test.mjs
index ed1c66265f..aa7267c0d1 100644
--- a/packages/cli/src/utils/package-manager.test.mjs
+++ b/packages/cli/src/utils/package-manager.test.mjs
@@ -4,9 +4,16 @@ import {describe, it, expect, afterEach, vi} from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
-import {detectPackageManager} from './package-manager.mjs';
+import {
+ detectPackageManager,
+ getDlxPrefix,
+ isCliOneOff,
+ getCliInvocation,
+ formatCliCommand,
+} from './package-manager.mjs';
let tmpDir;
+const ORIGINAL_ARGV1 = process.argv[1];
afterEach(() => {
if (tmpDir) {
@@ -15,6 +22,7 @@ afterEach(() => {
}
vi.restoreAllMocks();
delete process.env.npm_config_user_agent;
+ process.argv[1] = ORIGINAL_ARGV1;
});
function makeTmpDir() {
@@ -111,3 +119,102 @@ describe('detectPackageManager', () => {
expect(detectPackageManager(dir)).toBe('bun');
});
});
+
+describe('getDlxPrefix', () => {
+ it('returns "pnpm dlx" for pnpm projects', () => {
+ const dir = makeTmpDir();
+ fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+ expect(getDlxPrefix(dir)).toBe('pnpm dlx');
+ });
+
+ it('returns "yarn dlx" for yarn projects', () => {
+ const dir = makeTmpDir();
+ fs.writeFileSync(path.join(dir, 'yarn.lock'), '');
+ expect(getDlxPrefix(dir)).toBe('yarn dlx');
+ });
+
+ it('returns "bunx" for bun projects', () => {
+ const dir = makeTmpDir();
+ fs.writeFileSync(path.join(dir, 'bun.lockb'), '');
+ expect(getDlxPrefix(dir)).toBe('bunx');
+ });
+
+ it('falls back to "npx" with no signals', () => {
+ const dir = makeTmpDir();
+ delete process.env.npm_config_user_agent;
+ expect(getDlxPrefix(dir)).toBe('npx');
+ });
+});
+
+describe('isCliOneOff', () => {
+ it('detects an npm npx cache entry', () => {
+ process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
+ expect(isCliOneOff()).toBe(true);
+ });
+
+ it('detects a pnpm dlx cache entry', () => {
+ process.argv[1] = '/home/u/.cache/pnpm/dlx/9f/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+ expect(isCliOneOff()).toBe(true);
+ });
+
+ it('detects a bunx cache entry', () => {
+ process.argv[1] = '/home/u/.bun/install/cache/@astryxdesign/cli/bin/astryx.mjs';
+ expect(isCliOneOff()).toBe(true);
+ });
+
+ it('is false for an installed node_modules entry', () => {
+ process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+ expect(isCliOneOff()).toBe(false);
+ });
+
+ it('is false for a source checkout (dev) entry', () => {
+ process.argv[1] = '/repo/packages/cli/bin/astryx.mjs';
+ expect(isCliOneOff()).toBe(false);
+ });
+});
+
+describe('getCliInvocation', () => {
+ it('uses the run-prefix + bare bin when installed (not one-off)', () => {
+ process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+ const dir = makeTmpDir();
+ fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+ expect(getCliInvocation(dir)).toBe('pnpm exec astryx');
+ });
+
+ it('uses the dlx runner + scoped package when run one-off', () => {
+ process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
+ const dir = makeTmpDir();
+ delete process.env.npm_config_user_agent;
+ expect(getCliInvocation(dir)).toBe('npx @astryxdesign/cli');
+ });
+
+ it('pairs the dlx runner with the scoped package for pnpm one-off', () => {
+ process.argv[1] = '/home/u/.cache/pnpm/dlx/9f/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+ const dir = makeTmpDir();
+ fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+ expect(getCliInvocation(dir)).toBe('pnpm dlx @astryxdesign/cli');
+ });
+});
+
+describe('formatCliCommand', () => {
+ it('strips a leading "astryx" token and prepends the invocation stem', () => {
+ process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+ const dir = makeTmpDir();
+ fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+ expect(formatCliCommand('astryx component Button', dir)).toBe('pnpm exec astryx component Button');
+ });
+
+ it('accepts a bare subcommand (no leading astryx)', () => {
+ process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+ const dir = makeTmpDir();
+ fs.writeFileSync(path.join(dir, 'package-lock.json'), '{}');
+ expect(formatCliCommand('docs tokens', dir)).toBe('npx astryx docs tokens');
+ });
+
+ it('rewrites to the scoped package for one-off invocations', () => {
+ process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
+ const dir = makeTmpDir();
+ fs.writeFileSync(path.join(dir, 'package-lock.json'), '{}');
+ expect(formatCliCommand('astryx component Button', dir)).toBe('npx @astryxdesign/cli component Button');
+ });
+});
diff --git a/packages/cli/src/utils/update-check.mjs b/packages/cli/src/utils/update-check.mjs
index 803ed46fe3..85325c8835 100644
--- a/packages/cli/src/utils/update-check.mjs
+++ b/packages/cli/src/utils/update-check.mjs
@@ -14,6 +14,7 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
import {semverGt} from './semver.mjs';
+import {getCliInvocation} from './package-manager.mjs';
/**
* Read the latest available version from local signals.
@@ -75,7 +76,7 @@ export function checkForUpdate(cwd = process.cwd()) {
// Use semver-aware comparison so '0.0.20' is correctly treated as greater
// than '0.0.5' (lexicographic compare gets that backwards).
if (semverGt(latest, installed)) {
- return `FYI: A newer version of @astryxdesign/core (${latest}) is available. Install the new package version, then run: astryx upgrade --from <old-version> --apply`;
+ return `FYI: A newer version of @astryxdesign/core (${latest}) is available. Install the new package version, then run: ${getCliInvocation()} upgrade --from <old-version> --apply`;
}
return null;
diff --git a/packages/core/README.md b/packages/core/README.md
index b55308e5b1..ce84cf4327 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -2,7 +2,14 @@
Core UI components, theme system, and utilities for the Astryx design system. For project setup, see [Quick Start](#quick-start) below.
-> **Building with an AI agent?** Run **`npx astryx init`** first. It installs the Astryx CLI's component index into your `AGENTS.md`/`CLAUDE.md` so your agent discovers components, templates, and design tokens instead of guessing. Without it, agents can't see the CLI — see [XDS CLI](#xds-cli).
+> **Building with an AI agent?** Add the CLI, then run `init`:
+>
+> ```bash
+> npm install -D @astryxdesign/cli # or: pnpm add -D / yarn add -D / bun add -d
+> npx astryx init # resolves to the CLI you just installed
+> ```
+>
+> `init` writes the Astryx component index into your `AGENTS.md`/`CLAUDE.md` so your agent discovers components, templates, and design tokens instead of guessing. Need a single command without installing? Use the scoped package directly — `npx @astryxdesign/cli <cmd>` (or `pnpm dlx`/`bunx @astryxdesign/cli`). Bare `npx astryx` only works once `@astryxdesign/cli` is a dependency; before that npm resolves it to an unrelated package. See [XDS CLI](#xds-cli).
## Component Docs
@@ -25,9 +32,9 @@ global navigation.
Requires `@astryxdesign/cli` (`npm install -D @astryxdesign/cli`):
```bash
-npx astryx template --list # browse all page and block templates
-npx astryx template dashboard # emit full page source
-npx astryx template settings --skeleton # layout skeleton with spatial annotations
+astryx template --list # browse all page and block templates
+astryx template dashboard # emit full page source
+astryx template settings --skeleton # layout skeleton with spatial annotations
```
## Astryx CLI
@@ -35,19 +42,21 @@ npx astryx template settings --skeleton # layout skeleton with spatial annotatio
The CLI (`@astryxdesign/cli`) provides additional tooling:
```bash
-npx astryx --help # full listing of all commands
-npx astryx component Button # full docs + related block templates
-npx astryx docs # reference docs (principles, tokens, theming, styling)
-npx astryx docs theme # theming guide (Theme, defineTheme, light/dark)
-npx astryx docs tokens # spacing, color, radius, typography token reference
-npx astryx init # initialize Astryx in your project
-npx astryx theme build # build theme CSS for production
-npx astryx swizzle Button # eject component source for customization
-npx astryx upgrade --apply # run codemods to migrate between versions
-npx astryx discover # discover external Astryx packages
-npx astryx gap-report # report a missing capability
+astryx --help # full listing of all commands
+astryx component Button # full docs + related block templates
+astryx docs # reference docs (principles, tokens, theming, styling)
+astryx docs theme # theming guide (Theme, defineTheme, light/dark)
+astryx docs tokens # spacing, color, radius, typography token reference
+astryx init # initialize Astryx in your project
+astryx theme build # build theme CSS for production
+astryx swizzle Button # eject component source for customization
+astryx upgrade --apply # run codemods to migrate between versions
+astryx discover # discover external Astryx packages
+astryx gap-report # report a missing capability
```
+> Prefix these with your runner: `npx astryx …` / `pnpm exec astryx …` once the CLI is installed, or `npx @astryxdesign/cli …` to run without installing.
+
## Related Packages
| Package | Description |
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index cbdfdf882e..9a4780551c 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -113,7 +113,7 @@ export const docs = {
{
name: 'labelIcon',
type: 'IconType',
- description: 'Icon to display before the label text. See `npx astryx docs icons` for valid semantic names.',
+ description: 'Icon to display before the label text. See `astryx docs icons` for valid semantic names.',
},
{
name: 'status',
diff --git a/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
index dbb739ed02..0f81f7f679 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
@@ -18,7 +18,7 @@ export const docs = {
{
name: 'icon',
type: 'IconType',
- description: 'Icon to display before the label. See `npx astryx docs icons` for valid semantic names.',
+ description: 'Icon to display before the label. See `astryx docs icons` for valid semantic names.',
},
{
name: 'label',
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
index 024072c0a7..064fa52f59 100644
--- a/packages/core/src/Field/Field.doc.mjs
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -95,7 +95,7 @@ export const docs = {
{
name: 'labelIcon',
type: 'IconType',
- description: 'Icon to display before the label text. See `npx astryx docs icons` for valid semantic names.',
+ description: 'Icon to display before the label text. See `astryx docs icons` for valid semantic names.',
},
{
name: 'labelTooltip',
diff --git a/packages/core/src/Field/FieldLabel.doc.mjs b/packages/core/src/Field/FieldLabel.doc.mjs
index b0af260219..5df799e84b 100644
--- a/packages/core/src/Field/FieldLabel.doc.mjs
+++ b/packages/core/src/Field/FieldLabel.doc.mjs
@@ -48,7 +48,7 @@ export const docs = {
{
name: 'labelIcon',
type: 'IconType',
- description: 'Icon before the label text. See `npx astryx docs icons` for valid semantic names.',
+ description: 'Icon before the label text. See `astryx docs icons` for valid semantic names.',
},
{
name: 'labelTooltip',
diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjs
index 4802222c61..f6eeba8b5d 100644
--- a/packages/core/src/NumberInput/NumberInput.doc.mjs
+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs
@@ -82,12 +82,12 @@ export const docs = {
{
name: 'startIcon',
type: 'IconType',
- description: 'Icon to display at the start of the input. See `npx astryx docs icons` for valid semantic names.',
+ description: 'Icon to display at the start of the input. See `astryx docs icons` for valid semantic names.',
},
{
name: 'labelIcon',
type: 'IconType',
- description: 'Icon to display before the label text. See `npx astryx docs icons` for valid semantic names.',
+ description: 'Icon to display before the label text. See `astryx docs icons` for valid semantic names.',
},
{
name: 'status',
diff --git a/packages/core/src/Selector/SelectorOption.doc.mjs b/packages/core/src/Selector/SelectorOption.doc.mjs
index ff263e05a3..825d48603a 100644
--- a/packages/core/src/Selector/SelectorOption.doc.mjs
+++ b/packages/core/src/Selector/SelectorOption.doc.mjs
@@ -20,7 +20,7 @@ export const docs = {
name: 'icon',
type: 'IconType',
description:
- 'Icon displayed before the label. See `npx astryx docs icons` for valid semantic names.',
+ 'Icon displayed before the label. See `astryx docs icons` for valid semantic names.',
},
{
name: 'description',
diff --git a/packages/core/src/SideNav/SideNavItem.doc.mjs b/packages/core/src/SideNav/SideNavItem.doc.mjs
index 6d8919204f..63007b7f66 100644
--- a/packages/core/src/SideNav/SideNavItem.doc.mjs
+++ b/packages/core/src/SideNav/SideNavItem.doc.mjs
@@ -23,12 +23,12 @@ export const docs = {
{
name: 'icon',
type: 'IconType',
- description: 'Icon displayed in the outline (unselected) variant. See `npx astryx docs icons` for valid semantic names.',
+ description: 'Icon displayed in the outline (unselected) variant. See `astryx docs icons` for valid semantic names.',
},
{
name: 'selectedIcon',
type: 'IconType',
- description: 'Icon displayed when the item is selected (filled variant). See `npx astryx docs icons` for valid semantic names.',
+ description: 'Icon displayed when the item is selected (filled variant). See `astryx docs icons` for valid semantic names.',
},
{
name: 'isSelected',
diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjs
index f005a32f31..785936efc0 100644
--- a/packages/core/src/Switch/Switch.doc.mjs
+++ b/packages/core/src/Switch/Switch.doc.mjs
@@ -107,7 +107,7 @@ export const docs = {
{
name: 'labelIcon',
type: 'IconType',
- description: 'Icon displayed before the label text. See `npx astryx docs icons` for valid semantic names.',
+ description: 'Icon displayed before the label text. See `astryx docs icons` for valid semantic names.',
},
{
name: 'labelTooltip',
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
index 814a8e3df8..d1cfdd4c18 100644
--- a/packages/core/src/TextArea/TextArea.doc.mjs
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -116,7 +116,7 @@ export const docs = {
name: 'startIcon',
type: 'IconType',
description:
- 'Icon component rendered inside the leading edge of the textarea wrapper. See `npx astryx docs icons` for valid semantic names.',
+ 'Icon component rendered inside the leading edge of the textarea wrapper. See `astryx docs icons` for valid semantic names.',
},
{
name: 'hasSpellCheck',
diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjs
index 45fc77fbf5..a48a35bde5 100644
--- a/packages/core/src/TextInput/TextInput.doc.mjs
+++ b/packages/core/src/TextInput/TextInput.doc.mjs
@@ -106,7 +106,7 @@ export const docs = {
name: 'startIcon',
type: 'IconType',
description:
- 'SVG icon component displayed at the start of the input. See `npx astryx docs icons` for valid semantic names.',
+ 'SVG icon component displayed at the start of the input. See `astryx docs icons` for valid semantic names.',
},
{
name: 'status',
diff --git a/packages/core/src/theme/Theme.doc.mjs b/packages/core/src/theme/Theme.doc.mjs
index 390acd71c9..2a9a5e896c 100644
--- a/packages/core/src/theme/Theme.doc.mjs
+++ b/packages/core/src/theme/Theme.doc.mjs
@@ -39,12 +39,12 @@ export const docs = {
},
usage: {
description:
- 'Wraps a subtree with a specific Astryx theme. For static production themes, use `npx astryx theme build` and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime `defineTheme()` when themes are dynamic or for prototyping.\n\n`defineTheme` accepts a `tokens` object whose keys are CSS custom property names (always prefixed with `--`). Common token names include `--color-accent`, `--color-background-surface`, `--color-background-body`, `--color-text-primary`, `--color-text-secondary`, `--radius-container`, `--spacing-1` through `--spacing-6`. Values can be a string (same for light/dark) or a `[light, dark]` tuple.\n\nExample:\n```ts\nimport {defineTheme} from \'@astryxdesign/core/theme\';\nconst myTheme = defineTheme({\n name: \'ocean\',\n tokens: {\n \'--color-accent\': [\'#0077B6\', \'#48CAE4\'],\n \'--color-background-surface\': [\'#F0F8FF\', \'#0A1628\'],\n \'--color-text-primary\': [\'#0A1317\', \'#FFFFFF\'],\n \'--radius-container\': \'16px\',\n },\n});\n```',
+ 'Wraps a subtree with a specific Astryx theme. For static production themes, use `astryx theme build` and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime `defineTheme()` when themes are dynamic or for prototyping.\n\n`defineTheme` accepts a `tokens` object whose keys are CSS custom property names (always prefixed with `--`). Common token names include `--color-accent`, `--color-background-surface`, `--color-background-body`, `--color-text-primary`, `--color-text-secondary`, `--radius-container`, `--spacing-1` through `--spacing-6`. Values can be a string (same for light/dark) or a `[light, dark]` tuple.\n\nExample:\n```ts\nimport {defineTheme} from \'@astryxdesign/core/theme\';\nconst myTheme = defineTheme({\n name: \'ocean\',\n tokens: {\n \'--color-accent\': [\'#0077B6\', \'#48CAE4\'],\n \'--color-background-surface\': [\'#F0F8FF\', \'#0A1628\'],\n \'--color-text-primary\': [\'#0A1317\', \'#FFFFFF\'],\n \'--radius-container\': \'16px\',\n },\n});\n```',
bestPractices: [
{
guidance: true,
description:
- 'Build app themes that are known ahead of time with `npx astryx theme build`, then import the generated CSS and built theme object.',
+ 'Build app themes that are known ahead of time with `astryx theme build`, then import the generated CSS and built theme object.',
},
{
guidance: true,
@@ -90,12 +90,12 @@ export const docs = {
export const docsDense = {
usage: {
description:
- 'Wraps subtree w/ specific Astryx theme. For static production themes, use `npx astryx theme build` + generated CSS + built theme object for first-paint/SSR performance. Use runtime `defineTheme()` for dynamic themes or prototyping. Token names always start with `--` (e.g. `--color-accent`, `--color-background-surface`).',
+ 'Wraps subtree w/ specific Astryx theme. For static production themes, use `astryx theme build` + generated CSS + built theme object for first-paint/SSR performance. Use runtime `defineTheme()` for dynamic themes or prototyping. Token names always start with `--` (e.g. `--color-accent`, `--color-background-surface`).',
bestPractices: [
{
guidance: true,
description:
- 'Build app themes known ahead of time w/ `npx astryx theme build`; import generated CSS + built theme object.',
+ 'Build app themes known ahead of time w/ `astryx theme build`; import generated CSS + built theme object.',
},
{
guidance: true,
diff --git a/packages/core/src/theme/Theme.tsx b/packages/core/src/theme/Theme.tsx
index d174dfbb12..3c76f3f9c8 100644
--- a/packages/core/src/theme/Theme.tsx
+++ b/packages/core/src/theme/Theme.tsx
@@ -127,7 +127,7 @@ function useThemeStyleInjection(theme: DefinedTheme): void {
`For better performance, use the pre-built theme:\n\n` +
` import {${theme.name}Theme} from '@astryxdesign/theme-${theme.name}/built';\n` +
` import '@astryxdesign/theme-${theme.name}/theme.css';\n\n` +
- `For custom themes, run \`npx astryx theme build <file>\` to generate ` +
+ `For custom themes, run \`npx @astryxdesign/cli theme build <file>\` to generate ` +
`the built artifacts.`,
);
}
diff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.ts
index 7c5d8167fa..737178b137 100644
--- a/packages/core/src/theme/defineTheme.ts
+++ b/packages/core/src/theme/defineTheme.ts
@@ -5,7 +5,7 @@
*
* Two distribution modes:
* - Unbuilt: Theme generates CSS and injects a <style> tag at runtime
- * - Built: `npx astryx theme build` pre-compiles to a CSS file; Theme just
+ * - Built: `astryx theme build` pre-compiles to a CSS file; Theme just
* sets the data-astryx-theme attribute
*
* Token values can be:
diff --git a/scripts/generate-token-docs.mjs b/scripts/generate-token-docs.mjs
index eb1a41e1a1..3657783958 100644
--- a/scripts/generate-token-docs.mjs
+++ b/scripts/generate-token-docs.mjs
@@ -232,7 +232,7 @@ const styles = stylex.create({
},
{
type: 'prose',
- text: "See `npx astryx docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `npx astryx docs theme` for overriding tokens with defineTheme.",
+ text: "See `astryx docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `astryx docs theme` for overriding tokens with defineTheme.",
},
],
});