Address PR review feedback

- Fix track.ts file filtering: use `filename !== '.realm.json'` instead of
  `!filename.startsWith('.realm.json')`
- Add Windows compatibility check in stop.ts with helpful message
- Improve stop.ts process matching to handle both dev (tsx) and installed
  (boxel, node) modes
- Add BOXEL_PASSWORD env var support in profile.ts for secure non-interactive
  usage
- Fix touch.ts missing sync() method implementation
- Add profile manager integration to check.ts, create.ts, list.ts, skills.ts,
  status.ts (was using old env var approach)
- Update docs to use `npx boxel` as default command pattern
- Add security notes about avoiding `-p` flag for passwords in shell history
- Add Claude Code note at top of README with link to claude.ai/code
- Streamline installation section in README

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: christse

.claude/CLAUDE.md

@@ -8,20 +8,22 @@
 
 ## How to Run Boxel Commands
 
-**IMPORTANT:** In this development repo, the `boxel` CLI is not globally installed. Always run commands using:
+After `npm install && npm run build`, use `npx boxel`:
 
 ```bash
-npm run dev -- <command> [args]
+npx boxel sync .
+npx boxel history ./workspace
+npx boxel profile add
 ```
 
-Examples:
+Or use `boxel` directly after `npm link`.
+
+**For development** (no rebuild needed after code changes):
 ```bash
-npm run dev -- sync .                    # NOT: boxel sync .
-npm run dev -- history ./workspace       # NOT: boxel history ./workspace
-npm run dev -- milestone ./workspace 1 -n "Name"
+npm run dev -- <command>
 ```
 
-The `--` separates npm arguments from the CLI arguments. All documentation below shows `boxel <command>` for brevity, but always use `npm run dev -- <command>` when executing.
+All documentation below shows `boxel <command>` for brevity.
 
 ---
 
@@ -53,45 +55,44 @@ When you detect a new user (no profile configured), guide them through setup:
 
 ### Step 1: Check Profile
 ```bash
-npm run dev -- profile
+npx boxel profile
 ```
 
 If no profile exists, run the interactive setup:
 
 ### Step 2: Add a Profile
 ```bash
-npm run dev -- profile add
+npx boxel profile add
 ```
 
 This launches an interactive wizard that:
 1. Asks for environment (Production or Staging)
 2. Asks for username and password
 3. Creates the profile in `~/.boxel-cli/profiles.json`
 
-**Non-interactive option:**
+**Non-interactive option (CI/automation only):**
 ```bash
-# Production
-npm run dev -- profile add -u @username:boxel.ai -p "password" -n "My Prod Account"
-
-# Staging
-npm run dev -- profile add -u @username:stack.cards -p "password" -n "My Staging Account"
+# Use environment variable to avoid exposing password in shell history
+BOXEL_PASSWORD="password" npx boxel profile add -u @username:boxel.ai -n "My Prod Account"
 ```
 
+> **Security Note:** Avoid passing passwords via `-p` flag as they appear in shell history and process listings. Use the interactive wizard or `BOXEL_PASSWORD` environment variable.
+
 ### Step 3: Verify & List Workspaces
 ```bash
-npm run dev -- list
+npx boxel list
 ```
 
 ### Step 4: First Sync
 Help them sync their first workspace:
 ```bash
-npm run dev -- sync @username/workspace ./workspace-name
+npx boxel sync @username/workspace ./workspace-name
 ```
 
 ### Switching Between Profiles
 ```bash
-npm run dev -- profile list              # See all profiles (★ = active)
-npm run dev -- profile switch username   # Switch by partial match
+npx boxel profile list              # See all profiles (★ = active)
+npx boxel profile switch username   # Switch by partial match
 ```
 
 ---
@@ -203,8 +204,8 @@ boxel skills --export ./project   # Export as Claude commands
 ```bash
 boxel profile                     # Show current active profile
 boxel profile list                # List all saved profiles (★ = active)
-boxel profile add                 # Interactive wizard to add profile
-boxel profile add -u @user:boxel.ai -p pass -n "Name"  # Non-interactive
+boxel profile add                 # Interactive wizard to add profile (recommended)
+# Non-interactive: use BOXEL_PASSWORD env var instead of -p flag for security
 boxel profile switch <username>   # Switch profile (partial match OK)
 boxel profile remove <profile-id> # Remove a profile
 boxel profile migrate             # Migrate from old .env file

.claude/commands/setup.md

@@ -5,70 +5,91 @@ Guide new users through Boxel CLI setup.
 ## Trigger
 Run this automatically when:
 - User first opens the repo
-- No `.env` file exists
+- No profile is configured (`npx boxel profile` shows nothing)
 - User asks about setup or getting started
 
 ## Flow
 
 ### 1. Check Current State
 ```bash
-cat .env 2>/dev/null || echo "NOT_CONFIGURED"
-npm list 2>/dev/null || echo "NOT_INSTALLED"
+npx boxel profile
 ```
 
-### 2. Ask Environment Choice
-Present options:
+If no profile exists, proceed with setup.
 
-**Production (app.boxel.ai)**
-- For live Boxel usage
-- Your real workspaces
+### 2. Add a Profile
 
-**Staging (realms-staging.stack.cards)**
-- For development/testing
-- Experimental features
+**Option A: Interactive (recommended)**
+```bash
+npx boxel profile add
+```
+
+This wizard will:
+1. Ask for environment (Production or Staging)
+2. Ask for username and password
+3. Create the profile automatically
 
-### 3. Collect Credentials
-Ask for:
+**Option B: Non-interactive (CI/automation)**
+
+Ask the user for:
+- **Environment**: Production (app.boxel.ai) or Staging (realms-staging.stack.cards)
 - **Username**: Their Boxel handle (e.g., `aallen90`, `ctse`). Found in Account panel as `@username:stack.cards` or in workspace URLs like `app.boxel.ai/username/workspace-name`
 - **Password**: Same as Boxel web login
 
-### 4. Create .env File
+Then run (using environment variable for security):
 
 **Production:**
-```env
-MATRIX_URL=https://matrix.boxel.ai
-MATRIX_USERNAME=<username>
-MATRIX_PASSWORD=<password>
-REALM_SERVER_URL=https://app.boxel.ai/
+```bash
+BOXEL_PASSWORD="password" npx boxel profile add -u @username:boxel.ai -n "Production"
 ```
 
 **Staging:**
-```env
-MATRIX_URL=https://matrix-staging.stack.cards
-MATRIX_USERNAME=<username>
-MATRIX_PASSWORD=<password>
-REALM_SERVER_URL=https://realms-staging.stack.cards/
+```bash
+BOXEL_PASSWORD="password" npx boxel profile add -u @username:stack.cards -n "Staging"
 ```
 
-### 5. Install & Verify
+> **Security Note:** Avoid passing passwords via `-p` flag as they appear in shell history.
+
+### 3. Verify
 ```bash
-npm install
-npm run dev -- list
+npx boxel list
 ```
 
-### 6. First Sync
+### 4. First Sync
 Help them sync a workspace:
 ```bash
-npm run dev -- sync @username/workspace
+npx boxel sync @username/workspace ./workspace-name
+```
+
+## Profile Management
+
+**List profiles:**
+```bash
+npx boxel profile list
+```
+
+**Switch profile:**
+```bash
+npx boxel profile switch <username>
+```
+
+**Migrate from old .env:**
+```bash
+npx boxel profile migrate
 ```
 
 ## Success Message
 ```
 Setup complete! You can now:
-- `boxel list` - See your workspaces
-- `boxel sync @username/workspace` - Sync a workspace
-- `boxel watch .` - Monitor for changes
-- `boxel history .` - View/restore checkpoints
+- `npx boxel list` - See your workspaces
+- `npx boxel sync @username/workspace` - Sync a workspace
+- `npx boxel watch .` - Monitor for changes
+- `npx boxel history .` - View/restore checkpoints
+
+Profile management:
+- `npx boxel profile` - Show active profile
+- `npx boxel profile list` - List all profiles
+- `npx boxel profile switch <name>` - Switch profiles
 
 For AI-assisted development, try:
 - `/watch` - Smart watch with auto intervals

README.md

@@ -4,7 +4,50 @@
 
 Edit Boxel cards locally with your IDE or AI agent, sync changes instantly, and collaborate seamlessly between web UI and local development.
 
-### Features
+> **Note:** Boxel CLI is developed and tested with [Claude Code](https://claude.ai/code). For the best experience, install Claude Code first and let it guide you through setup.
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/cardstack/boxel-cli.git
+cd boxel-cli
+npm install && npm run build
+```
+
+Now you can use `npx boxel` (or `boxel` after `npm link`):
+
+```bash
+npx boxel profile add              # Set up your account
+npx boxel list                     # List your workspaces
+npx boxel sync @user/workspace .   # Sync a workspace locally
+```
+
+### With Claude Code (Recommended)
+
+If you have [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed, just start it in the repo:
+
+```bash
+claude
+```
+
+Claude will detect the Boxel CLI project and guide you through setup automatically.
+
+### Global Command (Optional)
+
+To use `boxel` directly without `npx`:
+
+```bash
+npm link
+boxel profile add
+boxel list
+boxel sync .
+```
+
+---
+
+## Features
 
 - **Bidirectional Sync** - Push local changes, pull remote updates, resolve conflicts
 - **Track Mode** - Auto-checkpoint local edits as you type in your IDE
@@ -108,33 +151,20 @@ flowchart TB
 
 ---
 
-## Quick Start
-
-```bash
-# Install
-git clone https://github.com/cardstack/boxel-cli.git
-cd boxel-cli && npm install
-
-# Setup profile (interactive)
-npm run dev -- profile add
-
-# List workspaces
-npm run dev -- list
-
-# Sync a workspace
-npm run dev -- sync @username/workspace ./local-dir
-```
-
 ## Authentication
 
 ### Option 1: Profile Manager (Recommended)
 ```bash
-boxel profile add                    # Interactive setup
-boxel profile add -u @user:boxel.ai -p "pass" -n "Prod"  # Non-interactive
+boxel profile add                    # Interactive setup (recommended)
 boxel profile list                   # Show profiles (★ = active)
 boxel profile switch username        # Switch profile
+
+# Non-interactive (CI/automation only - avoid in shell history)
+BOXEL_PASSWORD="pass" boxel profile add -u @user:boxel.ai -n "Prod"
 ```
 
+> **Security Note:** Avoid passing passwords directly via `-p` flag as they may be exposed in shell history and process listings. Use the interactive wizard or environment variables for credentials.
+
 Profiles stored in `~/.boxel-cli/profiles.json`
 
 ### Option 2: Environment Variables
@@ -486,7 +516,7 @@ npm test                        # Run tests
 npm run lint                    # Check code style
 ```
 
-> **Note:** Use `npm run dev -- <command>` during development. After global install, use `boxel <command>`.
+> **Note:** Use `npm run dev -- <command>` during development (no rebuild needed). After build, use `npx boxel` or `boxel` (after `npm link`).
 
 ### Claude Code Integration
 

src/commands/check.ts

@@ -3,6 +3,7 @@ import * as path from 'path';
 import * as crypto from 'crypto';
 import { MatrixClient } from '../lib/matrix-client.js';
 import { RealmAuthClient } from '../lib/realm-auth-client.js';
+import { getProfileManager, formatProfileBadge } from '../lib/profile-manager.js';
 
 interface SyncManifest {
   workspaceUrl: string;
@@ -18,15 +19,22 @@ export async function checkCommand(
   filePath: string,
   options: { sync?: boolean }
 ): Promise<void> {
-  const matrixUrl = process.env.MATRIX_URL;
-  const matrixUsername = process.env.MATRIX_USERNAME;
-  const matrixPassword = process.env.MATRIX_PASSWORD;
+  // Get credentials from profile manager (falls back to env vars)
+  const profileManager = getProfileManager();
+  const credentials = await profileManager.getActiveCredentials();
 
-  if (!matrixUrl || !matrixUsername || !matrixPassword) {
-    console.error('Missing Matrix credentials in environment variables');
+  if (!credentials) {
+    console.error('No credentials found. Run "boxel profile add" or set environment variables.');
     process.exit(1);
   }
 
+  const { matrixUrl, username: matrixUsername, password: matrixPassword, profileId } = credentials;
+
+  // Show active profile if using one
+  if (profileId) {
+    console.log(`${formatProfileBadge(profileId)}\n`);
+  }
+
   // Resolve the file path
   const absolutePath = path.resolve(filePath);
 

src/commands/create.ts

@@ -1,4 +1,5 @@
 import { MatrixClient } from '../lib/matrix-client.js';
+import { getProfileManager, formatProfileBadge } from '../lib/profile-manager.js';
 
 interface CreateOptions {
   background?: string;
@@ -41,16 +42,23 @@ export async function createCommand(
   name: string,
   options: CreateOptions,
 ): Promise<void> {
-  const matrixUrl = process.env.MATRIX_URL;
-  const username = process.env.MATRIX_USERNAME;
-  const password = process.env.MATRIX_PASSWORD;
+  // Get credentials from profile manager (falls back to env vars)
+  const profileManager = getProfileManager();
+  const credentials = await profileManager.getActiveCredentials();
 
-  if (!matrixUrl || !username || !password) {
-    console.error('Missing Matrix credentials in environment variables');
+  if (!credentials) {
+    console.error('No credentials found. Run "boxel profile add" or set environment variables.');
     process.exit(1);
   }
 
-  let realmServerUrl = process.env.REALM_SERVER_URL;
+  const { matrixUrl, username, password, realmServerUrl: baseRealmServerUrl, profileId } = credentials;
+
+  // Show active profile if using one
+  if (profileId) {
+    console.log(`${formatProfileBadge(profileId)}\n`);
+  }
+
+  let realmServerUrl = baseRealmServerUrl;
   if (!realmServerUrl) {
     const matrixUrlObj = new URL(matrixUrl);
     if (matrixUrlObj.hostname.startsWith('matrix-')) {