LQ CLI (@liquisio/git-cli)

Git-like GitHub sync tool for Wix Blocks - Simple commands to push and pull code with smart conflict detection.

Perfect for reconnecting Wix Blocks projects after container resets or when git connection is lost.

Commands: lqcli or lq

Features

• Git-like Commands - Simple push, pull, watch, status commands (no menus)
• Smart Conflict Detection - Fails safely when files conflict, with clear error messages
• Conflict Resolution Strategies - Use --ours or --theirs to resolve pull conflicts
• Automatic Backups - Timestamped backups before any operation
• Watch Mode - Auto-pull changes from remote every 60 seconds
• Clean Push - Replace remote history with --clean flag
• Auto-generated Commits - Timestamped commit messages

Installation

Option 1: Use with npx (Recommended)

No installation needed:

npx @liquisio/git-cli --help

Option 2: Install Globally

npm install -g @liquisio/git-cli
lqcli --help

Option 3: Install Locally

npm install @liquisio/git-cli
npx lqcli --help

Option 4: Read-Only File Systems (Wix Blocks, Containers)

If you're in a read-only environment:

npm install @liquisio/git-cli --cache=/tmp/.npm
npx lqcli --help

Configuration

Create a lqcli.config.mjs file in your project (can be in root or src/ directory):

export default {
  git: {
    name: 'Your Name',
    email: '[email protected]',
    user: 'your-github-username',
    repo: 'your-repo-name',
  },
};

Create a .env file in the same directory:

LQCLI_TOKEN=github_pat_your_token_here

Note: The src path is auto-detected from ./src or /user-code/src.

Configuration Options

All options except the required git fields have sensible defaults.

// lqcli.config.mjs - Full configuration reference
export default {
  // === REQUIRED ===
  git: {
    name: 'Your Name',           // Git commit author name
    email: '[email protected]',    // Git commit author email
    user: 'github-username',     // GitHub username
    repo: 'repo-name',           // GitHub repository name
  },

  // === OPTIONAL: Git Settings ===
  // git: {
  //   remote: 'origin',         // Git remote name (default: 'origin')
  //   branch: 'main',           // Git branch name (default: 'main')
  //   tempBranch: 'fresh-start', // Temp branch for init command
  // },

  // === OPTIONAL: Paths ===
  // paths: {
  //   root: '/user-code',       // Project root (default: '/user-code')
  //   src: '/user-code/src',    // Source directory (auto-detected)
  //   backup: '/user-code/backup', // Backup directory
  // },

  // === OPTIONAL: Backup Settings ===
  // backup: {
  //   prefix: 'src_',           // Backup folder prefix (default: 'src_')
  // },

  // === OPTIONAL: Watch Mode ===
  // watch: {
  //   interval: 60000,          // Auto-pull interval in ms (default: 60s)
  // },

  // === OPTIONAL: Timeouts ===
  // timeouts: {
  //   git: 10000,               // Git operations timeout in ms (default: 10s)
  // },

  // === OPTIONAL: Prefixes ===
  // prefixes: {
  //   commitMessage: 'lq:',     // Auto-commit message prefix
  //   historyBranch: 'history_', // History branch prefix for force push
  // },

  // === OPTIONAL: Skip Directories ===
  // Directories to exclude from push/pull operations
  // Default: ['site', 'node_modules', 'backup']
  // skipDirectories: ['site', 'node_modules', 'backup', 'generated'],

  // === OPTIONAL: Tracked Extensions ===
  // File extensions to track (others are gitignored)
  // Default: ['.js', '.mjs', '.ts', '.jsx', '.tsx', '.json', '.css', ...]
  // trackedExtensions: ['.js', '.ts', '.json', '.css', '.html'],
};

| Option | Default | Description | |--------|---------|-------------| | git.name | (required) | Git commit author name | | git.email | (required) | Git commit author email | | git.user | (required) | GitHub username | | git.repo | (required) | GitHub repository name | | git.remote | 'origin' | Git remote name | | git.branch | 'main' | Git branch name | | paths.root | '/user-code' | Project root directory | | paths.src | (auto-detected) | Source directory | | backup.prefix | 'src_' | Backup folder prefix | | watch.interval | 60000 | Watch mode interval (ms) | | timeouts.git | 10000 | Git operation timeout (ms) | | skipDirectories | ['site', 'node_modules', 'backup'] | Directories to skip |

GitHub Personal Access Token

A GitHub token is required to connect to your repository.

How to generate a token:

1. Visit: https://github.com/settings/personal-access-tokens
2. Click "Generate new token"
3. Give it a name (e.g., "LQ CLI" or "Wix Blocks")
4. Repository access: Select only the repository you need
5. Permissions: Repository permissions → Contents: Read and write
6. Generate and copy the token
7. Add it to your .env file as LQCLI_TOKEN=...

Security:

• Token is stored in .env file (should be gitignored)
• Config file (lqcli.config.mjs) can be committed (no secrets)
• Never commit your .env file to version control
• Give token access to specific repos only

Usage

Commands

lqcli                # Show help
lqcli push           # Push local code to GitHub
lqcli pull           # Pull GitHub code to local
lqcli status         # Show differences between local and remote
lqcli watch          # Auto-pull every 60 seconds
lqcli restore        # Restore files from latest backup
lqcli config         # Manage configuration

Global Options

lqcli --help         # Show help message
lqcli --version      # Show version number
lqcli --logs         # Show verbose/debug output

Push

Push local code to GitHub:

lqcli push           # Push with auto-generated commit message
lqcli push -m "msg"  # Push with custom commit message
lqcli push --clean   # Clean push (replace remote history)
lqcli push -c        # Short form of --clean
lqcli push --logs    # Show detailed output

Normal push (preserves history):

1. Creates backup of local files
2. Fetches remote history (preserves commit history)
3. Copies your local files on top
4. Commits with auto-generated message: lq: push 2026-01-31 14:23:45
5. Pushes to GitHub

Clean push (--clean or -c flag):

1. Creates backup of local files
2. Saves existing remote history to history_<timestamp> branch
3. Replaces remote with local files (fresh commit, no history)
4. Force pushes to GitHub

Use clean push when you want to start fresh or when normal push fails due to diverged histories.

Pull

Pull GitHub code to local:

lqcli pull           # Pull from remote
lqcli pull --ours    # Keep local files when conflicts exist
lqcli pull --theirs  # Keep remote files when conflicts exist

What happens:

1. Creates backup of local files
2. Checks for conflicts with remote
3. If conflicts exist: fails with error (use --ours or --theirs)
4. Resets to remote HEAD
5. Preserves local-only files (files not on GitHub)

Conflict handling:

Error: Cannot pull - 3 file(s) would be overwritten:
   src/backend/config.js
   src/backend/utils.js
   src/backend/api.js

Use 'lqcli push' to save local changes first, or use '--ours' / '--theirs'.

Status

Show differences between local and remote:

lqcli status         # Show file differences
lqcli status --logs  # Show detailed diff information

Watch Mode

Auto-pull from remote every 60 seconds:

lqcli watch

Controls:

• Ctrl+C - Stop watching

Output (with --logs):

Watch mode started. Auto-pulling every 60s. Ctrl+C to exit.

[14:23:45] Already up to date
[14:24:45] Pulling changes...
[14:24:46] Pulled successfully

Restore

Restore files from the latest backup:

lqcli restore

Backups are stored in ./backup/src_YYYY-MM-DD_HH-MM-SS/.

Config

Manage configuration:

lqcli config         # Show current configuration (default)
lqcli config show    # Show current configuration
lqcli config init    # Generate config file templates
lqcli config path    # Show path to loaded config file

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 10 | Config file missing | | 11 | Config file invalid | | 20 | Git not installed | | 21 | Git operation error | | 30 | Conflict detected | | 40 | Authentication error | | 50 | Backup error |

File Comparison (with --logs)

When using --logs, you'll see file comparison details:

3 file(s) differ from remote
  - src/backend/config.js
  - src/backend/utils.js
  - src/backend/api.js
2 file(s) only on local
1 file(s) only on remote

Safety Features

• Automatic Backups: Creates timestamped backup before any operation
• Atomic Operations: Push uses temp directory snapshot; restores on failure
• Token Security: Stored in gitignored .env file; fully redacted in logs
• Conflict Detection: Pull fails safely on conflicts (no silent overwrites)
• Conflict Resolution: Use --ours or --theirs flags to resolve conflicts
• Whitespace Detection: Whitespace-only changes are detected (not silently ignored)
• Backup Restore: Easy recovery with lqcli restore
• Site Folder Preserved: site/ folder is never touched (configurable via skip directories)
• Smart Local File Handling: Pull preserves local-only files that exist NOW (won't resurrect deleted files)
• Corrupted Git Recovery: Automatically detects and fixes corrupted .git directories
• UTF-16 Support: Properly handles UTF-16 encoded files (not falsely detected as binary)

File Structure

@liquisio/git-cli/
├── dist/
│   └── index.js              # Bundled CLI (published to npm)
├── src/
│   ├── cli/
│   │   ├── index.js          # CLI orchestrator (Commander.js)
│   │   ├── presenter.js      # UI/display layer
│   │   └── commands/         # Command handlers
│   ├── services/             # Business logic
│   ├── adapters/             # External dependencies
│   ├── domain/               # Pure functions
│   └── types/                # Types and constants
├── scripts/
│   ├── lqinit.sh             # Install helper for Wix Blocks
│   └── setup-tests           # Sets up test environment
├── lqcli.config.mjs           # Example configuration
├── package.json
└── README.md

Development

Local Development

# Install dependencies
npm install

# Run from source
npm run dev

# Run with arguments
npm run dev -- push
npm run dev -- --logs

Testing

# Unit tests
npm run test:unit

# E2E tests (setup required)
mkdir -p /tmp/lq-test && cd /tmp/lq-test
/path/to/lq-cli/scripts/setup-tests

# Run all E2E tests
npm test

# Run individual test suites
npm run test:cli      # CLI basics
npm run test:push     # Push command
npm run test:pull     # Pull command
npm run test:init     # Clean push command
npm run test:bugs     # Edge case/bug fix tests

Build & Test

# Build bundle
npm run build

# Test bundle
node dist/index.js

# Create tarball
npm pack

Publishing

# Version bump
npm version patch  # 1.0.0 → 1.0.1

# Publish (runs build automatically)
npm publish

Requirements

• Node.js >= 18
• Git installed on system

License

MIT

Author

Varun Dev [email protected]