Terminal Layout Sync CLI

A CLI tool for developers to save, restore, and sync terminal workspace layouts across machines. Captures tmux/screen/iTerm2 configurations and enables easy recreation or cloud sync via dotfiles.

Overview

Terminal Layout Sync helps you:

• Save your current terminal workspace layout to a config file
• Restore saved layouts to new or existing terminal sessions
• Import/Export layouts as portable JSON files
• Sync layouts between machines via git/dotfiles
• Templates - use predefined layouts for common development scenarios

Installation

# Clone the repository
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/terminal-layout-sync.git
cd terminal-layout-sync

# Install dependencies
npm install

# Build the project
npm run build

# Install globally (optional)
npm install -g .

Usage

Basic Commands

# Save current terminal layout
terminal-layout-sync save

# Restore a saved layout
terminal-layout-sync restore my-layout

# List all saved layouts
terminal-layout-sync list

# Export a layout to a file
terminal-layout-sync export my-layout -o my-layout.json

# Import a layout from a file
terminal-layout-sync import my-layout.json

Command Options

Save

terminal-layout-sync save [options]

Options:
  -n, --name <name>         Layout name
  -t, --terminal <type>     Terminal type (tmux, screen, iterm2)
  -s, --session <name>      Session name to capture
  -f, --format <format>     Output format (json, yaml)
  -d, --description <desc>  Layout description
  --tags <tags>             Tags (comma-separated)

Restore

terminal-layout-sync restore [name] [options]

Options:
  -s, --session <name>   Session name to restore to
  -a, --attach           Show attach command after restore
  --dry-run              Show commands without executing

List

terminal-layout-sync list [options]

Options:
  -f, --format <format>   Output format (table, json)
  -v, --verbose           Show verbose output

Import/Export

# Export a layout
terminal-layout-sync export [name] -o output.json

# Import a layout
terminal-layout-sync import <file> -n new-name

Sync with Git

# Initialize git repo for layouts
terminal-layout-sync sync --init --remote https://github.com/user/layouts.git

# Push changes
terminal-layout-sync sync --push

# Pull changes
terminal-layout-sync sync --pull

Templates

# List available templates
terminal-layout-sync template --list

# Apply a template with variables
terminal-layout-sync template --apply dev --var PROJECT_DIR=/path/to/project

# Create a template from a saved layout
terminal-layout-sync template --create

Configuration

Environment Variables

Variable	Description	Default
TERMINAL_LAYOUT_DIR	Directory to store layouts	~/.config/terminal-layouts
TERMINAL_LAYOUT_DEFAULT_FORMAT	Default format for layout files	json
GIT_SYNC_ENABLED	Enable git sync feature	true

Configuration File

Located at ~/.config/terminal-layouts/config.json:

{
  "layoutDir": "~/.config/terminal-layouts/layouts",
  "defaultFormat": "json",
  "gitSyncEnabled": true,
  "templatesDir": "~/.config/terminal-layouts/templates"
}

Templates

Built-in templates are included for common scenarios:

Development (dev)

Standard development environment with editor and terminals.

Variables:

• PROJECT_DIR - Project root directory
• EDITOR - Default editor command

Debug (debug)

Layout for debugging applications with multiple terminal panes.

Variables:

• PROJECT_DIR - Project root directory
• SERVER_URL - Debug server URL
• LOG_LEVEL - Logging level

Production (prod)

Production environment monitoring and management layout.

Variables:

• ENVIRONMENT - Production environment name
• SERVER_HOST - Server hostname
• SSH_USER - SSH username

Examples

Save and Restore Workflow

# In your current tmux session
terminal-layout-sync save --name my-dev-setup --description "My daily development setup"

# On another machine or new terminal
terminal-layout-sync restore my-dev-setup

Cross-Machine Sync

# On machine A
terminal-layout-sync sync --init --remote git@github.com:user/terminal-layouts.git
terminal-layout-sync sync --push

# On machine B
git clone git@github.com:user/terminal-layouts.git ~/.config/terminal-layouts/layouts
terminal-layout-sync list

Using Templates

# Apply development template
terminal-layout-sync template --apply dev --var PROJECT_DIR=/home/user/projects/myapp

# The layout is saved and ready to restore
terminal-layout-sync restore dev-instance

Supported Terminals

• tmux - Full support on Linux and macOS
• screen - Full support on Linux
• iTerm2 - macOS only with AppleScript support

Error Handling

Error	Solution
No tmux/screen session found	Start a new session or specify session name
Layout file corrupted	Validate JSON syntax, use backup file
Permission denied accessing layouts directory	Check directory permissions, create if missing
Git sync failed (no remote configured)	Run git remote add origin <url> first
Template not found	Check template name spelling, list available templates

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: npm test
5. Run linting: npm run lint
6. Submit a pull request

License

MIT License - see LICENSE file for details.