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

$3

No installation needed:

``bash
npx @liquisio/git-cli --help
`

$3

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

$3

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

$3

If you're in a read-only environment:

`bash
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):

`javascript
export default {
git: {
name: 'Your Name',
email: 'your.email@example.com',
user: 'your-github-username',
repo: 'your-repo-name',
},
};
`

Create a .env file in the same directory:

`bash
LQCLI_TOKEN=github_pat_your_token_here
`

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

$3

All options except the required git fields have sensible defaults.

`javascript
// lqcli.config.mjs - Full configuration reference
export default {
// === REQUIRED ===
git: {
name: 'Your Name', // Git commit author name
email: 'you@example.com', // 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 |

$3

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

$3

`bash
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
`

$3

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

$3

Push local code to GitHub:

`bash
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_ 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.

$3

Pull GitHub code to local:

`bash
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'.
`

$3

Show differences between local and remote:

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

$3

Auto-pull from remote every 60 seconds:

`bash
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
`

$3

Restore files from the latest backup:

`bash
lqcli restore
`

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

$3

Manage configuration:

`bash
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

$3

`bash


Install dependencies

npm install

Run from source

npm run dev

Run with arguments

npm run dev -- push
npm run dev -- --logs
`

$3

`bash


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
`

$3

`bash


Build bundle

npm run build

Test bundle

node dist/index.js

Create tarball

npm pack
`

Publishing

`bash


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