CLI tool for Spck Editor - provides remote filesystem, git, and terminal access over WebSocket.

Connect your local development environment to Spck Editor mobile app and access local files, git operations, and terminal sessions remotely.

• 🗂️ Remote Filesystem - Access local files from Spck Editor mobile app
• 🔄 Git Integration - Full git operations over the network connection (requires Git 2.20.0+)
• 💻 Terminal Access - Interactive terminal sessions with xterm.js
• 🔍 Fast Search - Optimized file search with automatic ripgrep detection (100x faster when installed)
• 🔒 Secure - Cryptographically signed requests with optional Firebase authentication

• Node.js: 18.0.0 or higher
• Operating System: Linux, macOS, or Windows
• Spck Editor Account: Premium subscription required
• Spck Editor Mobile App: Required for QR code connection (Android/iOS)

• Git: 2.20.0 or higher - Required for git integration features (commit, push, pull, branch management)

  • Check version: git --version
  • Install:
    • macOS: brew install git (via Homebrew)
    • Ubuntu/Debian: sudo apt-get install git
    • Windows: Download from git-scm.com

• ripgrep: 15.0.0 or higher - Dramatically improves search performance (100x faster than default search)

  • Check version: rg --version
  • Install:
    • macOS: brew install ripgrep
    • Ubuntu/Debian: sudo apt-get install ripgrep
    • Windows: choco install ripgrep (via Chocolatey) or download from GitHub releases
  • Note: The CLI will automatically detect and use ripgrep if available, falling back to Node.js search if not installed

No installation required - run directly using npx:

npx spck

Install the CLI globally to use it from anywhere:

npm install -g spck
spck

On first run, the CLI will guide you through:

1. Firebase Authentication - Sign in with your Spck Editor account
2. Configuration Setup - Choose root directory and settings
3. Git Configuration (Advanced) - Optionally add .spck-editor/ to .gitignore

The setup wizard will:

• Detect if a .gitignore file exists in your project
• Prompt you to automatically add .spck-editor/ to prevent committing the symlink
• Create or update .gitignore with proper comments

To reconfigure or run the setup wizard manually:

spck --setup

Once running, the CLI displays a QR code and connection details.

IMPORTANT: The Spck Editor mobile app must be installed BEFORE scanning the QR code. The QR code contains a custom spck:// deep link that only works with the app installed.

On Android:

1. Install Spck Editor from Google Play Store if not already installed
2. Use your device's built-in QR scanner:
   • Open the Camera app and point it at the QR code, OR
   • Swipe down from the top and tap the QR code scanner in Quick Settings
3. When the QR code is detected, Android will show a notification to open with Spck Editor
4. Tap the notification to open Spck Editor
5. The app will automatically parse the connection details and connect

On iOS:

1. Install Spck Editor from the App Store if not already installed
2. Use your device's built-in QR scanner:
   • Open the Camera app and point it at the QR code, OR
   • Open Control Center and tap the QR code scanner icon
3. When the QR code is detected, iOS will show a notification to open with Spck Editor
4. Tap the notification to open Spck Editor
5. The app will automatically parse the connection details and connect

Note: Spck Editor does NOT have a built-in QR scanner. You must use your device's native QR scanning capability (camera or system scanner).

If the QR code doesn't work or you prefer manual entry:

1. Open Spck Editor mobile app
2. Tap Projects → New Project → Link Remote Server
3. Enter the Client ID and Secret shown below the QR code in your terminal
4. Tap Connect

Once connected, you can browse and edit your local files from the mobile app!

# Start the CLI with default settings
spck

# Run interactive setup wizard
spck --setup

# Show account information
spck --account

# Logout and clear credentials
spck --logout

# Show help
spck --help

# Show version
spck --version

# Use custom configuration file
spck --config /path/to/config.json
spck -c /path/to/config.json

# Override root directory
spck --root /path/to/project
spck -r /path/to/project

The configuration is stored in .spck-editor/config/spck-cli.config.json in your project directory.

Important: .spck-editor/config is a symlink to ~/.spck-editor/projects/{project_id}/, which keeps your secrets outside the project directory and prevents accidental git commits. Other files like logs and temporary data are stored locally in .spck-editor/.tmp, .spck-editor/.trash, and .spck-editor/logs.

Default Configuration:

{
  "version": 1,
  "root": "/path/to/your/project",
  "name": "My Project",
  "terminal": {
    "enabled": true,
    "maxBufferedLines": 5000,
    "maxTerminals": 10
  },
  "security": {
    "userAuthenticationEnabled": false
  },
  "filesystem": {
    "maxFileSize": "10MB",
    "watchIgnorePatterns": [
      "**/.git/**",
      "**/.spck-editor/**",
      "**/node_modules/**",
      "**/*.log",
      "**/.DS_Store",
      "**/dist/**",
      "**/build/**"
    ]
  }
}

• terminal.enabled (boolean): Enable/disable terminal access
  • Default: true
• terminal.maxBufferedLines (number): Maximum scrollback buffer lines
  • Default: 10000
• terminal.maxTerminals (number): Maximum concurrent terminal sessions
  • Default: 10

• security.userAuthenticationEnabled (boolean): Enable Firebase user authentication
  • Default: false
  • When true: Requires Firebase account login (adds user identity verification, adds latency (2-20s) to initial connection)
  • When false: Requests still protected by secret signing key (lower latency, compatible with Spck Editor Lite)
  • Note: All requests are always cryptographically signed regardless of this setting

• filesystem.maxFileSize (string): Maximum file size for read/write operations
  • Default: "10MB"
  • Accepts: "5MB", "50MB", etc.
• filesystem.watchIgnorePatterns (string[]): Glob patterns to ignore when watching files
  • Default: Ignores node_modules, .git, dist, build

The CLI uses a secure storage system that prevents accidentally committing secrets to git:

• User Credentials (Global): ~/.spck-editor/.credentials.json

  • Contains: Firebase refresh token and user ID
  • Persisted across all projects
  • Stored securely in your home directory

• Project Data (Per-Project): ~/.spck-editor/projects/{project_id}/

  • Contains: Configuration and connection settings for each project
  • Each project gets a unique ID based on its path
  • Stored securely outside your project directory

• Project Directory: .spck-editor in your project directory

  • Regular directory containing local data (.tmp, .trash, logs)
  • The config subdirectory is a symbolic link pointing to ~/.spck-editor/projects/{project_id}/
  • Automatically created by the CLI
  • Prevents secrets from being committed to git

Files stored in the symlinked config directory (.spck-editor/config/):

• spck-cli.config.json - Project configuration
• connection-settings.json - Server token, client ID, and secret signing key

Files stored locally (.spck-editor/):

• .tmp/ - Temporary files
• .trash/ - Deleted files
• logs/ - CLI operation logs

The maximum number of simultaneous CLI connections depends on your account type. When the limit is reached, you'll see:

⚠️  Maximum of X CLI connections reached.
Close other CLI instances and try again.

Note: Only one Spck Editor mobile app can connect to a CLI instance at a time. Each CLI instance uses one connection slot.

To manage multiple projects simultaneously, run separate CLI instances (up to your account limit).

Spck CLI is designed with security as a priority. Multiple layers of protection ensure your local files and development environment remain secure.

All communication between the CLI and Spck Editor mobile app is encrypted:

• WSS (WebSocket Secure): All WebSocket connections use TLS/SSL encryption
• HTTPS: All HTTP requests to the proxy server use HTTPS
• End-to-End Protection: Data is encrypted in transit from your computer to the mobile app

This ensures that even if network traffic is intercepted, your files and credentials cannot be read by third parties.

Spck CLI uses a two-layer security model:

All requests are cryptographically signed using a secret signing key:

• Never Transmitted: The secret key is generated locally and never sent over the network
• Local Signing: Every request is signed locally before transmission
• Signature Verification: The server verifies the signature to ensure requests are authentic
• Per-Connection Secret: Each CLI connection generates a unique cryptographically secure random secret

This base layer ensures that even without user authentication, only someone with access to the secret can make requests to your CLI instance.

User authentication provides an additional layer of identity verification:

Configuration Option:

{
  "security": {
    "userAuthenticationEnabled": true
  }
}

When Enabled:

• You must sign in with your Spck Editor account
• Connections use Firebase ID tokens that expire after 1 hour
• Expired tokens are automatically refreshed using secure refresh tokens
• Adds verification that the connecting user is using the same account as the CLI

Trade-offs:

• Pros: Adds user identity verification, prevents unauthorized access even if secret is compromised
• Cons: Adds latency to initial connection due to Firebase authentication
• Compatibility: Not supported by Spck Editor Lite

When Disabled:

• Requests are still protected by the secret signing key
• No additional latency from Firebase authentication
• Compatible with Spck Editor Lite
• Recommended for local development or when latency is a concern

Note: Even with user authentication disabled, all requests remain cryptographically signed and protected.

Each CLI connection has unique security credentials:

• Client ID: Unique identifier for each CLI instance (keep this secret for anonymity, attacker must be able to guess your Client ID to connect)
• Secret: Cryptographically secure random secret (generated per connection, never transmitted through the internet)
• Server Token: Time-limited token that expires after 24 hours

The Client ID and Secret are stored in .spck-editor/config/connection-settings.json and should never be shared publicly. Anyone with access to these credentials can connect to your CLI instance if userAuthenticationEnabled is also disabled.

Terminal access can be disabled entirely if you only need filesystem and git operations:

Configuration Option:

{
  "terminal": {
    "enabled": false
  }
}

When terminal.enabled is set to false:

• No terminal sessions can be created
• The CLI will not spawn any shell processes
• Only filesystem and git operations are available

This reduces the attack surface if you don't need terminal functionality.

1. Protect Connection Credentials

   • Automatic Git Protection: The setup wizard will detect .gitignore and offer to add .spck-editor/ automatically
   • If you skipped the setup prompt, manually add to .gitignore:

     .spck-editor/
     

   • Security by Design: Project secrets are stored in ~/.spck-editor/projects/{project_id}/ via the .spck-editor/config symlink
   • Never share or commit files from ~/.spck-editor/ (contains secret signing keys and tokens)
   • If user authentication is enabled, keep ~/.spck-editor/.credentials.json private

2. Logout on Shared Machines

   • Always run spck --logout when done on shared computers
   • This clears all authentication tokens and connection settings

3. Review Active Connections

   • Use spck --account to view active connections
   • Close unused CLI instances to free connection slots

4. Limit Exposed Directories

   • Use --root to specify the minimum necessary directory
   • Don't expose your entire home directory or system root

5. Monitor Terminal Sessions

   • Be aware of which terminal sessions are active
   • Close unused terminals when done
   • Configure terminal.maxTerminals to limit concurrent sessions

6. Firewall Configuration

   • Ensure WebSocket connections (WSS) are allowed through your firewall
   • The CLI connects to a regional relay server over WSS (port 443)

The CLI operates with your local user permissions:

• Files are read/written with your user's file system permissions
• Terminal sessions run with your user account privileges
• No privilege escalation occurs

The CLI only transmits data explicitly requested by Spck Editor app:

• File Operations: File contents only when you open/save files
• Git Operations: Git metadata and repository data during git commands
• Terminal I/O: Terminal input/output during active sessions
• File Watching: File change notifications (paths only, not contents)

If the root directory doesn't exist:

# Reconfigure with correct path
spck --setup

Or manually specify the path:

spck --root /correct/path/to/project

If configuration files are corrupted:

# Clear settings and start fresh
spck --logout
spck --setup

If the CLI cannot connect to the proxy server:

1. Check internet connection
2. Try logging out and reconnecting:

   spck --logout
   spck

3. Check firewall settings - ensure WebSocket connections are allowed

If git operations (commit, push, pull, etc.) are not working:

1. Verify Git is installed:

   git --version

   • Required: Git 2.20.0 or higher
   • If not installed, see installation instructions in the Requirements section

2. Check repository initialization:

   cd /path/to/project
   git status

   • If not a git repository, initialize it: git init

If file search is slow:

1. Install ripgrep for 100x faster search:

   # macOS
   brew install ripgrep
   
   # Ubuntu/Debian
   sudo apt-get install ripgrep
   
   # Windows (Chocolatey)
   choco install ripgrep

2. Verify installation:

   rg --version

   • The CLI will automatically detect and use ripgrep if available

Add .spck-editor/ to .gitignore manually:

If you skipped the setup wizard prompt or need to add it manually:

# Append to .gitignore
echo ".spck-editor/" >> .gitignore

Or add it with a comment for clarity:

cat >> .gitignore << 'EOF'

# Spck CLI project data
.spck-editor/
EOF

Re-run setup to trigger .gitignore prompt:

spck --setup

The setup wizard will detect your .gitignore and offer to add the entry automatically.

# Start in current directory
cd /path/to/project
spck

# Start with specific root directory
spck --root /path/to/project

# Terminal 1: Project A
cd /path/to/projectA
spck

# Terminal 2: Project B
cd /path/to/projectB
spck

Each project maintains its own configuration and connection.

# Use custom config file
spck --config ~/my-custom-config.json

# Override root directory
spck --root ~/projects/myapp

# Clone the repository
cd cli
npm install
npm run build

npm test
npm run test:coverage

MIT License - see LICENSE file for details.

• Website: https://spck.io
• Download: Spck Editor on Google Play | Spck Editor on App Store

For help and support, visit spck.io or contact support through the mobile app.

Made with ❤️ by the Spck Editor team