Repository navigation
CLI Remote Libraries
A component library can live in another git repo: its components/<library>/library.json carries a remote: { url, ref, path? } block and the folder holds only library.json + README.md. Its members are fetched live into a local cache, and never copied into the stack. Projects import members the same way as local components.
The design is in https://github.com/escacs/stack/blob/main/docs/decisions/0005-remote-component-libraries.md; the shadcn registry support in https://github.com/escacs/stack/blob/main/docs/decisions/0006-shadcn-remote-libraries.md (private repo). Shadcn registries in the remote repo are auto-detected (each item with files becomes a member).
Fetching a remote library needs git on PATH; without it the sync fails with git is not installed or not on PATH; install git to use remote component libraries. The CLI sets GIT_TERMINAL_PROMPT=0 on git, so git never waits for a password.
stack remote list
stack remote status [lib...]
stack remote sync [lib...]list shows the configured libraries:
$ stack remote list
- components/dithercn [experimental]: Remote library: dithered React primitives (backgrounds, charts, interface, text, images) fetched live from opencoredev/dithercn on main. Its shadcn registry is auto-detected, so items import like stack components. (https://github.com/opencoredev/dithercn @ main, path .)
status shows the state of each cache. The state is ok, error or never. , stale is added when the cache needs a sync: it is older than the reuse window, its last sync failed, or it lacks a commit a project pins.
$ stack remote status
- components/dithercn [never, stale]: https://github.com/opencoredev/dithercn @ main, path . (commit none, 0 members, never synced)
$ stack remote status dithercn
- components/dithercn [ok]: https://github.com/opencoredev/dithercn @ main, path . (commit 3b1e853, 67 members, shadcn, 2 skipped, synced 2026-11-10T17:36:42.613Z)
When the last sync failed, the entry is [error] with an error: line below it. status still exits 0 in that case. sync exits 1 when a library fails.
sync fetches the branch tips into the caches. It reports each library and exits 1 if any failed:
$ stack remote sync dithercn
synced components/dithercn -> 3b1e853 (67 members, shadcn, 2 skipped)
A library that fails prints failed components/<lib>: <git error> and the command exits 1.
stack init --components [lib...] [--dry-run] [--project <dir>]Tracks remote libraries in a project. For each library it checks that the repo is reachable, syncs the cache, validates the member layouts, and records url, ref, path and commit in stack.toml under [remotes."<lib>"]. Run with no library names, it covers every configured library. It exits non-zero if any library fails. init --components is idempotent. A dry run refreshes the caches, so the plan lists real members, but writes no project files.
$ stack init --components dithercn --project ./rem
init components/dithercn (https://github.com/opencoredev/dithercn @ main, path .): 67 members, shadcn, commit 3b1e853
skipped: dither-tokens (no usable files)
next:
stack import components/dithercn/<component> --to src/components/<name> (members: components/dithercn/area-chart, ...)
stack remote sync [<library>...] (refresh the offline copies)
stack serve (browse the stack)
The full output also has a skipped: dithercn-skill line, which lists a long run of duplicate-file and missing-file messages; it is cut here. The skipped lines describe problems in the upstream library's registry. A project cannot fix them.
Importing a member of a library works like any component. stack show components/dithercn lists its members; stack import components/dithercn/aurora imports one, and stack import components/dithercn imports them all.
Each remote library has a git clone and a small sync record, side by side in the same folder:
| Path | Holds |
|---|---|
$ESCACS_STACK_CACHE/<lib>/ |
the git clone of the library's repo |
$ESCACS_STACK_CACHE/<lib>.json |
url, ref, path, commit, syncedAt and the last error
|
$ESCACS_STACK_CACHE/<lib>.synth/ |
one folder per member, generated from a shadcn registry. Only for shadcn-style libraries; this is where show and import read a member's files |
ESCACS_STACK_CACHE names the folder that holds those. When it is not set, the folder is $XDG_CACHE_HOME/escacs-stack/remotes if XDG_CACHE_HOME is set, and ~/.cache/escacs-stack/remotes otherwise.
A cache is reused without contacting the remote while it is younger than ESCACS_STACK_REMOTE_TTL_MS (default 15000 ms). Older caches are synced again on the next read. Imports of a member always use the commit recorded in stack.toml, so the cache must still hold that commit; sync fetches it when needed.
--offline means no network access at all. Each library is read from its cache if it has one. A library with no cache is left out, and the commands that name its members fail with the sync hint. The list, search and show commands accept --offline; path, import, status, update, sync and preset apply also accept it, as their stack help pages show.
Without --offline, a read that finds a stale cache first tries to sync it. When that sync fails, the CLI prints one line on stderr for the library, once per run. Two cases:
-
warning: components/<lib> is unavailable (no offline copy yet). Fetch it with: stack remote sync <lib>.The library has no cache at all and its sync failed. Reads that do not need it still succeed.list --jsonreports it underremotes.errors. -
note: components/<lib> is using its offline copy (remote unreachable or its pinned ref is gone). Refresh with: stack remote sync <lib>, or skip the network with --offline.The sync failed, but an older cache exists, and the CLI reads from it.
A warning or note never fails a read. An import, update or sync that targets a member of a library with no usable cache does fail, with exit 1 and the sync hint. For example, import components/dithercn/aurora prints:
warning: components/dithercn is unavailable (no offline copy yet). Fetch it with: stack remote sync dithercn.
components/dithercn: git failed for https://127.0.0.1:9/nope.git: ...; run `stack remote sync dithercn`
--verbose, or STACK_DEBUG set to any non-empty value, adds the raw git error as a debug: line after the note. --verbose is accepted by the read commands (list, search, show, path, import).
See also: CLI Importing, CLI Environment and Flags, CLI Discover.
Stack desktop client + CLI wiki — condensed from the repo docs. App repo: https://github.com/escacs/stack-app. CLI repo (private): https://github.com/escacs/stack.