lota

README

Lota

A configurable task runner for rapid development. Define commands in a YAML file and run them from the terminal.

Features

• ✨ Configurable tasks — Define tasks and command groups in a single lota.yml. No code required: commands, arguments, variables, dependencies and execution hooks are all declared in YAML.
• 🔧 Flexible arguments — Support positional arguments, named flags (-f/--flag), boolean flags with negation (--!verbose), wildcard capture (...args) and typed arrays (files:arr[5]). CLI values are validated and exported as environment variables.
• 🔄 Variable interpolation — Inject variables and arguments into scripts with $name. Scopes follow app → group → command, so local definitions naturally override global ones.
• 🐚 Shell-aware execution — Auto-detects the system shell and falls back to bash if unsure. Override the shell per app, group or command. Supports bash, zsh, fish, sh, dash and others.
• 👁️ Dry-run mode — Run with --dry-run to print the exact scripts and resolved environment without executing them.
• 🛡️ Graceful shutdown — SIGINT/SIGTERM are propagated to child processes with a graceful period before forced termination.
• 📄 Env file imports — Load variables from .env files via import:env .env inside vars.
• 📊 YAML config imports — Import nested YAML files as variables with import:yaml <file>[@section] [prefix] and access flattened keys like ${app.database.host}.
• 📂 Nested groups — Organize commands in hierarchical groups (lota infra docker up) with arbitrary nesting depth.
• 📁 Working directory — Set dir per group or command. Relative paths resolve against the config file; use $CWD to run from the current directory.
• 📝 Tee logging — Mirror command output to log files while still printing to the terminal. Logs are inherited down the group tree and can be made independent.
• 🔗 Command dependencies — Declare depends with full dot-paths. Independent dependencies run in parallel by default, shared ones run once, and circular dependencies are detected automatically.
• 🔍 Upward config search — Run commands from any subdirectory: Lota walks up to the git root looking for lota.yml/lota.yaml.
• 🎨 Colored help — Highlight group and command names with named ANSI colors or hex values (e.g. #FF5733).
• ⏱️ Command timeout — Set a per-run timeout with --timeout 5m.
• 🧩 Execution hooks — Build pipelines with before, script, after, fallback and finally stages.
• 🧱 Native commands — Embed Lota as a Go library and register Go functions as handlers for native: true commands.
• 🎯 Shell completion — Built-in completion for bash, zsh and fish.

📦 Installation

Quick Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/quonaro/lota/main/scripts/install.sh | bash

Or with specific version:

curl -fsSL https://raw.githubusercontent.com/quonaro/lota/main/scripts/install.sh | bash -s -- -V v0.1.0

Script verifies SHA256 checksum and installs to ~/.local/bin (or /usr/local/bin with sudo).

Build from Source

Requires Go 1.26+

go install github.com/quonaro/lota@latest

Or manually:

git clone https://github.com/quonaro/lota.git
cd lota && go build -o lota . && sudo mv lota /usr/local/bin/

📚 Documentation

• Embedding Guide - How to embed Lota in your Go application
• Examples - Complete configuration examples for various use cases

🚀 Quick Start

Initialize a new configuration:

lota --init

This creates a lota.yml in your current directory.

Or create it manually:

build:
  desc: Build the application
  script: go build -o bin/app .

dev:
  desc: Development commands
  run:
    desc: Run with hot reload
    script: air
  test:
    desc: Run tests
    script: go test ./...

Run a command:

lota build
lota dev run
lota dev test

Comparison

Feature	Lota	Task	Just	npm scripts
Declarative YAML	✅	✅	✅	❌
Type-safe arguments	✅	✅	✅	❌
Variable interpolation	✅	✅	✅	✅
Nested groups	✅	✅	❌	❌
Working directory (dir)	✅	✅	❌	❌
Command dependencies	✅	✅	✅	❌
Upward config search	✅	❌	❌	❌
Env file imports	✅	✅	❌	❌
Shell auto-detection	✅	❌	❌	❌
Dry-run mode	✅	✅	❌	❌
Tee logging	✅	❌	❌	❌
Execution hooks	✅	❌	❌	❌
Native Go commands	✅	❌	❌	❌
Config file imports	✅	✅	❌	❌

Syntax Comparison

Simple build command:

# Lota
build:
  script: go build -o app .

# Task (Taskfile.yml)
build:
  cmds:
    - go build -o app .

# Just
build:
    go build -o app .

# npm scripts
"build": "go build -o app ."

With arguments:

# Lota
dev:
  args:
    - port|p:int=3000
  script: npm start -- --port $port

# Task (Taskfile.yml)
build:
  vars:
    PORT: 3000
  cmds:
    - npm start -- --port {{.PORT}}

# Just
port := "3000"
dev:
    npm start -- --port {{port}}

# npm scripts
"dev": "npm start -- --port ${PORT:-3000}"

With dependencies:

# Lota
test:
  depends:
    - build
  script: go test ./...

# Task (Taskfile.yml)
test:
  deps: [build]
  cmds:
    - go test ./...

# Just
build:
    go build -o app .

test: build
    go test ./...

# npm scripts
"test": "npm run build && go test ./..."

Examples

See the examples/ directory for complete working configurations:

• embedded.yaml - Full-featured example with native commands, groups, colors, variables, and arguments
• simple-web-project.yaml - Web development workflow
• devops-infrastructure.yaml - Docker and Kubernetes operations
• go-project.yaml - Go build, test, and release workflows
• multi-environment.yaml - Environment-specific configurations

⚙️ Configuration

📋 Structure

shell: bash # Optional: default shell (auto-detected if omitted)

vars: # global environment variables
  - KEY=value
  - import:env .env # Import from .env file

args: # global argument definitions
  - name:type=default

imports: # optional: import other config files / URLs
  - url: extra.yaml
    namespace: ext # optional; wraps imported commands/groups under `ext:`

group-name: # command group
  desc: ...
  color: cyan # Optional: highlight group name in help
  inherit_color: true # Optional: inherit color from parent group
  shell: sh # Optional: override shell for this group
  vars: # group-level variables
    - KEY=value
  args: # group-level arguments
    - name:type=default
  log: # Optional: group-level tee logging
    path: group.log
  command-name:
    desc: ...
    color: green # Optional: highlight command name in help
    script: ...

command-name: # top-level command
  desc: ...
  color: red # Optional: highlight command name in help
  script: ...
  log: # Optional: command-level tee logging
    path: cmd.log

🔑 Variables (vars)

Variables are exported as environment variables into scripts. Both vars and args share a unified environment pool — CLI args override vars on name collision. They support three scopes with priority: app < group < command.

vars:
  - DOCKER=docker compose # app-level

dev:
  vars:
    - DOCKER=docker # overrides app-level for this group
  run:
    vars:
      - DOCKER=podman # overrides group-level for this command
    script: $DOCKER up

📄 Import from .env files

Load variables from environment files:

vars:
  - import:env .env
  - import:env config/prod.env

📊 Import from YAML files

Import nested YAML configurations with automatic flattening to dot-notation:

vars:
  - import:yaml config.yaml # Import all with original keys
  - import:yaml config.yaml app # Import all with 'app.' prefix
  - import:yaml config.yaml@public # Import only 'public' section
  - import:yaml secrets.yaml@db cfg # Import 'db' section with 'cfg.' prefix

Syntax: import:yaml <file>[@<section>] [<prefix>]

Note: The old !import:yaml syntax is deprecated but still supported. Use import:yaml instead.

• file - Path to YAML file
• section (optional) - Import only specific top-level section via @section
• prefix (optional) - Add prefix to all imported keys

Example YAML file:

# config.yaml
public:
  app_name: MyApp
  version: 1.0.0
  database:
    host: localhost
    port: 5432

private:
  api_key: secret123

Resulting variables:

# import:yaml config.yaml@public app
vars:
  app.app_name: "MyApp"
  app.version: "1.0.0"
  app.database.host: "localhost"
  app.database.port: "5432"

Access in scripts: ${app.app_name}, ${app.database.host}

🎯 Arguments (args)

Arguments are passed from the CLI and exported as environment variables, accessible via $name in scripts.

Format: name|short:type=default

Part	Description	Example
name	Long name	output
|short	Short alias (optional)	|o
:type	Type (optional)	:str, :int, :bool, :arr
=default	Default value (optional)	=./bin

📝 Argument Types

Positional — passed by position, no flag needed:

args:
  - filename:str
  - count:int
script: process "$filename" "$count"

lota cmd file.txt 5

Flag — passed by name using --flag or -f. Any arg with a short alias (|short) or type bool becomes a flag:

args:
  - output|o:str=./bin
  - verbose|v:bool
script: go build -o "$output"

lota cmd --output ./dist
lota cmd -o ./dist --verbose

Wildcard — captures all remaining positional arguments:

args:
  - service:str
  - ...cmd
script: docker exec "$service" "$cmd"

lota cmd backend python manage.py shell
# service=backend, cmd="python manage.py shell"

Array — collects multiple consecutive positional values:

args:
  - files:arr[5] # collect up to 5 values
script: lint $files

lota cmd a.go b.go c.go

Boolean Flags

Bool args support negation via --!name:

lota cmd --verbose          # verbose=true
lota cmd --!verbose         # verbose=false
lota cmd --verbose=false    # verbose=false

Argument Scopes

Like vars, args can be defined at app, group, or command level and are merged with the same priority (command wins):

args:
  - env:str=dev # available to all commands

deploy:
  args:
    - env:str=prod # overrides app-level for this group
  run:
    script: ./deploy.sh --env="$env"

Deprecation: Using {{name}} for variable and argument interpolation is deprecated. Use $name instead. {{name}} will be removed in a future version.

Reserved Variables: System environment variable names (PATH, HOME, USER, SHELL, etc.) are reserved and cannot be overridden in vars.

🐚 Shell Configuration

Important: Lota selects the shell interpreter, but the script itself is shell-specific. Write scripts for the shell you target.

Lota auto-detects the shell binary from the system environment. If detection fails, it falls back to bash.

Override the shell at any level:

shell: zsh # app-level

dev:
  shell: bash # group-level override
  run:
    shell: sh # command-level override
    script: echo $0

Supported shells: bash, sh, zsh, dash, ksh, mksh, pdksh, ash, busybox, sash, tcsh, csh, fish

📁 Working Directory (dir)

Set the working directory for commands and groups. The path is resolved relative to the lota.yml file location.

backend:
  dir: ./backend # group-level default
  build:
    desc: Build backend
    script: go build .
  test:
    desc: Run backend tests
    dir: ./backend/tests # command-level override
    script: go test ./...

Priority: command > group > config file dir. Use $CWD or $CWD/... to target the current working directory. Useful in monorepos where different commands run in different subprojects.

🔗 Command Dependencies (depends)

Reference other commands that must run before the current one. Dependencies are specified as full dot-separated paths.

build:
  desc: Build the application
  script: go build -o bin/app .

test:
  desc: Run tests
  depends:
    - build
  script: go test ./...

deploy:
  desc: Deploy to production
  depends:
    - build
    - test
  script: ./deploy.sh

Dependencies execute with their own context (shell, vars, dir, default args). Circular dependencies are detected automatically and produce an error.

Independent dependencies run in parallel by default, with output prefixed by colored task name (like Docker Compose):

\x1b[35m[build]\x1b[0m  go build -o bin/app .
\x1b[36m[lint]\x1b[0m   golangci-lint run
\x1b[35m[build]\x1b[0m  ✓ done
\x1b[36m[lint]\x1b[0m   ✓ done
\x1b[33m[deploy]\x1b[0m ./deploy.sh

Each task gets its own color: either from its color field, inherited from a parent group, or a deterministic color derived from the task name.

To force sequential execution, set parallel: false:

ci:
  depends:
    - lint
    - test
  parallel: false
  script: echo "CI done"

Shared dependencies are executed once (deduplication). If build is a dependency of both test and deploy, running lota deploy will execute build exactly once.

TODO: A TUI for interactive task monitoring is under consideration for future versions.

⚡ Hooks Tutorial

Lota provides five execution stages per command. You only use what you need — a simple script is enough for most tasks.

before → script → after → finally
          ↓
    fallback → finally

Stage	Purpose	Runs on error?
before	Preparation (compile, check env)	Skips script, triggers fallback
script	Main command	Triggers fallback
after	Post-success action (notify, log)	Triggers fallback
fallback	Recovery / alternative path (rollback, alert, degrade)	If succeeds, command returns 0
finally	Cleanup (stop containers, remove temp files)	Always runs

Return code: 0 if before+script+after succeeded, or if fallback succeeded after a failure. Otherwise the first error's exit code. finally errors are printed to stderr but do not change the return code.

Example 1: Basic Pipeline

build:
  before: echo "Compiling..."
  script: go build -o bin/app .
  after: echo "Build complete"

Happy path: before → script → after → return 0

If script fails: before → script (exit 1) → return 1. after is skipped.

Example 2: Cleanup with finally

Use finally for operations that must run regardless of success or failure.

test:
  before: docker-compose up -d test-db
  script: go test ./...
  finally: docker-compose down test-db

Any outcome: before → script → finally → return 0 or 1. The database container is always stopped.

Example 3: Error Handling with fallback

Use fallback to react to failures — rollback, send alerts, write crash reports.

deploy:
  before: echo "Starting deploy..."
  script: ./deploy.sh
  after: echo "Deploy successful"
  fallback: ./rollback.sh
  finally: echo "Deploy finished"

Happy path: before → script → after → finally → return 0 Script fails: before → script (fail) → fallback → finally → return 0 (if fallback succeeds) After fails: before → script → after (fail) → fallback → finally → return 0 (if fallback succeeds)

Example 4: Full Pipeline — Database Migration

db:
  migrate:
    before: |
      echo "Creating backup..."
      pg_dump mydb > /tmp/backup.sql
    script: |
      echo "Running migrations..."
      migrate -path ./migrations -database "$DATABASE_URL" up
    after: echo "Migration complete"
    fallback: |
      echo "Migration failed, restoring backup..."
      psql mydb < /tmp/backup.sql
    finally: rm -f /tmp/backup.sql

Scenario	Flow
Success	before → script → after → finally (backup deleted)
Migration fails	before → script (fail) → fallback (restore) → finally (backup deleted)
After fails	before → script → after (fail) → fallback (restore) → finally (backup deleted)

📝 Tee Logging (log)

Write command output to log files while still printing to the terminal. Logs support additive inheritance: a command writes to its own log file plus all ancestor log files, unless independent: true breaks the chain.

log:
  path: logs/all.log # app-level: all commands inherit this

build:
  desc: Build the application
  script: go build -o bin/app .
  log:
    path: logs/build.log # writes to both all.log and build.log
    truncate: true # overwrite on each run (default: append)

test:
  desc: Run tests
  script: go test ./...
  log:
    path: logs/test.log
    independent: true # writes ONLY to test.log, skips all.log

Field	Type	Default	Description
path	string	required	Log file path (relative to lota.yml). Supports variable interpolation ($var).
truncate	bool	false	If true, overwrite the file on each run. If false, append.
independent	bool	false	If true, discard all ancestor logs and write only to this file. Not allowed at app level.

Inheritance behavior:

• independent: false (default): the command writes to its own path plus all ancestor paths.
• independent: true: the command writes only to its own path; ancestor logs are skipped.
• truncate applies only to the path declared on the same level.

log:
  path: logs/global.log

infra:
  desc: Infrastructure
  log:
    path: logs/infra.log
    independent: true # infra commands skip global.log
  docker:
    desc: Docker ops
    log:
      path: logs/docker.log # writes to infra.log + docker.log
    up:
      script: docker-compose up -d

Runtime errors (missing parent dir, permission denied, path is a directory) are printed to stderr as [log error] but do not fail the command.

📁 Nested Groups

Organize commands in hierarchical groups:

infra:
  desc: Infrastructure commands
  docker:
    desc: Docker operations
    up:
      script: docker-compose up
    down:
      script: docker-compose down
  k8s:
    desc: Kubernetes operations
    apply:
      script: kubectl apply -f k8s/

lota infra docker up
lota infra k8s apply

🎨 Help Colors

Highlight group and command names in lota help output using named ANSI colors or hex values:

dev:
  desc: Development commands
  color: cyan
  frontend:
    desc: Frontend commands
    inherit_color: true
    start:
      desc: Start dev server
      inherit_color: true
      script: npm run dev
    build:
      desc: Build frontend
      color: yellow
      script: npm run build

Option	Description
color	Named ANSI color (black, red, green, yellow, blue, magenta, cyan, white, and hi* variants) or any #RRGGBB hex value (e.g. #FF5733)
inherit_color	true to inherit the nearest ancestor color. Defaults to null (no inheritance)

Color resolution priority: direct color > inherited color > default. inherit_color: true walks up the group chain and uses the first non-empty color found. Hex colors work in true-color capable terminals.

🚩 Global Flags

Flag	Description
-h, --help	Show help
-V	Show version only (machine-friendly)
--version	Show version with ASCII banner
-v, --verbose	Enable verbose output
--dry-run	Show commands without executing
--init	Create a template lota.yml
--config	Specify config file or directory
-g	Use system-wide config (/etc/lota.yml)
-u	Use user config (~/.local/share/lota.yml)
--timeout <duration>	Set a command timeout (e.g. 30s, 5m)
--install-completion	Install shell completion script (auto-detects shell)
--install-completion zsh|bash|fish	Install completion for a specific shell
--completion-script zsh|bash|fish	Print completion script to stdout

🐚 Shell Completion

Lota provides built-in shell completion for bash, zsh, and fish.

Auto-install

lota --install-completion

Lota detects your shell from $SHELL and writes the completion script to the standard location.

Install for a specific shell

lota --install-completion bash
lota --install-completion zsh
lota --install-completion fish

Manual install (print to stdout)

Bash:

lota --completion-script bash >> ~/.bashrc

Zsh:

lota --completion-script zsh > ~/.config/zsh/completions/_lota

Fish:

lota --completion-script fish > ~/.config/fish/completions/lota.fish

Troubleshooting

If lota behaves like a completion engine instead of executing commands:

unset COMP_LINE COMP_POINT

Then regenerate and reinstall the completion script for your shell.

🔍 Upward Config Search

If lota.yml is not found in the current directory, Lota searches upward through parent directories until it finds one or reaches the git root (.git directory) or the filesystem root (/).

This is critical for monorepos and nested projects where you might run commands from subdirectories:

cd backend/src
lota build    # finds lota.yml in project root

Pass --help after a command to see its arguments:

lota dev run --help

👁️ Dry Run Mode

Preview what would be executed without actually running it:

lota build --dry-run

👨‍💻 Development

Prerequisites

• Go 1.26+
• Python 3.8+ (for pre-commit)
• cocogitto (cog) - for conventional commits

Setup Git Hooks

Install git hooks for commit validation and code quality:

# Install pre-commit
pip install pre-commit

# Install pre-commit hooks
pre-commit install

# Install commit-msg hook (for conventional commits)
pre-commit install --hook-type commit-msg

This installs:

• pre-commit hooks - runs go fmt, go vet, go test, and golangci-lint
• commit-msg hook - validates conventional commits via cocogitto

Manual Pre-commit

Run pre-commit manually without committing:

# Run all hooks
pre-commit run --all-files

# Run specific hook
pre-commit run go-fmt --all-files

Testing

# Run all tests
go test ./...

# Run with race detector
go test -race ./...

# Run with coverage
go test -cover ./...

Linting

# Run golangci-lint
golangci-lint run

# Run go vet
go vet ./...

# Format code
gofmt -w -s .

🏗️ Architecture

Lota follows a strict layered architecture:

• config/ - YAML parsing and configuration models
• runner/ - Command execution, argument parsing, interpolation
• engine/ - High-level orchestration used by the CLI and embedded Go API
• cli/ - CLI orchestration (binds config and engine; does not import runner directly)
• shared/ - Constants and shared utilities

Key design principles:

• Stateless - no global variables
• Context-aware execution with graceful shutdown
• Pure functions for interpolation and parsing (testable)
• Clean error handling with wrapped errors

📜 License

Apache License 2.0