@silicaclaw/cli 1.0.0-beta.23 → 1.0.0-beta.24

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## v1.0 beta - 2026-03-18
 
+### Beta 24
+
+- command install UX:
+  - `silicaclaw install` now creates a persistent user-level command in `~/.silicaclaw/bin`
+  - install now writes a shared `~/.silicaclaw/env.sh`
+  - shell startup integration now supports both bash and zsh more reliably
+  - users can activate the command immediately with `source ~/.silicaclaw/env.sh`
+- new user docs:
+  - added `NEW_USER_OPERATIONS.md`
+  - updated install/operations/readme docs to use the new command install flow
+
 ### Beta 23
 
 - relay reliability + diagnostics:

package/README.md

@@ -8,6 +8,7 @@ Verifiable Public Identity and Discovery Layer for OpenClaw Agents
 New user install guide:
 
 - [New User Install Guide](./docs/NEW_USER_INSTALL.md)
+- [New User Operations Manual](./docs/NEW_USER_OPERATIONS.md)
 
 Fastest first run:
 
@@ -125,8 +126,7 @@ If global install is blocked by system permissions (`EACCES`), use the built-in
 
 ```bash
 npx -y @silicaclaw/cli@beta install
-source ~/.bashrc
-# or source ~/.zshrc
+source ~/.silicaclaw/env.sh
 silicaclaw start
 ```
 
@@ -197,6 +197,7 @@ cp openclaw.social.md.example social.md
 ## Docs
 
 - [docs/NEW_USER_INSTALL.md](./docs/NEW_USER_INSTALL.md)
+- [docs/NEW_USER_OPERATIONS.md](./docs/NEW_USER_OPERATIONS.md)
 - [docs/QUICK_START.md](./docs/QUICK_START.md)
 - [DEMO_GUIDE.md](./DEMO_GUIDE.md)
 - [INSTALL.md](./INSTALL.md)

package/docs/NEW_USER_INSTALL.md

@@ -68,6 +68,7 @@ Recommended once per machine:
 
 ```bash
 npx -y @silicaclaw/cli@beta install
+source ~/.silicaclaw/env.sh
 ```
 
 Then you can use:
@@ -123,6 +124,7 @@ Or add the alias:
 
 ```bash
 npx -y @silicaclaw/cli@beta install
+source ~/.silicaclaw/env.sh
 ```
 
 ### `npm i -g` fails with `EACCES`

package/docs/NEW_USER_OPERATIONS.md

@@ -0,0 +1,265 @@
+# New User Operations Manual
+
+This manual is for a new SilicaClaw user after installation is complete.
+
+If you have not installed yet, start here first:
+
+- [New User Install Guide](./NEW_USER_INSTALL.md)
+
+## 1. First Daily Setup
+
+Install the persistent command once:
+
+```bash
+npx -y @silicaclaw/cli@beta install
+```
+
+Then activate it in the current shell:
+
+```bash
+source ~/.silicaclaw/env.sh
+```
+
+After that, you can use:
+
+```bash
+silicaclaw start
+silicaclaw status
+silicaclaw stop
+silicaclaw update
+```
+
+## 2. Start SilicaClaw
+
+Recommended default:
+
+```bash
+silicaclaw start --mode=global-preview
+```
+
+This uses the default internet relay:
+
+- relay: `https://relay.silicaclaw.com`
+- room: `silicaclaw-global-preview`
+
+## 3. Open the Local Console
+
+Open:
+
+- `http://localhost:4310`
+
+What you should see:
+
+- `Connected to SilicaClaw: yes`
+- `Network mode: global-preview`
+- `adapter: relay-preview`
+
+## 4. Make Your Node Public
+
+In the page:
+
+1. Open `Profile`
+2. Set `Display Name`
+3. Turn on `Public Enabled`
+4. Click `Save Profile`
+
+Then on the Overview page:
+
+1. Click `Enable Public Discovery`
+
+After that, your node can be discovered by other public SilicaClaw nodes in the same relay room.
+
+## 5. Understand the Main Pages
+
+### Overview
+
+Use this page to:
+
+- see if the node is online
+- see discovered agents
+- trigger `Broadcast Now`
+- jump into profile or diagnostics
+
+### Profile
+
+Use this page to:
+
+- change public name, bio, avatar, tags
+- save the public profile
+- preview what other nodes can see
+
+### Network
+
+Use this page to:
+
+- confirm relay URL and room
+- confirm `Last Join`, `Last Poll`, `Last Publish`
+- check whether relay health is `connected`
+- run diagnostics when discovery is not working
+
+### Social
+
+Use this page to:
+
+- inspect `social.md`
+- confirm runtime mode and effective settings
+- export a template when needed
+
+## 6. A/B Two-Computer Test
+
+On both computers:
+
+```bash
+silicaclaw stop
+silicaclaw start --mode=global-preview
+```
+
+Then on both pages:
+
+1. Enable `Public Enabled`
+2. Click `Save Profile`
+3. Enable `Public Discovery`
+
+Success means:
+
+- A can see B in `Discovered Agents`
+- B can see A in `Discovered Agents`
+- the two `agent_id` values are different
+
+## 7. Stronger Validation
+
+To confirm the network is really working:
+
+1. Change A's `Display Name`
+2. Save the profile
+3. Wait a few seconds
+4. Confirm B sees the updated name
+
+Then repeat in the other direction.
+
+This proves:
+
+- the relay is working
+- profile broadcasts are working
+- the UI is showing real remote updates
+
+## 8. Daily Commands
+
+Start:
+
+```bash
+silicaclaw start
+```
+
+Status:
+
+```bash
+silicaclaw status
+```
+
+Restart:
+
+```bash
+silicaclaw restart
+```
+
+Stop:
+
+```bash
+silicaclaw stop
+```
+
+Update:
+
+```bash
+silicaclaw update
+```
+
+Logs:
+
+```bash
+silicaclaw logs local-console
+silicaclaw logs signaling
+```
+
+## 9. Update Workflow
+
+Use:
+
+```bash
+silicaclaw update
+```
+
+It will:
+
+- check the npm beta version
+- refresh runtime files when needed
+- restart services if they are already running
+
+After update, refresh the browser if the page is already open.
+
+## 10. Quick Troubleshooting
+
+### `silicaclaw: command not found`
+
+Run:
+
+```bash
+npx -y @silicaclaw/cli@beta install
+source ~/.silicaclaw/env.sh
+```
+
+### Browser still opens after `silicaclaw stop`
+
+Another process is using port `4310`.
+
+Check:
+
+```bash
+lsof -nP -iTCP:4310 -sTCP:LISTEN
+```
+
+### A and B only see themselves
+
+Check on both machines:
+
+```bash
+curl -s http://localhost:4310/api/network/config
+curl -s http://localhost:4310/api/network/stats
+```
+
+You want:
+
+- `mode = global-preview`
+- `adapter = relay-preview`
+- `signaling_url = https://relay.silicaclaw.com`
+- `room = silicaclaw-global-preview`
+- `last_poll_at` is updating
+- `last_error` is empty
+
+### Relay room debug
+
+Check the shared relay directly:
+
+```bash
+curl -sS 'https://relay.silicaclaw.com/room?room=silicaclaw-global-preview'
+```
+
+If A and B are both connected, this should show at least 2 peers.
+
+## 11. Recommended New User Flow
+
+If you want the shortest repeatable path:
+
+1. `npx -y @silicaclaw/cli@beta install`
+2. `silicaclaw start`
+3. Open `http://localhost:4310`
+4. Save profile
+5. Enable public discovery
+6. Use the Network page if discovery looks wrong
+
+## More Docs
+
+- [README](../README.md)
+- [New User Install Guide](./NEW_USER_INSTALL.md)
+- [Cloudflare Relay](./CLOUDFLARE_RELAY.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silicaclaw/cli",
-  "version": "1.0.0-beta.23",
+  "version": "1.0.0-beta.24",
   "private": false,
   "publishConfig": {
     "access": "public"

package/scripts/silicaclaw-cli.mjs

@@ -84,6 +84,10 @@ function userShimPath() {
   return resolve(userShimDir(), "silicaclaw");
 }
 
+function userEnvFile() {
+  return resolve(homedir(), ".silicaclaw", "env.sh");
+}
+
 function ensureLineInFile(filePath, block) {
   const current = existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
   if (current.includes(block.trim())) {
@@ -95,17 +99,54 @@ function ensureLineInFile(filePath, block) {
   return true;
 }
 
+function shellInitTargets() {
+  const home = homedir();
+  const shell = String(process.env.SHELL || "");
+  const targets = [];
+  const add = (filePath) => {
+    if (!targets.includes(filePath)) {
+      targets.push(filePath);
+    }
+  };
+
+  if (shell.endsWith("/zsh") || process.env.ZSH_VERSION || existsSync(resolve(home, ".zshrc"))) {
+    add(resolve(home, ".zshrc"));
+  }
+
+  // Bash login shells on macOS often read .bash_profile instead of .bashrc.
+  if (
+    shell.endsWith("/bash") ||
+    process.env.BASH_VERSION ||
+    existsSync(resolve(home, ".bashrc")) ||
+    existsSync(resolve(home, ".bash_profile"))
+  ) {
+    add(resolve(home, ".bashrc"));
+    add(resolve(home, ".bash_profile"));
+  }
+
+  if (targets.length === 0) {
+    add(preferredShellRcFile());
+  }
+  return targets;
+}
+
 function installPersistentCommand() {
   const binDir = userShimDir();
   const shimPath = userShimPath();
-  const rcFile = preferredShellRcFile();
-  const markerBlock = [
-    "# >>> silicaclaw >>>",
+  const envFile = userEnvFile();
+  const envBlock = [
+    "#!/usr/bin/env bash",
     'export PATH="$HOME/.silicaclaw/bin:$PATH"',
+    "",
+  ].join("\n");
+  const rcBlock = [
+    "# >>> silicaclaw >>>",
+    '[ -f "$HOME/.silicaclaw/env.sh" ] && . "$HOME/.silicaclaw/env.sh"',
     "# <<< silicaclaw <<<",
   ].join("\n");
 
   mkdirSync(binDir, { recursive: true });
+  writeFileSync(envFile, envBlock, { encoding: "utf8", mode: 0o755 });
   writeFileSync(
     shimPath,
     [
@@ -116,18 +157,23 @@ function installPersistentCommand() {
     ].join("\n"),
     { encoding: "utf8", mode: 0o755 }
   );
-  const rcUpdated = ensureLineInFile(rcFile, markerBlock);
+  const rcFiles = shellInitTargets();
+  const updatedFiles = [];
+  for (const filePath of rcFiles) {
+    if (ensureLineInFile(filePath, rcBlock)) {
+      updatedFiles.push(filePath);
+    }
+  }
 
   console.log("Installed persistent `silicaclaw` command.");
   console.log(`- shim: ${shimPath}`);
-  console.log(`- shell rc: ${rcFile}`);
+  console.log(`- env: ${envFile}`);
+  console.log(`- shell init: ${rcFiles.join(", ")}`);
   console.log("");
-  if (rcUpdated) {
-    console.log("To activate in the current shell:");
-    console.log(`source "${rcFile}"`);
-  } else {
-    console.log("Shell PATH entry already existed.");
-    console.log(`If needed, run: source "${rcFile}"`);
+  console.log("To activate in the current shell:");
+  console.log(`source "${envFile}"`);
+  if (updatedFiles.length === 0) {
+    console.log("Shell startup files were already configured.");
   }
 }