github.com/ck3mp3r/laio-cli @v0.17.0

A simple, flexbox-inspired layout and session manager for tmux. Define complex multi-window, multi-pane layouts in YAML and manage session lifecycles with startup/shutdown hooks.

Full Documentation

Features

• Flexbox-inspired layouts - Define pane splits with flex and flex_direction (row/column)
• Template variables - Dynamic configurations with Tera template support and array variables
• Session lifecycle management - Startup/shutdown commands and embedded scripts
• Dual configuration modes - Global configs (~/.config/laio) or local project configs (.laio.yaml)
• Session serialization - Export existing tmux sessions to YAML format
• Focus & zoom control - Pin focus and zoom states in configuration
• Environment & shell customization - Per-session env vars and shell overrides
• Tmux native - Built for tmux (experimental Zellij support available)

Quick Start

# Install (see Installation section)
nix profile install "github:ck3mp3r/laio-cli"

# Create a new config
laio config create myproject

# Start the session
laio start myproject

# List sessions and configs
laio list

Installation

Supported platforms: - Linux: x86_64 (Intel/AMD), aarch64 (ARM) - macOS: aarch64 (Apple Silicon)

Nix

nix profile install "github:ck3mp3r/laio-cli"

Homebrew

brew tap ck3mp3r/laio-cli https://github.com/ck3mp3r/laio-cli/
brew install laio

Binary Download

Download from the Release Page and add to PATH.

Development

Prerequisites

• Rust 1.70+ (or use Nix for reproducible builds)
• tmux 3.0+

Build

cargo build --release
# Binary at: target/release/laio

Test

cargo test

Development Environment (Nix)

nix develop
# or use direnv
direnv allow

Configuration Schema

The YAML configuration schema is defined in src/common/config/schema.json. Use this for editor integration (LSP, validation).

Usage

Commands

laio start [name]                  # Start session (interactive picker if name omitted)
laio start --file config.yaml      # Start from specific file
laio start --var key=value         # Start with template variables
laio stop [name]                   # Stop session
laio stop --all                    # Stop all laio-managed sessions
laio list                          # List sessions and configs
laio config create <name>          # Create new config
laio config create --var key=value # Create from _default.yaml with variables
laio config create --copy src      # Create from existing config
laio config edit <name>            # Edit config in $EDITOR
laio config link <name>            # Symlink .laio.yaml to global config
laio session yaml                  # Export current tmux session to YAML
laio completion <shell>            # Generate shell completions

See laio --help or full documentation for all options.

Template Variables

Create reusable configurations with template variables:

name: {{ session_name }}
path: {{ path }}

windows:
{% for service in services %}
  - name: {{ service }}
    panes:
      - path: ./{{ service }}
        commands:
          - command: npm
            args: [run, dev]
{% endfor %}

Auto-injected variables: - session_name - Set from the session name (cannot be overridden) - path - Defaults to current working directory

Start with variables:

# Uses session name and cwd automatically
laio start myproject

# Override path
laio start myproject --var path=~/projects/myproject

# Multiple services (array variables)
laio start microservices \
  --var services=auth \
  --var services=api \
  --var services=frontend

See template variable docs for complete syntax and examples.

Configuration

Configurations are YAML files defining session layouts:

name: myproject
path: /path/to/myproject

# Session lifecycle hooks
startup:
  - command: docker-compose
    args: [up, -d]

startup_script: |
  #!/usr/bin/env bash
  echo "Session starting..."

shutdown:
  - command: docker-compose
    args: [down]

shutdown_script: |
  #!/usr/bin/env bash
  echo "Cleaning up..."

# Session environment
shell: /bin/zsh
env:
  NODE_ENV: development
  DEBUG: "app:*"

# Window and pane layout
windows:
  - name: editor
    focus: true  # active window after session creation
    panes:
      - name: nvim
        commands:
          - command: $EDITOR

  - name: dev
    flex_direction: row  # vertical split (panes side-by-side)
    panes:
      - flex: 2
        flex_direction: column  # horizontal split (panes stacked)
        panes:
          - flex: 3
            path: ./src
            focus: true  # initial focus
            commands:
              - command: npm
                args: [run, dev]
          - flex: 1
            zoom: true  # start zoomed
            script: |
              #!/usr/bin/env bash
              tail -f logs/app.log
      - flex: 1
        style: bg=blue,fg=white  # tmux pane styling

Key features: - flex: Proportional sizing (e.g., flex: 2 = twice the size of flex: 1) - flex_direction: row (vertical split, side-by-side) or column (horizontal split, stacked) - focus (window): Active window after session creation - focus (pane): Pin initial cursor position within a window - zoom: Start pane in zoomed state - commands: Sequential command execution - script: Inline script blocks - path: Working directory (absolute or relative to session root)

See configuration docs for all options.

Project Configurations

Create .laio.yaml in any project directory:

cd myproject
laio config create  # creates .laio.yaml
laio start          # auto-detects and uses .laio.yaml

Link local configs to global namespace:

laio config link myproject  # symlinks .laio.yaml -> ~/.config/laio/myproject.yaml

Session Serialization

Export existing tmux sessions to YAML:

# From within a tmux session
laio session yaml > ~/.config/laio/newsession.yaml

Usage Restrictions

Use of this software is strictly prohibited for any organization, company, or government directly or indirectly involved in aiding or abetting the genocide and atrocities committed against the Palestinian people in Gaza. Only individuals and entities unaffiliated with such actions are permitted to use the software.

License

See LICENSE.md