CLI reference
The signalos CLI wraps the shadcn pull with a lockfile and drift tracking. Every command runs from your app's root.
Commands
| Command | What it does |
|---|---|
| signalos token set <token> | Cross-platform token setup: persists it for your shell (setx / .zshrc / .bashrc / fish), writes .env.local in a project (and gitignores it), verifies registry access. |
| signalos token status | Shows where the token is loaded from (masked) and whether it reaches the registry. |
| signalos init | Adds the @signalos registry to components.json, verifies the token, creates signalos.lock.json. |
| signalos add <widgets…> | Pulls widget/page source (delegates to shadcn add) and records versions + file hashes in the lockfile. |
| signalos diff [widget] [--json] | Compares installed items against the registry. Exit 1 on any drift - cron-friendly. |
| signalos update <widget> | Re-pulls one item: clean files overwritten, locally-edited files get .new siblings. |
| signalos lock refresh <widget> | Re-hashes on-disk files after you resolve .new conflicts - records the merged state as baseline. |
Global options & environment
SIGNALOS_REGISTRY_TOKEN- required for every network command; a fine-grained GitHub PAT with Contents read-only on the registry repo. Resolved from the shell environment first, then.env.local/.envin the app root - set it once withsignalos token set.--cwd <path>- run against another app root (default: current directory).--registry-url <template>- override the registry URL; must contain{name}. Point it at a git tag to pin:…/signal-widgets/<tag>/r/{name}.json
Troubleshooting
the usual suspects
404 on a private repo → bad/expired token, or you left the widget-consumers team
(GitHub answers 404, not 401, for private repos)
"SIGNALOS_REGISTRY_TOKEN is not set"
→ export it in your shell profile and CI secrets
diff exits 1 → that's the point - something drifted; read the report