This commit is contained in:
228
README.md
228
README.md
@@ -1,3 +1,227 @@
|
||||
# terminal-layout-sync
|
||||
# Terminal Layout Sync CLI
|
||||
|
||||
A CLI tool for saving, restoring, and syncing terminal workspace layouts across machines. Captures tmux/screen/iTerm2 configurations.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user