Global mode

Global mode means installing the Astryx CLI once for your computer, so the astryx command works everywhere: in your projects, in an empty folder, and for every coding agent. Inside a project, the project's own version of Astryx answers, so your global install never changes what a project gets.

bash
npm i -g @astryxdesign/cli

• Docs, components, templates, and search in any folder, before you have a project.
• Every coding agent on your computer knows Astryx, through a short guide the CLI keeps where agent tools look.
• Each project keeps its own version: in a project, the project's version answers, whichever astryx command you run.

Not sure whether you want a project install, a global one, or both: astryx docs global/project-global-or-both. The details: astryx docs global/who-answers.

Your global install never upgrades itself or a project. When a newer version is out, a command that succeeds ends with a two-line notice, at most once a day: astryx docs global/updates.

The CLI keeps a short Astryx guide where agent tools look in your home folder, so an agent working anywhere knows Astryx is there: astryx docs global/computer-agent-guide.

Integrations you install next to your global install work outside projects. Inside a project, only the project's own integrations do: astryx docs global/computer-integrations. Building one: astryx docs cli/integrations/global-integrations.

• Install, and work offline: astryx docs global/install-once.
• Monorepos and nested folders: astryx docs global/monorepos.
• CI and containers: astryx docs global/ci-and-containers.
• Something looks wrong: astryx docs global/problems.
• Uninstall and reset: astryx docs global/uninstall.
• Every path, setting, JSON field, and error code: astryx docs global/reference.
• What each command does outside a project: astryx docs cli/commands.

Install the CLI in each project and once for your computer. Each side does something the other cannot, and they never conflict:

• **In the project**, the CLI version is pinned in package.json and the lockfile, so teammates and CI run exactly that version, with nothing fetched at run time.
• **Globally**, the astryx command works in every folder, including an empty one before a project exists, and every coding agent on your computer knows Astryx through its agent guide.
• **Together**, in a project the project's version always answers, even when you type the global astryx command; outside a project your global version does. Global mode never makes the project's CLI unnecessary.

In the project folder (the getting-started guide lists the other packages an app installs):

bash
npm install @astryxdesign/core @astryxdesign/cli
astryx init

Once for your computer:

bash
npm i -g @astryxdesign/cli

For both, do both, in either order.

In a project, the project's version always answers, even when you type the global astryx command; outside a project, your global version does. astryx docs global/who-answers

This page is part of astryx docs global, which explains what global mode is and how each part works. To start an app: astryx docs getting-started.

Install the CLI package with your package manager. One astryx command then works in every folder.

bash
npm i -g @astryxdesign/cli
# or: pnpm add -g @astryxdesign/cli · yarn global add @astryxdesign/cli · bun add -g @astryxdesign/cli · volta install @astryxdesign/cli

Keep the CLI installed in each project too: that pins its version for teammates and CI (astryx docs global/project-global-or-both). Inside a project, whichever astryx command you type, the project's version answers. Outside a project, your global install answers with its own version, and a version you name, such as npx @astryxdesign/cli@0.7.0, answers as exactly that version.

If npm i -g fails with EACCES, do not use sudo. Give npm a global folder you own, then add its bin folder to your PATH, or use a Node version manager such as nvm, fnm, or Volta:

bash
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
npm i -g @astryxdesign/cli

Astryx's update notice then names that folder in its upgrade command.

When a project's own CLI is installed but cannot start, Astryx runs the CLI version equal to the project's Core instead, installing it once into a cache in your home folder and reusing it. It uses npm for that, so your npm registry, proxy, and offline settings apply. Deleting the cache is safe: versions come back when a project needs them. Where it lives: astryx docs global/reference.

Your global install answers offline in a project with only Core, and so does any project that installs its own CLI. Outside a project, commands that read components, such as astryx component Button, need your global version's Core: after any command you run online, your global install downloads it once into the cache in the background, so they work offline from then on (not in CI, where nothing downloads by itself: astryx docs global/ci-and-containers; and not on Windows, where the first component command downloads it). Only a project whose own CLI cannot start needs a version installed or cached; when it is neither and cannot be fetched, your global install answers with a one-line warning, and Astryx waits 2 minutes before trying to download it again (10 minutes after a second failure in a row). astryx docs global/problems has the exact message.

This page is part of astryx docs global, which explains what global mode is and how each part works. Next: astryx docs global/who-answers.

• The project installs the CLI, as recommended: that CLI answers, whatever its version, as it always has. When you type the global astryx command instead, it passes the run to the project's CLI, with the same arguments, input, output, and exit status, so either command gives the same answer.
• The project installs only Core, or nothing is installed yet, as in a fresh clone: the astryx command you started answers, as it always has. When its version differs from the project's Core, a hint after the command, once a day, names the command that adds the CLI at Core's version.
• The project's CLI is installed but cannot start: the CLI version equal to the project's Core answers instead (from the installed Core, else the lockfile, else the newest one the declared range allows), installed once into a cache.

Components come from @astryxdesign/core, and templates, docs, and agent guides come from the CLI. In a project, that Core is the one the project installs, so component commands work offline once the project's dependencies are installed. Outside a project, or in a project with nothing installed yet (a fresh clone), they use the answering version's own Core, from beside the CLI or the cache; when that Core cannot be downloaded, the error says to install the project's dependencies. When the project's CLI and Core are different versions, astryx doctor warns and prints the command that brings them to one version.

In a folder that belongs to no project, your global install answers as a brand-new project on its version would, so you and your agents can read every component and doc. It never installs a newer version by itself.

A few commands work on your computer rather than a folder, such as astryx init --user: your global install answers them in any folder.

In a project with only Core, the hint looks like this, after the command, at most once a day per project:

text
astryx: this project has no Astryx CLI installed; answered by CLI 0.7.2 while its Core is 0.6.8. To match, run: npm install @astryxdesign/cli@0.6.8

Otherwise, in text mode, one line on standard error names the version, unless the project's own CLI answered directly:

text
astryx: answered by this project's CLI 0.6.8, handed over from CLI 0.7.2
astryx: answered by CLI 0.6.8 with Core 0.6.8, the release that matches this project's Core
astryx: answered by CLI 0.7.2 with Core 0.7.2, outside a project
astryx: answered by CLI 0.7.2 with Core 0.7.2, for this computer

With --json nothing extra prints; every result carries meta.answeredBy instead (astryx docs global/reference):

json
{"meta": {"answeredBy": {"cli": "0.7.2", "core": "0.6.8", "copy": "starting"}}}

Commands the CLI prints for you to run start with a name that reaches the same version: the project's runner (such as pnpm exec astryx) in a project, astryx outside a project when your global install answered, and otherwise the CLI pinned to the version, such as npx @astryxdesign/cli@0.6.8. An integration can name its own command: astryx docs cli/integrations/building-blocks/configuration/cli-command.

This page is part of astryx docs global, which explains what global mode is and how each part works. To check your computer, run astryx doctor outside any project (astryx docs cli/commands/doctor). Monorepos: astryx docs global/monorepos.

Once a day, never in your first day, your global install checks the registry's latest version in the background, without slowing the command. When a newer one exists, a command that succeeds prints two lines on standard error, at most once a day:

text
A new release of Astryx is available: 0.7.2 → 0.7.3
To upgrade, run: npm i -g @astryxdesign/cli@latest

• The command is the one for the package manager that installed your global install: npm i -g, pnpm add -g, yarn global add, bun add -g, or volta install. A global folder moved with the package manager's own setting (BUN_INSTALL, Yarn's global-folder, PNPM_HOME, or npm's prefix) counts while that setting names it; an app's own copy never runs the update check.
• When the newest version needs a newer Node than your computer runs, the second line says which Node to install first.
• Inside a project, the notice is about the project's version, and names the project's install and upgrade commands. The install command always adds the CLI next to Core, so a project that installed only Core gets its own CLI too, as recommended.

No notice prints with --json, after a failed command, when the CI environment variable is set, or when NO_UPDATE_NOTIFIER is set; with either variable set, the CLI does not check the registry either. Unlike some CLIs, a notice prints even when standard error is not a terminal, because agents run the CLI without one.

astryx doctor shows the same thing at any time, in its newest-release check, along with why the last notice did not print, if one did not. When the last check ran, and when each notice printed, are kept in state.json in the settings folder (astryx docs global/reference).

This page is part of astryx docs global, which explains what global mode is and how each part works. Upgrading a project: astryx docs cli/commands/upgrade.

A project's agent docs reach only agents working in that project. Your global install also keeps one skill file, ~/.agents/skills/astryx/SKILL.md, which most coding agents read. It tells agents that Astryx is on this computer, when it is relevant (building or changing UI), and to start with astryx search. It names no version, so it never goes stale. Inside a project, the project's own agent docs come first.

It is written in the background on the first run and again after you upgrade, so no command waits for it. Installing the package does not write it, because some package managers skip install scripts.

Agents that read only their own skills folder get a link to the skill's folder, so they read the same one file: a folder symlink with a relative target (a junction on Windows, or a copy where neither can be made). Continue's scanner skips links, so it gets a copy, refreshed with the file:

Astryx never replaces anything it did not create at one of these folders, and never writes a folder another tool manages; astryx doctor names any it skipped, and any link whose skill folder is missing, as in a container that mounts only one agent's folder.

• Cloud and background agents read only the repository, so the project's own agent docs, the block astryx init writes into AGENTS.md or CLAUDE.md, are what reach them.
• Apps that take an uploaded skill: upload ~/.agents/skills/astryx/SKILL.md, or a zip of its folder.

If your agent reads skills from another folder, link it to the skill:

bash
ln -s ~/.agents/skills/astryx <your agent's skills folder>/astryx

On Windows, in PowerShell:

powershell
New-Item -ItemType Junction -Path "<your agent's skills folder>\astryx" -Target "$HOME\.agents\skills\astryx"

bash
astryx init --user
astryx init --user --remove-agents

• init --user writes the file and the links now.
• --remove-agents removes the file and every link Astryx made, and turns it off until you run astryx init --user again.
• A file you edited is never overwritten or removed; delete it to get the current text.
• Outside a project, astryx doctor says whether the skill is there, current, edited, or turned off, and where it is linked.

This page is part of astryx docs global, which explains what global mode is and how each part works. A project's own agent docs: astryx docs cli/commands/init.

Install the integration the same way you installed the CLI, so the two sit side by side:

bash
npm i -g @astryxdesign/cli @acme/widgets
# or: pnpm add -g · yarn global add · bun add -g

A tool that installs the CLI together with integrations in one folder, and runs the CLI from there, counts the same way. npx and the cache of project versions never count.

In a folder outside any project, Astryx loads each integration installed next to your global install the way a project loads its own: its components, templates, docs, themes, and discover source show up, and a command name it declares starts the commands Astryx prints. One whose @astryxdesign/core or @astryxdesign/cli peer range leaves out your global version is skipped, and astryx doctor says why.

A project's answers must match what it installs: a component from a package it does not install would not build. So inside a project, an integration installed only globally adds nothing. astryx discover lists it among the packages the project could add, with the project's install command, when it supports the project's version and loads. When the project installs the same integration, the project's copy is the one used.

• Outside a project, astryx doctor lists the global integrations it uses and warns about each it skips.
• Inside a project, astryx doctor and astryx discover list the ones the project could add.

This page is part of astryx docs global, which explains what global mode is and how each part works. Building an integration: astryx docs cli/integrations/global-integrations.

Astryx searches upward from the current folder: @astryxdesign/core or @astryxdesign/cli installed there or a few folders above, else the nearest package.json declaring either, up to the repository root. Folders without any are outside projects.

• A workspace member declaring Astryx is its own project, even with packages hoisted to the repository root. A root CLI answers it, as always; a member with its own Core and no CLI anywhere gets answered by the astryx command you started.
• A folder without its own package.json, such as src/ or scripts/, belongs to the project above it.
• A repository that builds the CLI itself, with the CLI in packages/cli next to Core in packages/core, runs that CLI.

• Folders inside another project, such as nested apps or cloned repositories, answer with the enclosing project's release.
• Folder names compare as your file system compares them: a folder reached through a link, or typed in different letter case on macOS or Windows, answers like the folder itself.
• In a Yarn Plug'n'Play project, Astryx cannot see the project's own CLI, so the astryx command you started answers. Run the project's CLI through Yarn (yarn astryx) to use it directly.

Part of astryx docs global: what global mode is and how each part works.

• Most CI services set CI=true. When CI is set to anything but empty, 0, or false, Astryx never checks for updates and never prints a notice; CI=false, CI=0, and an empty CI do not count. NO_UPDATE_NOTIFIER, set to anything, does the same anywhere.
• Add @astryxdesign/cli to the project as a devDependency at the same version as @astryxdesign/core; then CI runs the version pinned in the repo, and nothing is fetched. A global install in a CI image also works: in a project, it runs the project's version.
• Use --json for output a script reads; it never carries the answered-by line or a notice.

When the project installs its own CLI and you install the project's dependencies first, there is nothing to cache. Astryx downloads into its cache only the CLI version a project whose own CLI cannot start needs, and, outside a project, the Core of a global install for commands that read components. In CI it downloads nothing in the background, so a global install in a CI image fetches that Core on its first component command. To skip those downloads on every run, cache this folder between runs:

When the cache cannot be written, a project whose own CLI cannot start is answered by the global install, with a warning naming the folder. Point XDG_CACHE_HOME at a writable absolute path, or reinstall the project's dependencies. The global install's daily check and agent guide are skipped quietly when they cannot be written.

This page is part of astryx docs global, which explains what global mode is and how each part works.

text
astryx: answered by CLI 0.7.2 with Core 0.7.2, outside a project

Information, not an error: it names the version that answered and why. It prints in text mode only, never with --json. The other forms: astryx docs global/who-answers.

text
astryx: installing CLI release 0.6.8 into the per-user cache (once)...
astryx: waiting for another run to finish installing CLI release 0.6.8...

The project's own CLI cannot start, so Astryx is installing the CLI version equal to its Core into its cache once. The second line means another run is installing it; this one waits, up to 15 minutes. To avoid the wait, install the project's dependencies.

text
A new release of Astryx is available: 0.7.2 → 0.7.3
To upgrade, run: npm i -g @astryxdesign/cli@latest
To upgrade, install Node >=22 (this computer runs Node 20.11.0), then run: npm i -g @astryxdesign/cli@latest

A newer version is out; run the command shown. When the newest version needs a newer Node, the second line names it first. To stop notices, set NO_UPDATE_NOTIFIER: astryx docs global/updates.

text
The astryx command on this computer runs CLI 0.6.4, which answers every folder itself.
To upgrade, run: npm i -g @astryxdesign/cli@latest

The first astryx command on your PATH is a version from before global mode, so it ignores your projects' versions. Run the command shown, or remove that install. astryx doctor lists every astryx command on your PATH in its cli-on-path check.

text
astryx: could not get Astryx 0.6.8 to match this project's Core (the registry could not be reached); answering with CLI 0.7.2 instead
astryx: could not get Astryx 0.6.8 to match this project's Core (the registry does not have it); answering with CLI 0.7.2 instead
astryx: could not get Astryx 0.6.8 to match this project's Core (the release cache /home/me/.cache/astryx/releases cannot be written (EACCES)); answering with CLI 0.7.2 instead

The project's own CLI cannot start, so Astryx needs the CLI version equal to its Core, and could not get it, so the command still runs: the astryx command you started answers, as before global mode. Its answers may not match the project's Core until you fix the cause. With --json, meta.answeredBy.copy is fallback. Astryx waits 2 minutes before trying the download again, and 10 minutes after a second failure in a row; reinstalling the project's dependencies fixes the project's own CLI.

• The registry could not be reached: you are offline, or a proxy blocks it. Astryx installs with npm, so set npm's proxy, https-proxy, or registry in your .npmrc, or add the CLI to the project and install its dependencies.
• The registry does not have it: a private registry without the Astryx packages. Point npm's registry for @astryxdesign at one that has them.
• The cache cannot be written: a read-only home folder, as in some containers. Point XDG_CACHE_HOME at a writable folder: astryx docs global/ci-and-containers.

Astryx treats a copy as installed for your computer only when your package manager's own settings name its folder: npm's global prefix, Bun's BUN_INSTALL, Yarn's global-folder, pnpm's PNPM_HOME, or their defaults. A folder chosen only with a one-off flag, such as yarn global add --global-folder ~/mine, is not in any setting, so Astryx treats that copy like a project's: no daily update check and no agent guide. Save the folder in your settings so Astryx knows it is a global install:

bash
yarn config set global-folder ~/mine   # writes ~/.yarnrc
export BUN_INSTALL=~/mybun              # in your shell profile, for Bun

Outside a project, commands that read components (component, search, template, build, and the like) use your global version's Core. It ships beside the CLI only for some installs; otherwise your global install downloads it once into its cache in the background after a command you run online (on Windows, the first component command downloads it), and a component command before that, offline, fails with ERR_VERSIONS_UNAVAILABLE. Reinstalling the CLI does not help: run any command once online, and component reads work offline from then on. In CI nothing downloads in the background, so the first component command there needs the registry. The global-mode pages (astryx docs global) read offline either way.

In a project with nothing installed yet, such as a fresh clone, the same commands use that Core too, and offline the error reads This project has no Core installed, and Core <version> could not be downloaded: install the project's dependencies (npm install, or your package manager's), and the project's own Core answers from then on.

A run fails with ERR_VERSIONS_UNAVAILABLE only when nothing can answer: a command that needs Core outside a project cannot install it, or a version you requested exactly cannot be found.

text
Error: No package.json found. Run this command inside an app project.
Error: No package.json found. Run this command inside an integration package.
Error: Could not find @astryxdesign/core package. Make sure you are inside the design system monorepo or have @astryxdesign/core installed.
Error: Could not find installed @astryxdesign/core (or legacy @xds/core). This folder is outside a project; upgrade migrates the code of an app project that installs @astryxdesign/core.

Commands that change an app or a package, such as theme use, integration add, swizzle, and upgrade, write nothing outside a project and say what they need. Run them in that project. Each command's doc says what it does outside a project (astryx docs cli/commands); a newer command that refuses uses ERR_PROJECT_REQUIRED.

• npm i -g fails with EACCES (permission denied): do not use sudo. Use a Node version manager, or give npm a global folder you own: npm config set prefix ~/.npm-global, then add ~/.npm-global/bin to your PATH.
• astryx: command not found after installing: your package manager's global bin folder is not on your PATH. npm prefix -g shows npm's (its bin folder on macOS and Linux); pnpm setup adds pnpm's.
• pnpm add -g stops with ERR_PNPM_NO_GLOBAL_BIN_DIR, often with Corepack: run pnpm setup, open a new terminal, and try again. Yarn 2 and later have no yarn global; use npm i -g instead.
• Windows: npm puts astryx.cmd in %APPDATA%\npm, which must be on your PATH. If PowerShell says running scripts is disabled, run astryx.cmd, or allow scripts for your user with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
• Two installs, and the wrong one runs: astryx doctor outside a project lists every astryx command on your PATH, in the order your shell tries them.

This page is part of astryx docs global, which explains what global mode is and how each part works.

While the CLI is still installed, remove the agent guide from your home folder:

bash
astryx init --user --remove-agents

Or delete ~/.agents/skills/astryx and the links to it listed in astryx docs global/computer-agent-guide.

bash
npm uninstall -g @astryxdesign/cli
# or: pnpm remove -g @astryxdesign/cli · yarn global remove @astryxdesign/cli · bun remove -g @astryxdesign/cli · volta uninstall @astryxdesign/cli

Projects are unaffected: each keeps the CLI it installs, if any.

Delete either folder to reset it; Astryx recreates what it needs on the next run.

On Linux, XDG_CACHE_HOME and XDG_CONFIG_HOME move them when set to absolute paths.

This page is part of astryx docs global, which explains what global mode is and how each part works.

Every folder the agent guide is linked into: astryx docs global/computer-agent-guide.

Astryx reads no environment variable of its own. npm's own settings, such as its registry and proxy, apply to the versions it installs for projects.

• meta.answeredBy on every successful --json result: cli (the version that answered), core (the Core it used, or null), and copy: project (the project's own CLI), starting (the astryx command you started, in a project with no CLI of its own), matched (the CLI version equal to the project's Core, when the project's own CLI cannot start), carried (outside a project), or fallback (that version could not be obtained, so the astryx command you started answered instead).
• meta.available entries from astryx discover with source: "installed for this computer": an integration installed next to your global install that the project could add, with its install command in install.

• ERR_VERSIONS_UNAVAILABLE: nothing can answer, such as a command that needs Core outside a project that cannot install it. When only the matching version is missing, the run answers anyway, with a warning. astryx docs global/problems
• ERR_PROJECT_REQUIRED: a command that only works in a project ran outside one. Commands released before global mode keep the codes they already used: theme use, theme remove, and theme add <slug> use ERR_THEME_INVALID, integration add uses ERR_FILE_NOT_FOUND, swizzle uses ERR_CORE_NOT_FOUND, and upgrade uses ERR_VERSION_DETECT.

• Which version answers: in a project, the project's own CLI (with only Core, the astryx command you started); outside one, your global version. astryx docs global/who-answers
• Commands that change a project write nothing outside one; doctor, init, and theme add do something else there. astryx docs cli/commands
• Integrations installed globally work only outside projects. astryx docs global/computer-integrations
• The programmatic API runs in your process with the package you import and never hands off to another version; with cwd outside a project, its functions answer as the commands do there. astryx docs cli/api

• **Global install**: the CLI installed for your computer with npm i -g or another package manager.
• **The project's version**: the project's own CLI; it answers every command in that project. A project with only Core has none, so the astryx command you started answers.
• **Cache**: the folder where Astryx keeps versions projects need but do not install.

This page is part of astryx docs global, which explains what global mode is and how each part works.