Spck CLI

Overview

Spck CLI is a command-line tool that connects your local development environment to the Spck Editor mobile app. It provides remote filesystem access, git integration, and terminal sessions over a secure WebSocket connection, enabling you to edit local files from your mobile device.

Key Features

Requirements

Required

Optional (Recommended)

Installation

Option 1: Run with npx (No Installation)

npx spck

Always uses the latest version, perfect for first-time setup.

Option 2: Global Installation

npm install -g spck
spck

Faster startup, works offline, convenient for daily use.

That's it, now your current working directory can be accessed by Spck Editor mobile app by scanning the QR code displayed in the terminal.

First-Time Setup

When you first run the CLI, an interactive setup wizard guides you through:

1. Authentication

spck
# Press ENTER to open browser
# Sign in with your Spck Editor account
# Authorize the CLI
# Return to terminal

Credentials are stored in ~/.spck-editor/.credentials.json and persist across sessions.

2. Project Configuration

The wizard will configure:

3. Git Integration (Optional)

If a .gitignore file is detected, the CLI offers to add .spck-editor/ to prevent committing secrets:

Add .spck-editor/ to .gitignore? (Y/n)

Recommendation: Choose Y to protect connection credentials.

Re-run Setup

To reconfigure at any time:

spck --setup

Connecting to Spck Editor

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

Method 1: QR Code (Recommended)

IMPORTANT: Install Spck Editor app BEFORE scanning the QR code.

On Android:

  1. Use Camera app or Quick Settings QR scanner
  2. When detected, tap notification to open Spck Editor
  3. App automatically connects

💡 Note: Some QR code scanners cannot handle the custom scheme to open Spck Editor directly. Copy the url and paste it in Chrome which will launch Spck Editor from the url.

On iOS:

  1. Use Camera app or Control Center QR scanner
  2. When detected, tap notification to open Spck Editor
  3. App automatically connects

💡 Note: Spck Editor does NOT have a built-in QR scanner. Use your device's native QR capability.

Method 2: Manual Entry

If QR code doesn't work:

  1. Open Spck Editor → Projects → New Project → Link Remote Server
  2. Enter Client ID and Secret shown in terminal
  3. Tap Connect

Relay Server

The CLI connects to Spck Editor through a relay server that forwards messages between the two. On first run, the CLI automatically selects the relay server with the lowest latency and saves the preference to ~/.spck-editor/.credentials.json.

IMPORTANT: Both the CLI and the Spck Editor client must use the same relay server to connect. If the client cannot find the CLI, verify that both sides have selected the same relay server.

Available Relay Servers

Region URL
Europe cli-eu-1.spck.io
North America cli-na-1.spck.io
South Asia cli-sas-1.spck.io
East Asia cli-ea-1.spck.io

Overriding the Relay Server

# Use a specific relay server
spck --server cli-eu-1.spck.io

# Short form
spck -s cli-na-1.spck.io

The override is saved and reused on subsequent runs. To re-run auto-selection, clear your credentials and restart:

spck --logout
spck

Choosing a Relay Server in Spck Editor

When connecting from the mobile app via Link Remote Server, select the same relay server from the Relay Server dropdown that the CLI is using. The relay server name is displayed in the CLI output after connecting.

CLI Commands

Basic Commands

# Start the CLI
spck

# Run setup wizard
spck --setup

# Show account information
spck --account

# Logout and clear credentials
spck --logout

# Show help
spck --help

# Show version
spck --version

Advanced Options

# 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

# Override relay server (e.g., use a specific region)
spck --server cli-eu-1.spck.io
spck -s cli-na-1.spck.io

Configuration

Configuration File Location

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}/, keeping secrets outside your project directory.

Default Configuration

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

Key Configuration Options

Terminal Settings

Security Settings

Filesystem Settings

Security

Encrypted Connections

All communication uses:

Request Signing

Every request is cryptographically signed:

Best Practices

  1. Protect credentials:

    # Add to .gitignore (automatic during setup)
echo ".spck-editor/" >> .gitignore

  2. Logout on shared machines:

    spck --logout

  3. Limit exposed directories:

    # Instead of entire home directory
spck --root /path/to/specific/project

  4. Disable terminal if not needed:

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

Daily Workflow

Starting Your Session

cd /path/to/project
spck
# Connect from mobile app (auto-connects to saved server)
# Start coding

Editing Files

  1. Browse files in mobile app
  2. Tap to open and edit
  3. Files save automatically to your computer

Running Git Commands

Option 1 - Mobile App GUI:

Option 2 - Terminal:

git status
git add .
git commit -m "Update feature"
git push

Terminal Sessions

Tap terminal icon in mobile app for full shell access with your user permissions.

Ending Your Session

# Keep CLI running for quick reconnects (recommended)
# Or stop with Ctrl+C

Troubleshooting

Root Directory Not Found

# Reconfigure with correct path
spck --setup

# Or specify directly
spck --root /correct/path/to/project

Corrupted Configuration

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

Connection Issues

  1. Check internet connection
  2. Verify both the CLI and Spck Editor are using the same relay server (shown in CLI output after connecting)
  3. Try logging out and reconnecting:
    spck --logout
spck
  4. Check firewall settings - ensure WebSocket connections (port 443) are allowed

QR Code Not Scanning

Solutions:

Git Operations Not Working

  1. Verify Git is installed:

    git --version  # Requires 2.20.0+

  2. Install if needed:

    # macOS
brew install git

# Ubuntu/Debian
sudo apt-get install git

# Windows: Download from git-scm.com

Slow Search Performance

Install ripgrep for 100x faster search:

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt-get install ripgrep

# Windows (Chocolatey)
choco install ripgrep

# CLI automatically detects and uses ripgrep

High CPU Usage

  1. Reduce file watching by adding more ignore patterns:

    {
  "filesystem": {
    "watchIgnorePatterns": [
      "**/.git/**",
      "**/.spck-editor/**",
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**",
      "**/.next/**",
      "**/coverage/**",
      "**/.cache/**"
    ]
  }
}

  2. Limit concurrent terminals:

    {
  "terminal": {
    "maxTerminals": 5
  }
}

Permission Denied

Check file permissions:

# View permissions
ls -la /path/to/file

# Fix if needed
chmod 644 /path/to/file

# Don't use sudo - CLI should run as the user who owns the files

AI Coding Agents

The Spck CLI terminal gives you full shell access, which means you can run AI coding agents directly from your mobile device. These agents can read, write, and refactor code in your project while you supervise from Spck Editor.

💡 Tip: Use tmux to keep AI agent sessions running even after you disconnect. Start a tmux session on your desktop (tmux new -s code), launch the AI agent, then reattach from the Spck CLI terminal on your phone (tmux attach -t code). This lets you seamlessly switch between desktop and mobile without losing context.

Advanced Usage

Multiple Projects

Run separate CLI instances:

# 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.

Custom Configuration Files

Create specialized configs for different scenarios:

# Development config
spck --config ~/configs/dev-config.json

# Production config (read-only, no terminal)
spck --config ~/configs/prod-config.json

Environment-Specific Setup

Local Development:

{
  "security": {
    "userAuthenticationEnabled": false
  },
  "terminal": {
    "enabled": true
  }
}

Production Server:

{
  "security": {
    "userAuthenticationEnabled": true
  },
  "terminal": {
    "enabled": false
  }
}

Connection Limits

The maximum number of simultaneous CLI connections depends on your account type. When the limit is reached:

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

Check active connections:

spck --account

💡 Note: Only one mobile device can connect to a CLI instance at a time. Each CLI instance uses one connection slot.

Support and Resources

Next Steps

  1. Explore mobile app features: File browser, git panel, terminal, search
  2. Customize configuration: Adjust terminal, security, and filesystem settings
  3. Optimize performance: Install ripgrep, configure watch patterns
  4. Learn advanced features: Custom automation, environment-specific setups

For complete documentation with detailed explanations of all configuration options, troubleshooting steps, and advanced usage, see the full Getting Started Guide.