### Complete Project Configuration Example

Source: https://github.com/quonaro/lota/blob/main/_autodocs/configuration.md

A comprehensive example demonstrating shell settings, global variables, arguments, logging, and nested command groups.

```yaml
shell: bash

vars:
  - name: env
    value: development
  - name: app_name
    value: myapp

args:
  - name: verbose
    short: v
    type: bool

log:
  path: logs/app.log
  truncate: false

groups:
  - name: dev
    desc: Development commands
    color: green
    vars:
      - name: env
        value: development
    groups:
      - name: docker
        commands:
          - name: up
            script: docker-compose up -d
          - name: down
            script: docker-compose down
    commands:
      - name: server
        desc: Start dev server
        script: npm run dev
        log:
          path: logs/server.log

  - name: prod
    desc: Production commands
    color: red
    vars:
      - name: env
        value: production
    commands:
      - name: deploy
        desc: Deploy to production
        script: ./scripts/deploy.sh
        depends:
          - build
          - test
        parallel: true
        args:
          - name: force
            type: bool

commands:
  - name: build
    desc: Build the application
    script: npm run build
  
  - name: test
    desc: Run tests
    script: npm test
    args:
      - name: coverage
        type: bool
```

--------------------------------

### Common CLI Usage Examples

Source: https://github.com/quonaro/lota/blob/main/_autodocs/README.md

Practical examples for executing commands, viewing help, and applying global flags.

```bash
# Show all commands
lota --help

# Show command-specific help
lota build --help

# Execute with verbose output
lota --verbose deploy

# Dry-run (no execution)
lota --dry-run deploy

# Set timeout
lota --timeout 5m deploy

# Execute with arguments
lota deploy --env prod --force
```

--------------------------------

### Initialize LogConfig

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

Example instantiation of the LogConfig struct.

```go
log := &config.LogConfig{
    Path:     "logs/$env.log",
    Truncate: false,
    Independent: false,
}
```

--------------------------------

### Initialize RunOptions

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/runner.md

Example of initializing the RunOptions struct with custom configuration.

```go
opts := runner.RunOptions{
    Verbose:    true,
    DryRun:     false,
    ConfigDir:  "/app",
    WorkingDir: os.Getenv("PWD"),
    Timeout:    5 * time.Minute,
    Stdin:      os.Stdin,
    Stdout:     os.Stdout,
    Stderr:     os.Stderr,
}
```

--------------------------------

### Implement NativeFunc example

Source: https://github.com/quonaro/lota/blob/main/_autodocs/types.md

Example implementation of a function matching the NativeFunc signature.

```go
func deploy(ctx context.Context, nctx engine.NativeContext) error {
    env := nctx.Vars["env"]
    // Perform deployment
    return nil
}
```

--------------------------------

### Install Lota via shell script

Source: https://github.com/quonaro/lota/blob/main/README.md

Downloads and executes the installation script for Linux or macOS systems.

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

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

--------------------------------

### AppConfig Initialization Example

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

Shows how to initialize an AppConfig instance and build its internal lookup indexes.

```go
cfg := &config.AppConfig{
    Shell: "bash",
    Vars: []config.Var{
        {Name: "env", Value: "dev"},
    },
    Commands: []config.Command{
        {
            Name:   "build",
            Desc:   "Build the project",
            Script: "go build .",
        },
    },
}

if err := cfg.BuildIndexes(); err != nil {
    log.Fatal(err)
}

result := cfg.Find("build")
```

--------------------------------

### GetConfigPath Usage Example

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

Demonstrates how to resolve a configuration path by searching for default files.

```go
fc, err := config.GetConfigPath("")
if err != nil {
    log.Fatal(err)
}
fmt.Println(fc.Path)
```

--------------------------------

### LoadConfig Usage Example

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/engine.md

Demonstrates initializing the engine by loading a YAML configuration string.

```go
package main

import (
    "log"
    "github.com/quonaro/lota/engine"
)

func main() {
    // Read YAML config from file
    configBytes := []byte(`
build:
  desc: Build the project
  script: go build -o bin/app .
`)
    
    cfg, err := engine.LoadConfig(configBytes)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Loaded %d commands", cfg.countTotalCommands())
}
```

--------------------------------

### Options Initialization Example

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/engine.md

Shows how to instantiate the Options struct with custom configuration, including a prefix formatter.

```go
opts := engine.Options{
    Verbose:    true,
    DryRun:     false,
    ConfigDir:  "/app/config",
    WorkingDir: "/app",
    Timeout:    5 * time.Minute,
    Stdin:      os.Stdin,
    Stdout:     os.Stdout,
    Stderr:     os.Stderr,
    PrefixFormatter: func(path string, cmd *config.Command, groups []*config.Group) string {
        return fmt.Sprintf("[%s] ", path)
    },
}
```

--------------------------------

### Smart Suggestion Example

Source: https://github.com/quonaro/lota/blob/main/docs/CLI.md

Demonstrates the output when an unrecognized command is entered.

```bash
$ lota biuld
command not found: biuld
Did you mean:
  - build
```

--------------------------------

### Define and initialize Var

Source: https://github.com/quonaro/lota/blob/main/_autodocs/types.md

Structure for variable definitions and an example of initializing a variable.

```go
type Var struct {
    Name     string
    Value    string
    FromFile string
    Format   string
    IsFile   bool
    Prefix   string
}
```

```go
Var{Name: "env", Value: "production"}
```

--------------------------------

### Install Lota dependency

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Add the Lota module to your Go project.

```bash
go get github.com/quonaro/lota
```

--------------------------------

### Initialize NativeContext

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/engine.md

Example instantiation of NativeContext with environment variables and standard output streams.

```go
nctx := engine.NativeContext{
    Vars:   map[string]string{"env": "prod"},
    Args:   map[string]string{"force": "true"},
    Stdout: os.Stdout,
    Stderr: os.Stderr,
}
```

--------------------------------

### Initialize a Command instance

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

Example of initializing a Command struct with name, description, script, dependencies, variables, and arguments.

```go
cmd := config.Command{
    Name:   "deploy",
    Desc:   "Deploy to production",
    Script: "docker push registry/app:latest",
    Depends: []string{"build", "test"},
    Vars: []config.Var{
        {Name: "env", Value: "prod"},
    },
    Args: []config.Arg{
        {Name: "force", Type: "bool"},
    },
}
```

--------------------------------

### App-Level Configuration Example

Source: https://github.com/quonaro/lota/blob/main/docs/CONFIGURATION.md

Demonstrates global settings for shell, variables, arguments, logging, and imports in a lota.yml file.

```yaml
shell: bash
vars:
  - APP_NAME=myapp
  - import:env .env
args:
  - env|e:str=dev
log:
  path: logs/all.log
imports:
  - url: ./extra.yaml
    namespace: ext
```

--------------------------------

### InterpolationContext Initialization Example

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/runner.md

Shows how to instantiate an InterpolationContext with variables, arguments, and a warning writer.

```go
interpCtx := runner.InterpolationContext{
    Vars: map[string]string{"env": "prod"},
    Args: map[string]string{"force": "true"},
    ArgDefs: []config.Arg{
        {Name: "force", Type: "bool"},
    },
    WarnWriter: os.Stderr,
}
```

--------------------------------

### Install completion for specific shell

Source: https://github.com/quonaro/lota/blob/main/docs/CLI.md

Explicitly install completion scripts for bash, zsh, or fish.

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

--------------------------------

### Main Entry Point Example

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/cli.md

Demonstrates how to invoke the CLI Run function within a main function.

```go
func main() {
    ctx := context.Background()
    if err := cli.Run(ctx); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Initialize ImportConfig slice

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

Example instantiation of a slice of ImportConfig objects.

```go
imports := []config.ImportConfig{
    {URL: "./shared.yml"},
    {URL: "https://example.com/tasks.yml", Namespace: "external"},
}
```

--------------------------------

### Initialize Group instance

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

Example of creating a nested Group structure with commands and custom styling.

```go
group := config.Group{
    Name:  "infra",
    Desc:  "Infrastructure commands",
    Color: "#FF5733",
    Groups: []config.Group{
        {
            Name: "docker",
            Desc: "Docker commands",
            Commands: []config.Command{
                {
                    Name:   "up",
                    Script: "docker-compose up -d",
                },
            },
        },
    },
}
```

--------------------------------

### Parsing Command-Line Arguments

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/runner.md

Example demonstrating how to define argument configurations and parse a slice of command-line strings.

```go
argDefs := []config.Arg{
    {Name: "env", Short: "e", Type: "str", Required: true},
    {Name: "force", Type: "bool"},
    {Name: "port", Type: "int", Default: "8080"},
}

args, err := runner.ParseArgs([]string{"--env", "prod", "--force", "-e"}, argDefs)
// args = map[string]string{"env": "prod", "force": "true", "port": "8080"}
```

--------------------------------

### Example YAML Configuration File

Source: https://github.com/quonaro/lota/blob/main/README.md

Sample structure for a YAML file intended for variable import.

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

private:
  api_key: secret123
```

--------------------------------

### Use SearchResult

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

Example usage of the Find method and processing the resulting SearchResult.

```go
result := cfg.Find("build")
if result.Exists && result.Command != nil {
    fmt.Println(result.Command.Name)
}
```

--------------------------------

### GetSuggestion Usage Example

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/cli.md

Shows how to retrieve a suggested command when a user provides an incorrect input.

```go
suggestion := cli.GetSuggestion("buld", cfg.GetAllCommandNames())
// Returns "build"
```

--------------------------------

### Explicit Configuration Flags

Source: https://github.com/quonaro/lota/blob/main/docs/CLI.md

Examples of providing configuration paths via the --config flag.

```bash
lota --config ./my-config.yaml build
```

```bash
lota --config ./my-project build
```

```bash
lota --config https://example.com/lota.yml build
```

--------------------------------

### Initialize Arg slice

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

Example of defining a collection of command-line arguments with various types and requirements.

```go
args := []config.Arg{
    {Name: "env", Type: "str", Short: "e", Required: true},
    {Name: "force", Type: "bool"},
    {Name: "port", Type: "int", Default: "8080"},
    {Name: "files", Type: "arr", MaxArr: ptr(5)},
}
```

--------------------------------

### RunCommand Usage Example

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/engine.md

Demonstrates executing a command using a dot-separated path and handling potential errors.

```go
err := engine.RunCommand(ctx, cfg, "deploy.prod", []string{"--env", "us-west"}, opts)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Implement and register NativeFunc

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/engine.md

Example implementation of a deployment function and its registration within engine options.

```go
func deploy(ctx context.Context, nctx engine.NativeContext) error {
    env := nctx.Vars["env"]
    force := nctx.Args["force"]
    
    if force == "true" {
        fmt.Fprintf(nctx.Stdout, "Forcing deployment to %s\n", env)
    }
    
    // Perform deployment
    return nil
}

opts := engine.Options{
    NativeHandlers: map[string]NativeFunc{
        "deploy.prod": deploy,
    },
}
```

--------------------------------

### Define Lota configuration

Source: https://github.com/quonaro/lota/blob/main/README.md

Example YAML structure for defining build and development tasks.

```yaml
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 ./...
```

--------------------------------

### Integer Argument Usage

Source: https://github.com/quonaro/lota/blob/main/_autodocs/configuration.md

Usage example for integer-type arguments, which are validated at parse time.

```bash
lota deploy --port 8080
# Validated at parse time and interpolation
```

--------------------------------

### YAML Flattening Example

Source: https://github.com/quonaro/lota/blob/main/docs/CONFIGURATION.md

Demonstrates how nested YAML structures are flattened into dot-notation keys.

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

```yaml
# import:yaml config.yaml@public app
# Resulting variables:
app.app_name: "MyApp"
app.database.host: "localhost"
app.database.port: "5432"
```

--------------------------------

### Wildcard Argument Usage

Source: https://github.com/quonaro/lota/blob/main/_autodocs/configuration.md

Usage example for capturing remaining arguments after a double-dash separator.

```bash
lota run -- extra args here
# Everything after -- captured into $args
```

--------------------------------

### Define a command in YAML

Source: https://github.com/quonaro/lota/blob/main/_autodocs/configuration.md

Example configuration for a deploy command including variables, arguments, logging, and lifecycle hooks.

```yaml
commands:
  - name: deploy
    desc: Deploy to production
    shell: bash
    dir: $CWD
    color: green
    inherit_color: false
    show: true
    vars:
      - name: env
        value: production
    args:
      - name: force
        short: f
        type: bool
      - name: region
        type: str
        required: true
      - name: timeout
        type: int
        default: "300"
    log:
      path: logs/deploy-$env.log
      truncate: true
      independent: false
    depends:
      - build
      - test
    parallel: true
    native: false
    script: |
      echo "Deploying to $env"
      docker push registry/app:latest
    before: |
      echo "Pre-deployment checks"
    after: |
      echo "Post-deployment validation"
    fallback: |
      echo "Deployment failed, rolling back"
    finally: |
      echo "Cleanup"
```

--------------------------------

### ColorizeError Usage Example

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/cli.md

Demonstrates printing a formatted error message to the console.

```go
fmt.Println(cli.ColorizeError("Command failed"))
```

--------------------------------

### Lota CLI Usage Examples

Source: https://github.com/quonaro/lota/blob/main/docs/CLI.md

Common command-line patterns for interacting with the Lota CLI, including help, versioning, configuration, and execution modes.

```bash
# Show help
lota --help
lota -h

# Show version
lota -V                   # machine-friendly: "0.1.0"
lota --version            # with ASCII banner

# Verbose output (debug logging)
lota -v build
lota --verbose build

# Dry run
lota build --dry-run

# Specify config
lota --config ./my-config.yaml build
lota --config ./my-project build
lota --config https://example.com/lota.yml build

# System-wide / user config
lota -g build
lota -u build

# Timeout
lota --timeout 5m build
lota --timeout 30s test

# Initialize
lota --init
```

--------------------------------

### ResolveLogs Usage Example

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/runner.md

Demonstrates how to invoke ResolveLogs to retrieve log configurations, noting that independent logs discard ancestor configurations.

```go
logs := runner.ResolveLogs(app, groups, cmd)
// If app has log at "run.log", group has independent log at "group.log"
// Result: []config.LogConfig{group_log}
```

--------------------------------

### Manually install completion scripts

Source: https://github.com/quonaro/lota/blob/main/docs/CLI.md

Print completion scripts to stdout for manual redirection to shell configuration or completion directories.

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

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

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

--------------------------------

### String Argument Usage

Source: https://github.com/quonaro/lota/blob/main/_autodocs/configuration.md

Usage examples for string-type arguments using full names or short flags.

```bash
lota build --name myapp
# or
lota build -n myapp
```

--------------------------------

### Define Lota YAML configuration groups

Source: https://github.com/quonaro/lota/blob/main/_autodocs/00-START-HERE.md

Example of defining command groups and dependencies in a YAML configuration file.

```yaml
groups:
  - name: deploy
    commands:
      - name: prod
        script: ./deploy.sh
        depends: [build, test]
```

--------------------------------

### Full Pipeline Database Migration

Source: https://github.com/quonaro/lota/blob/main/docs/EXECUTION.md

A comprehensive example using multi-line scripts to perform database backups, migrations, and automated rollbacks on failure.

```yaml
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
```

--------------------------------

### Array Argument Usage

Source: https://github.com/quonaro/lota/blob/main/_autodocs/configuration.md

Usage example for array-type arguments, which are comma-separated in CLI and space-separated in scripts.

```bash
lota test --files file1.go,file2.go,file3.go
# Space-separated in scripts: file1.go file2.go file3.go
```

--------------------------------

### Boolean Argument Usage

Source: https://github.com/quonaro/lota/blob/main/_autodocs/configuration.md

Usage examples for boolean-type arguments, supporting various truthy/falsy values.

```bash
lota deploy --force
# or
lota deploy --!force
# Accepts: true, false, 1, 0, yes, no, on, off
```

--------------------------------

### Define Hierarchical Working Directories

Source: https://github.com/quonaro/lota/blob/main/docs/EXECUTION.md

Example configuration showing how working directories are resolved relative to the lota.yml file or the invocation directory.

```yaml
# lota.yml is at /project/lota.yml

backend:           # group
  dir: ./backend   # → /project/backend
  build:
    script: go build .    # runs in /project/backend
  test:
    dir: ./backend/tests  # → /project/backend/tests
    script: go test ./... # runs in /project/backend/tests

frontend:
  build:
    dir: $CWD             # → wherever the user ran `lota` from
    script: npm run build
```

--------------------------------

### Define a Lota group with nested commands

Source: https://github.com/quonaro/lota/blob/main/docs/CONFIGURATION.md

Example of a group configuration including variables, arguments, logging, and nested commands.

```yaml
infra:
  desc: Infrastructure management
  color: cyan
  inherit_color: true
  shell: bash
  dir: ./infra
  vars:
    - DOCKER=docker compose
  args:
    - env|e:str=dev
  log:
    path: logs/infra.log
  docker:
    desc: Docker operations
    up:
      desc: Start services
      script: $DOCKER up -d
    down:
      desc: Stop services
      script: $DOCKER down
```

--------------------------------

### Define Project Variables

Source: https://github.com/quonaro/lota/blob/main/_autodocs/configuration.md

Example of defining various variable types including literal values, YAML imports, and environment file imports.

```yaml
vars:
  - name: env
    value: production
  - name: version
    value: v1.2.3
  - name: database_url
    value: postgres://localhost/mydb
  - name: config
    value: import:yaml ./config.yaml app
  - name: secrets
    value: import:env .env
```

```yaml
vars:
  - name: simple
    value: hello
  - name: yaml_config
    value: import:yaml ./config.yaml app
  - name: env_file
    value: import:env .env.production
```

--------------------------------

### Variable Scope Priority Example

Source: https://github.com/quonaro/lota/blob/main/docs/ARGUMENTS_VARS.md

Demonstrates how variables defined at different levels override each other based on scope specificity.

```yaml
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       # resolves to "podman up"
```

--------------------------------

### Auto-install shell completion

Source: https://github.com/quonaro/lota/blob/main/docs/CLI.md

Automatically detect the current shell and install completion scripts to standard locations.

```bash
lota --install-completion
```

--------------------------------

### LoadConfig Error Handling

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/engine.md

Example of inspecting error types returned by LoadConfig to differentiate between syntax and validation issues.

```go
cfg, err := engine.LoadConfig(data)
if err != nil {
    if strings.Contains(err.Error(), "duplicate") {
        log.Println("Configuration has duplicate command names")
    } else if strings.Contains(err.Error(), "parse") {
        log.Println("Invalid YAML syntax")
    }
}
```

--------------------------------

### Define Positional Arguments

Source: https://github.com/quonaro/lota/blob/main/docs/CONFIGURATION.md

Example of defining positional arguments in a YAML configuration and executing them via CLI.

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

```bash
lota cmd file.txt 5
```

--------------------------------

### Initialize Var instances

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

Demonstrates creating a simple variable and a file-imported variable configuration.

```go
var := config.Var{
    Name:  "database_url",
    Value: "postgres://localhost/mydb",
}

// Or with import
importVar := config.Var{
    Name:     "cfg",
    FromFile: "config.yaml",
    Format:   "yaml",
    Prefix:   "app",
}
```

--------------------------------

### Load Configuration from Path

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Initialize the application using relative or absolute file paths for the configuration file.

```go
// Relative to current directory
app, err := engine.NewAppFromPath("./config/lota.yml", opts)

// Absolute path
app, err := engine.NewAppFromPath("/etc/myapp/lota.yml", opts)
```

--------------------------------

### Initialize configuration

Source: https://github.com/quonaro/lota/blob/main/docs/CLI.md

Generate a template lota.yml file in the current directory if one does not already exist.

```bash
lota --init
```

--------------------------------

### Load App from Path

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Initialize an App instance directly from a file path with optional configuration directory overrides.

```go
app, err := engine.NewAppFromPath("./my-tasks.yaml", engine.Options{
    ConfigDir: "./config", // Optional: overrides detected config dir
    Stdout:    os.Stdout,
    Stderr:    os.Stderr,
})
```

--------------------------------

### Undefined Variable Error

Source: https://github.com/quonaro/lota/blob/main/docs/ARGUMENTS_VARS.md

Example of the error message returned when a variable cannot be resolved.

```text
error: undefined variable "MISSING_VAR" in script
```

--------------------------------

### Initialize CLI Application

Source: https://github.com/quonaro/lota/blob/main/_autodocs/INDEX.md

Standard entry point for running Lota as a CLI application.

```go
// Use lota via CLI
func main() {
    if err := cli.Run(context.Background()); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Deprecated Double-Brace Interpolation

Source: https://github.com/quonaro/lota/blob/main/docs/ARGUMENTS_VARS.md

Example of the deprecated {{name}} syntax which triggers a deprecation warning.

```yaml
script: echo "Building {{APP_NAME}}"  # deprecated, use $APP_NAME
```

--------------------------------

### Load configuration from file

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/cli.md

Loads and validates configuration from a specified path or searches for it if the path is empty.

```go
func LoadConfig(path string) (*config.AppConfig, error)
```

```go
cfg, err := cli.LoadConfig("")
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Display Help

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Print help information for the top-level application or specific command groups.

```go
engine.PrintHelp(cfg, os.Stdout, "myapp")
```

```go
err := engine.Run(ctx, cfg, []string{"admin"}, opts)
var groupErr *engine.GroupError
if errors.As(err, &groupErr) {
    engine.PrintGroupHelp(cfg, groupErr.Groups, os.Stdout, "myapp")
}
```

--------------------------------

### Print general help

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/cli.md

Displays the Lota banner, available commands, and global options.

```go
func PrintHelp(configPath string)
```

```go
cli.PrintHelp("./lota.yml")
```

--------------------------------

### Build Lota from source

Source: https://github.com/quonaro/lota/blob/main/README.md

Compiles the project using Go. Requires Go 1.26 or higher.

```bash
go install github.com/quonaro/lota@latest
```

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

--------------------------------

### Invoke HandleGlobalFlags

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/cli.md

Example usage of HandleGlobalFlags to process flags and handle potential exit conditions.

```go
shouldExit, err := cli.HandleGlobalFlags(flags)
if err != nil {
    log.Fatal(err)
}
if shouldExit {
    return
}
```

--------------------------------

### Interpolation Depth Error

Source: https://github.com/quonaro/lota/blob/main/docs/ARGUMENTS_VARS.md

Example of the error message returned when exceeding the maximum interpolation depth.

```text
error: maximum interpolation depth (10) exceeded for variable "A"
```

--------------------------------

### Define a simple web project workflow

Source: https://github.com/quonaro/lota/blob/main/docs/EXECUTION.md

Demonstrates environment variable imports, typed arguments with aliases, and conditional shell execution.

```yaml
vars:
  - import:env .env
  - PORT=3000

args:
  - mode|m:str=dev

dev:
  desc: Start development server
  script: npm run dev -- --port $PORT

build:
  desc: Build for production
  args:
    - minify|:bool
  script: |
    if [ "$minify" = "true" ]; then
      npm run build -- --minify
    else
      npm run build
    fi

test:
  desc: Run tests
  script: npm test
```

--------------------------------

### App Wrapper Usage

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Use the App struct to bundle configuration, options, and handlers for simplified execution.

```go
app, err := engine.NewApp(lotaYAML, engine.Options{
    Verbose: true,
    DryRun:  false,
    Stdout:  os.Stdout,
    Stderr:  os.Stderr,
})
if err != nil {
    // handle error
}

// Run commands
err = app.Run(ctx, []string{"build"})

// Print help
app.PrintHelp()

// Access config
cfg := app.Config()
```

--------------------------------

### Print command-specific help

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/cli.md

Displays detailed information for a specific command, including arguments and dependencies.

```go
func PrintCommandHelp(cfg *config.AppConfig, result config.SearchResult, verbose bool)
```

```go
result, _, _ := config.ResolveCommand(cfg, []string{"build"})
cli.PrintCommandHelp(cfg, result, false)
```

--------------------------------

### Access help system

Source: https://github.com/quonaro/lota/blob/main/_autodocs/errors.md

Use help flags to view documentation for the overall tool or specific commands.

```bash
lota --help              # Overall help
lota build --help        # Command-specific help
lota infra --help        # Group help
```

--------------------------------

### Basic Pipeline Configuration

Source: https://github.com/quonaro/lota/blob/main/docs/EXECUTION.md

A simple configuration demonstrating the standard execution sequence of before, script, and after stages.

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

--------------------------------

### Run Lota commands programmatically

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Load a configuration file and execute commands using the engine.Run function.

```go
package main

import (
    "context"
    "fmt"
    "os"

    "github.com/quonaro/lota/engine"
)

func main() {
    ctx := context.Background()

    // Load config from a file
    data, err := os.ReadFile("lota.yml")
    if err != nil {
        fmt.Fprintf(os.Stderr, "read config: %v\n", err)
        os.Exit(1)
    }

    cfg, err := engine.LoadConfig(data)
    if err != nil {
        fmt.Fprintf(os.Stderr, "config: %v\n", err)
        os.Exit(1)
    }

    // Run a command using CLI-style arguments
    err = engine.Run(ctx, cfg, []string{"deploy", "prod", "--force"}, engine.Options{
        Stdout: os.Stdout,
        Stderr: os.Stderr,
    })
    if err != nil {
        fmt.Fprintf(os.Stderr, "run: %v\n", err)
        os.Exit(1)
    }
}
```

--------------------------------

### Run Commands

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Execute commands using either CLI-style arguments or a specific command path.

```go
err := engine.Run(ctx, cfg, []string{"deploy", "prod", "--force"}, engine.Options{
    Stdout: os.Stdout,
    Stderr: os.Stderr,
})
```

```go
err := engine.RunCommand(ctx, cfg, "deploy.prod", []string{"--force"}, engine.Options{
    Stdout: os.Stdout,
    Stderr: os.Stderr,
})
```

--------------------------------

### engine.NewApp

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Creates a new App instance from configuration data.

```APIDOC
## engine.NewApp

### Description
Initializes a new App wrapper using configuration data and provided options.

### Signature
`func NewApp(data []byte, opts Options) (*App, error)`
```

--------------------------------

### engine.Run

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

CLI-style entrypoint for executing commands based on provided arguments.

```APIDOC
## engine.Run(ctx context.Context, cfg *config.AppConfig, args []string, opts Options) error

### Description
CLI-style entrypoint. args is the full command line (e.g., []string{"deploy", "prod", "--force"}).

### Parameters
- **ctx** (context.Context) - Required - Execution context.
- **cfg** (*config.AppConfig) - Required - The parsed application configuration.
- **args** ([]string) - Required - The command line arguments.
- **opts** (Options) - Required - Execution options.
```

--------------------------------

### Load Configuration

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Load engine configuration from either a byte slice or a file path.

```go
cfg, err := engine.LoadConfig(lotaYAML)
if err != nil {
    // handle error
}
```

```go
cfg, configDir, err := engine.LoadConfigFromPath("./my-tasks.yaml")
if err != nil {
    // handle error
}
```

--------------------------------

### Retrieve Command Help

Source: https://github.com/quonaro/lota/blob/main/docs/CLI.md

Displays descriptions, arguments, and options for a specific command.

```bash
lota dev run --help
lota build --help
```

--------------------------------

### Define a Go project build and release workflow

Source: https://github.com/quonaro/lota/blob/main/docs/EXECUTION.md

Shows shell command substitution for variables, task dependencies, and multi-flag argument handling.

```yaml
vars:
  - BINARY=app
  - VERSION=$(git describe --tags --always)

build:
  desc: Build binary
  args:
    - os|o:str=linux
    - arch|a:str=amd64
  script: |
    GOOS=$os GOARCH=$arch go build -o bin/$BINARY-$os-$arch .

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

release:
  desc: Create release
  args:
    - tag|t:str
  script: |
    git tag $tag
    git push origin $tag
    goreleaser release
```

--------------------------------

### Execute Lota commands

Source: https://github.com/quonaro/lota/blob/main/README.md

Run tasks defined in the configuration file.

```bash
lota build
lota dev run
lota dev test
```

--------------------------------

### Define engine.Options

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Configuration structure for engine execution settings.

```go
type Options struct {
    Verbose         bool
    DryRun          bool
    ConfigDir       string
    WorkingDir      string
    Timeout         time.Duration
    Stdout          io.Writer
    Stderr          io.Writer
    PrefixFormatter func(path string, cmd *config.Command, groups []*config.Group) string
    NativeHandlers  map[string]NativeFunc
}
```

--------------------------------

### Retrieve Top-level Help

Source: https://github.com/quonaro/lota/blob/main/docs/CLI.md

Displays all available top-level commands and groups.

```bash
lota --help
```

--------------------------------

### App.Run

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Runs a command using the configured application instance.

```APIDOC
## (*App) Run(ctx context.Context, args []string) error

### Description
Runs a command with CLI-style arguments.

### Parameters
- **ctx** (context.Context) - Required - Execution context.
- **args** ([]string) - Required - The command line arguments.
```

--------------------------------

### Visualize Lota Architecture Layers

Source: https://github.com/quonaro/lota/blob/main/docs/EXECUTION.md

A text-based diagram illustrating the dependency flow between the main entry point and the core packages.

```text
┌─────────────────────────────────────────────────┐
│                   main.go                        │
│  (signal handling, terminal setup, exit codes)   │
└────────────────────┬────────────────────────────┘
                     │
              ┌──────▼──────┐
              │    cli/      │
              │  (orchestrator)│
              └──┬───────┬───┘
                 │       │
          ┌──────▼──┐ ┌──▼──────┐
          │ config/  │ │ engine/  │
          │ (parse)  │ │ (orchestrate)│
          └─────────┘ └──┬──────┘
                        │
                   ┌────▼────┐
                   │ runner/  │
                   │ (execute)│
                   └──────────┘
```

--------------------------------

### Upward Configuration Search

Source: https://github.com/quonaro/lota/blob/main/docs/CLI.md

Demonstrates how Lota automatically locates configuration files in parent directories.

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

--------------------------------

### func Run(ctx context.Context) error

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/cli.md

Executes the main CLI application by parsing global flags, loading configuration, and resolving commands.

```APIDOC
## func Run(ctx context.Context) error

### Description
Executes the main CLI application. Parses global flags, loads configuration, resolves commands, and delegates execution to the engine.

### Parameters
- **ctx** (context.Context) - Required - Context for cancellation and timeout

### Return Type
- **error** - Execution error or nil on success

### Global Flags
- **--config / -c** (string) - Optional - Explicit config file path (Default: lota.yml)
- **--verbose / -v** (bool) - Optional - Enable verbose output (Default: false)
- **--dry-run** (bool) - Optional - Print commands without executing (Default: false)
- **--timeout / -t** (duration) - Optional - Command timeout (e.g., 5m, 30s)
- **-G** (flag) - Optional - Use /etc/lota.yml
- **-U** (flag) - Optional - Use ~/.local/share/lota.yml
- **--help / -h** (flag) - Optional - Show help
- **--version** (flag) - Optional - Show version

### Special Commands
- **--init** - Initialize a new lota.yml
- **--complete <shell>** - Generate shell completion
- **--upgrade** - Check for and install updates
```

--------------------------------

### engine.NewAppFromPath

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Creates a new App instance from a file path.

```APIDOC
## engine.NewAppFromPath

### Description
Initializes a new App wrapper using a configuration file path and provided options.

### Signature
`func NewAppFromPath(path string, opts Options) (*App, error)`
```

--------------------------------

### Build Command Path in Go

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

Constructs a dot-separated string representing the command hierarchy.

```go
path := config.CommandPath(&cmd, []*config.Group{&group1, &group2})
// Returns "group1.group2.cmdname"
```

--------------------------------

### Run CLI Application

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/cli.md

Executes the main CLI application by parsing flags and resolving commands.

```go
func Run(ctx context.Context) error
```

--------------------------------

### Initialize Configuration Validator in Go

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

Creates a validator instance for a configuration file, enabling validation checks.

```go
validator := config.GetValidator(cfg, "lota.yml")
result := validator.Validate()
if result.Error != nil {
    log.Fatal(result.Error)
}
```

--------------------------------

### PrintHelp

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/cli.md

Prints general help information for available commands and options.

```APIDOC
## PrintHelp

### Description
Prints general help for available commands and options.

### Signature
`func PrintHelp(configPath string)`

### Parameters
- **configPath** (string) - Config file path (for reference in help)

### Example
```go
cli.PrintHelp("./lota.yml")
```
```

--------------------------------

### Programmatic Command Lookup

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Inspect and execute commands manually by looking them up in the configuration.

```go
result, err := config.FindCommandByPath(cfg, "infra.docker.up")
if err != nil {
    // handle error
}

fmt.Println("Command:", result.Command.Name)
fmt.Println("Script:", result.Command.Script)
fmt.Println("Description:", result.Command.Desc)

// Run it manually
err = engine.RunCommand(ctx, cfg, "infra.docker.up", nil, opts)
```

--------------------------------

### Configure Engine Options

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Define custom execution options including logging, timeouts, and native handlers.

```go
opts := engine.Options{
    Verbose:         true,                    // Enable verbose logging
    DryRun:          false,                   // Print without executing
    ConfigDir:       "./config",              // Base for relative paths
    WorkingDir:      os.Getwd(),              // Current working directory
    Timeout:         30 * time.Second,        // Execution timeout
    Stdout:          os.Stdout,               // Output writer
    Stderr:          os.Stderr,               // Error writer
    PrefixFormatter: customPrefixFormatter,   // Custom dependency prefix
    NativeHandlers:  nativeHandlers,         // Native command handlers
}
```

--------------------------------

### Build embedded Lota application

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Use the builder pattern with //go:embed to bundle configurations and register custom native Go handlers.

```go
package main

import (
    "context"
    "embed"
    "errors"
    "fmt"
    "os"

    "github.com/quonaro/lota/engine"
)

//go:embed lota.yml
var lotaYAML []byte

func main() {
    builder := engine.NewBuilder("myapp", lotaYAML)
    builder.RegisterNative("deploy", deployHandler)
    builder.RegisterNative("infra.status", statusHandler)

    app, err := builder.Build()
    if err != nil {
        fmt.Fprintf(os.Stderr, "config: %v\n", err)
        os.Exit(1)
    }

    if len(os.Args) < 2 {
        app.PrintHelp()
        return
    }

    if err := app.Run(context.Background(), os.Args[1:]); err != nil {
        var groupErr *engine.GroupError
        if errors.As(err, &groupErr) {
            app.PrintGroupHelp(groupErr.Groups)
            return
        }
        fmt.Fprintf(os.Stderr, "run: %v\n", err)
        os.Exit(1)
    }
}

func deployHandler(ctx context.Context, nctx engine.NativeContext) error {
    fmt.Fprintf(nctx.Stdout, "Deploying...\n")
    // Your deployment logic here
    return nil
}

func statusHandler(ctx context.Context, nctx engine.NativeContext) error {
    fmt.Fprintf(nctx.Stdout, "Checking infrastructure status...\n")
    // Your status check logic here
    return nil
}
```

--------------------------------

### Importing Lota Packages

Source: https://github.com/quonaro/lota/blob/main/_autodocs/README.md

Required imports for accessing core engine, runner, configuration, CLI, and logging functionality.

```go
import (
    "github.com/quonaro/lota/engine"    // Core execution
    "github.com/quonaro/lota/runner"    // Command execution
    "github.com/quonaro/lota/config"    // Configuration
    "github.com/quonaro/lota/cli"       // CLI interface
    "github.com/quonaro/lota/logger"    // Debug logging
)
```

--------------------------------

### Optimize Go Binary Size

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Use linker flags to strip debug information and optionally compress the binary with UPX to reduce size.

```bash
# Strip debug info and symbol table
go build -ldflags="-s -w" -o myapp ./cmd/myapp

# Compress with UPX (optional, reduces ~50-70%)
upx --best myapp
```

--------------------------------

### PrintCommandHelp

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/cli.md

Prints detailed help for a specific command, including arguments, dependencies, and description.

```APIDOC
## PrintCommandHelp

### Description
Prints detailed help for a specific command, including arguments, dependencies, and description.

### Signature
`func PrintCommandHelp(cfg *config.AppConfig, result config.SearchResult, verbose bool)`

### Parameters
- **cfg** (*config.AppConfig) - Configuration
- **result** (config.SearchResult) - Search result for the command
- **verbose** (bool) - Show extended information

### Example
```go
result, _, _ := config.ResolveCommand(cfg, []string{"build"})
cli.PrintCommandHelp(cfg, result, false)
```
```

--------------------------------

### Define a simple build command

Source: https://github.com/quonaro/lota/blob/main/README.md

Comparison of basic build command definitions across different task runners.

```yaml
# 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 ."
```

--------------------------------

### Embed Lota engine in Go

Source: https://github.com/quonaro/lota/blob/main/_autodocs/00-START-HERE.md

Basic implementation for loading a configuration and executing a command within a Go application.

```go
cfg, configDir, _ := engine.LoadConfigFromPath("")
opts := engine.Options{ConfigDir: configDir}
engine.Run(ctx, cfg, []string{"build"}, opts)
```

--------------------------------

### engine.Run

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Executes commands using CLI-style arguments.

```APIDOC
## engine.Run

### Description
Executes a command based on CLI-style arguments provided as a slice.

### Signature
`func Run(ctx context.Context, cfg *Config, args []string, opts Options) error`
```

--------------------------------

### Boolean Flag Usage

Source: https://github.com/quonaro/lota/blob/main/docs/CONFIGURATION.md

Demonstrates different ways to set boolean flags via the CLI.

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

--------------------------------

### Register native handlers using Options

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Register multiple handlers simultaneously by passing a map to the engine options.

```go
app, err := engine.NewApp(lotaYAML, engine.Options{
    NativeHandlers: map[string]engine.NativeFunc{
        "deploy": func(ctx context.Context, nctx engine.NativeContext) error {
            // handler logic
            return nil
        },
        "admin.users.reset-password": func(ctx context.Context, nctx engine.NativeContext) error {
            // handler logic
            return nil
        },
    },
})
```

--------------------------------

### Define multi-environment configurations

Source: https://github.com/quonaro/lota/blob/main/docs/EXECUTION.md

Uses YAML imports to load environment-specific data and conditional logic to switch deployment targets.

```yaml
vars:
  - import:yaml environments.yaml@dev dev
  - import:yaml environments.yaml@prod prod

args:
  - env|e:str=dev

deploy:
  desc: Deploy application
  script: |
    if [ "$env" = "prod" ]; then
      echo "Deploying to production at $prod.host:$prod.port"
      kubectl apply -f k8s/prod/
    else
      echo "Deploying to dev at $dev.host:$dev.port"
      kubectl apply -f k8s/dev/
    fi
```

--------------------------------

### Register native handlers using the builder

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

The recommended approach for registering handlers using the engine builder pattern.

```go
builder := engine.NewBuilder("myapp", lotaYAML)

builder.RegisterNative("deploy", func(ctx context.Context, nctx engine.NativeContext) error {
    env := nctx.Args["env"]       // "dev" or "prod"
    region := nctx.Vars["REGION"] // "eu-west-1"

    fmt.Fprintf(nctx.Stdout, "Deploying to %s in %s\n", env, region)

    // Your Go code here:
    // - HTTP requests
    // - Database calls
    // - File operations
    // - Any logic you need

    return nil
})

app, err := builder.Build()
```

--------------------------------

### Import YAML Configurations

Source: https://github.com/quonaro/lota/blob/main/README.md

Imports nested YAML files with optional section filtering and key prefixing.

```yaml
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
```

--------------------------------

### Run shell completion subcommand

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/cli.md

Executes the hidden completion subcommand to output shell suggestions.

```go
func RunCompleteSubcommand(args []string)
```

--------------------------------

### Interpolation in Directory and Log Paths

Source: https://github.com/quonaro/lota/blob/main/docs/ARGUMENTS_VARS.md

Shows how variables can be used within directory and log path configurations.

```yaml
build:
  dir: $CWD/build
  log:
    path: logs/$env-build.log
  script: make build
```

--------------------------------

### Configure command dependencies

Source: https://github.com/quonaro/lota/blob/main/_autodocs/00-START-HERE.md

YAML configuration for setting command execution order and parallelism.

```yaml
depends:
  - build
  - test
  - infra.setup
parallel: true  # Default
```

--------------------------------

### RunCommand Function Signature

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/engine.md

Defines the programmatic interface for executing commands with context, configuration, and options.

```go
func RunCommand(ctx context.Context, cfg *config.AppConfig, path string, cmdArgs []string, opts Options) error
```

--------------------------------

### Define Native Commands in YAML

Source: https://github.com/quonaro/lota/blob/main/docs/CONFIGURATION.md

Configure commands to execute as Go functions by setting native to true. Requires embedding Lota as a Go library.

```yaml
server:
  desc: Start HTTP server
  native: true
  args:
    - port:int=8080
    - host:str=0.0.0.0

admin:
  users:
    reset-password:
      desc: Reset user password
      native: true
      args:
        - username:str
        - password:str
```

--------------------------------

### Parse configuration from file path in Go

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

Parses a YAML configuration file from a specified path, optionally providing an io.Writer for variable import output.

```go
func ParseConfigWithWriter(path string, writer io.Writer) (*AppConfig, error)
```

```go
cfg, err := config.ParseConfigWithWriter("lota.yml", os.Stderr)
```

--------------------------------

### Import Variables from .env Files

Source: https://github.com/quonaro/lota/blob/main/docs/ARGUMENTS_VARS.md

Load key-value pairs from .env files relative to the lota.yml location.

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

```env
DATABASE_URL=postgres://localhost:5432/mydb
API_KEY=secret123
DEBUG=true
```

--------------------------------

### Define engine.NativeFunc

Source: https://github.com/quonaro/lota/blob/main/docs/EMBEDDING.md

Function signature for native command handlers.

```go
type NativeFunc func(ctx context.Context, nctx NativeContext) error
```

--------------------------------

### Configure Help Visibility

Source: https://github.com/quonaro/lota/blob/main/_autodocs/configuration.md

Set the show field to false to hide a command from the help output while keeping it executable.

```yaml
show: false          # Hidden from help (still executable)
```

--------------------------------

### AppConfig Structure Definition

Source: https://github.com/quonaro/lota/blob/main/_autodocs/api-reference/config.md

The root configuration structure for a Lota application.

```go
type AppConfig struct {
    Shell    string
    Vars     []Var
    Args     []Arg
    RawArgs  []string
    Log      *LogConfig
    Imports  []ImportConfig
    Groups   []Group
    Commands []Command

    // Indexes (private)
    commandsMap map[string]*Command
    groupsMap   map[string]*Group
}
```