terminal-layout-sync/README.md

# 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

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

```bash
# 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
```bash
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
```bash
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
```bash
terminal-layout-sync list [options]

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

#### Import/Export
```bash
# 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
```bash
# 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
```bash
# 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`:

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