tasktree 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

tasktree/cli.py

@@ -89,7 +89,7 @@ def _show_task(task_name: str):
 
 
 def _show_tree(task_name: str):
-    """Show dependency tree with freshness indicators."""
+    """Show dependency tree structure."""
     recipe = _get_recipe()
     if recipe is None:
         console.print("[red]No recipe file found (tasktree.yaml or tt.yaml)[/red]")
@@ -107,59 +107,11 @@ def _show_tree(task_name: str):
         console.print(f"[red]Error building dependency tree: {e}[/red]")
         raise typer.Exit(1)
 
-    # Get execution statuses
-    state = StateManager(recipe.project_root)
-    state.load()
-    executor = Executor(recipe, state)
-    statuses = executor.execute_task(task_name, dry_run=True)
-
     # Build Rich tree
-    tree = _build_rich_tree(dep_tree, statuses)
+    tree = _build_rich_tree(dep_tree)
     console.print(tree)
 
 
-def _dry_run(task_name: str):
-    """Show what would be executed without actually running."""
-    recipe = _get_recipe()
-    if recipe is None:
-        console.print("[red]No recipe file found (tasktree.yaml or tt.yaml)[/red]")
-        raise typer.Exit(1)
-
-    task = recipe.get_task(task_name)
-    if task is None:
-        console.print(f"[red]Task not found: {task_name}[/red]")
-        raise typer.Exit(1)
-
-    # Get execution plan
-    state = StateManager(recipe.project_root)
-    state.load()
-    executor = Executor(recipe, state)
-    statuses = executor.execute_task(task_name, dry_run=True)
-
-    # Display plan
-    console.print(f"[bold]Execution plan for '{task_name}':[/bold]\n")
-
-    will_run = [name for name, status in statuses.items() if status.will_run]
-    will_skip = [name for name, status in statuses.items() if not status.will_run]
-
-    if will_run:
-        console.print(f"[yellow]Will execute ({len(will_run)} tasks):[/yellow]")
-        for i, name in enumerate(will_run, 1):
-            status = statuses[name]
-            console.print(f"  {i}. [cyan]{name}[/cyan]")
-            console.print(f"     - {status.reason}")
-            if status.changed_files:
-                console.print(f"     - changed files: {', '.join(status.changed_files)}")
-        console.print()
-
-    if will_skip:
-        console.print(f"[green]Will skip ({len(will_skip)} tasks):[/green]")
-        for name in will_skip:
-            status = statuses[name]
-            last_run_str = f", last run {status.last_run}" if status.last_run else ""
-            console.print(f"  - {name} (fresh{last_run_str})")
-
-
 def _init_recipe():
     """Create a blank recipe file with commented examples."""
     recipe_path = Path("tasktree.yaml")
@@ -221,9 +173,6 @@ def main(
     ),
     show: Optional[str] = typer.Option(None, "--show", help="Show task definition"),
     tree: Optional[str] = typer.Option(None, "--tree", help="Show dependency tree"),
-    dry_run: Optional[str] = typer.Option(
-        None, "--dry-run", help="Show execution plan without running"
-    ),
     init: Optional[bool] = typer.Option(
         None, "--init", help="Create a blank tasktree.yaml"
     ),
@@ -239,6 +188,12 @@ def main(
     force: Optional[bool] = typer.Option(
         None, "--force", "-f", help="Force re-run all tasks (ignore freshness)"
     ),
+    only: Optional[bool] = typer.Option(
+        None, "--only", "-o", help="Run only the specified task, skip dependencies (implies --force)"
+    ),
+    env: Optional[str] = typer.Option(
+        None, "--env", "-e", help="Override environment for all tasks"
+    ),
     task_args: Optional[List[str]] = typer.Argument(
         None, help="Task name and arguments"
     ),
@@ -270,11 +225,6 @@ def main(
         _show_tree(tree)
         raise typer.Exit()
 
-    # Handle dry-run option
-    if dry_run:
-        _dry_run(dry_run)
-        raise typer.Exit()
-
     # Handle init option
     if init:
         _init_recipe()
@@ -287,7 +237,9 @@ def main(
 
     # Handle task execution
     if task_args:
-        _execute_dynamic_task(task_args, force=force or False)
+        # When --only is specified, force execution (--only implies --force)
+        force_execution = force or only or False
+        _execute_dynamic_task(task_args, force=force_execution, only=only or False, env=env)
     else:
         # No arguments - show available tasks
         recipe = _get_recipe()
@@ -335,12 +287,14 @@ def _get_recipe() -> Recipe | None:
         raise typer.Exit(1)
 
 
-def _execute_dynamic_task(args: list[str], force: bool = False) -> None:
+def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = False, env: str | None = None) -> None:
     """Execute a task specified by name with arguments.
 
     Args:
         args: Command line arguments (task name and task arguments)
         force: If True, ignore freshness and re-run all tasks
+        only: If True, run only the specified task without dependencies
+        env: If provided, override environment for all tasks
     """
     if not args:
         return
@@ -353,6 +307,17 @@ def _execute_dynamic_task(args: list[str], force: bool = False) -> None:
         console.print("[red]No recipe file found (tasktree.yaml or tt.yaml)[/red]")
         raise typer.Exit(1)
 
+    # Apply global environment override if provided
+    if env:
+        # Validate that the environment exists
+        if not recipe.get_environment(env):
+            console.print(f"[red]Environment not found: {env}[/red]")
+            console.print("\nAvailable environments:")
+            for env_name in sorted(recipe.environments.keys()):
+                console.print(f"  - {env_name}")
+            raise typer.Exit(1)
+        recipe.global_env_override = env
+
     task = recipe.get_task(task_name)
     if task is None:
         console.print(f"[red]Task not found: {task_name}[/red]")
@@ -364,20 +329,20 @@ def _execute_dynamic_task(args: list[str], force: bool = False) -> None:
     # Parse task arguments
     args_dict = _parse_task_args(task.args, task_args)
 
-    # Prune state before execution
+    # Create executor and state manager
     state = StateManager(recipe.project_root)
     state.load()
+    executor = Executor(recipe, state)
+
+    # Prune state before execution (compute hashes with effective environment)
     valid_hashes = {
-        hash_task(t.cmd, t.outputs, t.working_dir, t.args)
+        hash_task(t.cmd, t.outputs, t.working_dir, t.args, executor._get_effective_env_name(t))
         for t in recipe.tasks.values()
     }
     state.prune(valid_hashes)
     state.save()
-
-    # Execute task
-    executor = Executor(recipe, state)
     try:
-        executor.execute_task(task_name, args_dict, dry_run=False, force=force)
+        executor.execute_task(task_name, args_dict, force=force, only=only)
         console.print(f"[green]✓ Task '{task_name}' completed successfully[/green]")
     except Exception as e:
         console.print(f"[red]✗ Task '{task_name}' failed: {e}[/red]")
@@ -458,40 +423,21 @@ def _parse_task_args(arg_specs: list[str], arg_values: list[str]) -> dict[str, A
     return args_dict
 
 
-def _build_rich_tree(dep_tree: dict, statuses: dict) -> Tree:
-    """Build a Rich Tree from dependency tree and statuses.
+def _build_rich_tree(dep_tree: dict) -> Tree:
+    """Build a Rich Tree from dependency tree structure.
 
     Args:
         dep_tree: Dependency tree structure
-        statuses: Task execution statuses
 
     Returns:
         Rich Tree for display
     """
     task_name = dep_tree["name"]
-    status = statuses.get(task_name)
-
-    # Determine color based on status
-    if status:
-        if status.will_run:
-            if status.reason == "dependency_triggered":
-                color = "yellow"
-                label = f"{task_name} (triggered by dependency)"
-            else:
-                color = "red"
-                label = f"{task_name} (stale: {status.reason})"
-        else:
-            color = "green"
-            label = f"{task_name} (fresh)"
-    else:
-        color = "white"
-        label = task_name
-
-    tree = Tree(f"[{color}]{label}[/{color}]")
+    tree = Tree(task_name)
 
     # Add dependencies
     for dep in dep_tree.get("deps", []):
-        dep_tree_obj = _build_rich_tree(dep, statuses)
+        dep_tree_obj = _build_rich_tree(dep)
         tree.add(dep_tree_obj)
 
     return tree

tasktree/executor.py

@@ -2,7 +2,11 @@
 
 from __future__ import annotations
 
+import os
+import platform
+import stat
 import subprocess
+import tempfile
 import time
 from dataclasses import dataclass, field
 from datetime import datetime
@@ -46,6 +50,85 @@ class Executor:
         self.recipe = recipe
         self.state = state_manager
 
+    def _get_platform_default_environment(self) -> tuple[str, list[str]]:
+        """Get default shell and args for current platform.
+
+        Returns:
+            Tuple of (shell, args) for platform default
+        """
+        is_windows = platform.system() == "Windows"
+        if is_windows:
+            return ("cmd", ["/c"])
+        else:
+            return ("bash", ["-c"])
+
+    def _get_effective_env_name(self, task: Task) -> str:
+        """Get the effective environment name for a task.
+
+        Resolution order:
+        1. Recipe's global_env_override (from CLI --env)
+        2. Task's explicit env field
+        3. Recipe's default_env
+        4. Empty string (for platform default)
+
+        Args:
+            task: Task to get environment name for
+
+        Returns:
+            Environment name (empty string if using platform default)
+        """
+        # Check for global override first
+        if self.recipe.global_env_override:
+            return self.recipe.global_env_override
+
+        # Use task's env
+        if task.env:
+            return task.env
+
+        # Use recipe default
+        if self.recipe.default_env:
+            return self.recipe.default_env
+
+        # Platform default (no env name)
+        return ""
+
+    def _resolve_environment(self, task: Task) -> tuple[str, list[str], str]:
+        """Resolve which environment to use for a task.
+
+        Resolution order:
+        1. Recipe's global_env_override (from CLI --env)
+        2. Task's explicit env field
+        3. Recipe's default_env
+        4. Platform default (bash on Unix, cmd on Windows)
+
+        Args:
+            task: Task to resolve environment for
+
+        Returns:
+            Tuple of (shell, args, preamble)
+        """
+        # Check for global override first
+        env_name = self.recipe.global_env_override
+
+        # If no global override, use task's env
+        if not env_name:
+            env_name = task.env
+
+        # If no explicit env, try recipe default
+        if not env_name and self.recipe.default_env:
+            env_name = self.recipe.default_env
+
+        # If we have an env name, look it up
+        if env_name:
+            env = self.recipe.get_environment(env_name)
+            if env:
+                return (env.shell, env.args, env.preamble)
+            # If env not found, fall through to platform default
+
+        # Use platform default
+        shell, args = self._get_platform_default_environment()
+        return (shell, args, "")
+
     def check_task_status(
         self,
         task: Task,
@@ -81,8 +164,9 @@ class Executor:
                 reason="forced",
             )
 
-        # Compute hashes
-        task_hash = hash_task(task.cmd, task.outputs, task.working_dir, task.args)
+        # Compute hashes (include effective environment)
+        effective_env = self._get_effective_env_name(task)
+        task_hash = hash_task(task.cmd, task.outputs, task.working_dir, task.args, effective_env)
         args_hash = hash_args(args_dict) if args_dict else None
         cache_key = make_cache_key(task_hash, args_hash)
 
@@ -146,16 +230,16 @@ class Executor:
         self,
         task_name: str,
         args_dict: dict[str, Any] | None = None,
-        dry_run: bool = False,
         force: bool = False,
+        only: bool = False,
     ) -> dict[str, TaskStatus]:
         """Execute a task and its dependencies.
 
         Args:
             task_name: Name of task to execute
             args_dict: Arguments to pass to the task
-            dry_run: If True, only check what would run without executing
             force: If True, ignore freshness and re-run all tasks
+            only: If True, run only the specified task without dependencies (implies force=True)
 
         Returns:
             Dictionary of task names to their execution status
@@ -166,8 +250,17 @@ class Executor:
         if args_dict is None:
             args_dict = {}
 
+        # When only=True, force execution (ignore freshness)
+        if only:
+            force = True
+
         # Resolve execution order
-        execution_order = resolve_execution_order(self.recipe, task_name)
+        if only:
+            # Only execute the target task, skip dependencies
+            execution_order = [task_name]
+        else:
+            # Execute task and all dependencies
+            execution_order = resolve_execution_order(self.recipe, task_name)
 
         # Check status of all tasks
         statuses: dict[str, TaskStatus] = {}
@@ -183,9 +276,6 @@ class Executor:
             status = self.check_task_status(task, task_args, dep_statuses, force=force)
             statuses[name] = status
 
-        if dry_run:
-            return statuses
-
         # Execute tasks that need to run
         for name in execution_order:
             status = statuses[name]
@@ -220,21 +310,116 @@ class Executor:
         # Determine working directory
         working_dir = self.recipe.project_root / task.working_dir
 
+        # Resolve environment for this task
+        shell, shell_args, preamble = self._resolve_environment(task)
+
         # Execute command
         print(f"Running: {task.name}")
+
+        # Detect multi-line commands (ignore trailing newlines from YAML folded blocks)
+        if "\n" in cmd.rstrip():
+            self._run_multiline_command(cmd, working_dir, task.name, shell, preamble)
+        else:
+            self._run_single_line_command(cmd, working_dir, task.name, shell, shell_args)
+
+        # Update state
+        self._update_state(task, args_dict)
+
+    def _run_single_line_command(
+        self, cmd: str, working_dir: Path, task_name: str, shell: str, shell_args: list[str]
+    ) -> None:
+        """Execute a single-line command via shell.
+
+        Args:
+            cmd: Command string
+            working_dir: Working directory
+            task_name: Task name (for error messages)
+            shell: Shell executable to use
+            shell_args: Arguments to pass to shell
+
+        Raises:
+            ExecutionError: If command execution fails
+        """
         try:
-            result = subprocess.run(
-                cmd,
-                shell=True,
+            # Build command: shell + args + cmd
+            full_cmd = [shell] + shell_args + [cmd]
+            subprocess.run(
+                full_cmd,
                 cwd=working_dir,
                 check=True,
                 capture_output=False,
             )
         except subprocess.CalledProcessError as e:
-            raise ExecutionError(f"Task '{task.name}' failed with exit code {e.returncode}")
+            raise ExecutionError(
+                f"Task '{task_name}' failed with exit code {e.returncode}"
+            )
 
-        # Update state
-        self._update_state(task, args_dict)
+    def _run_multiline_command(
+        self, cmd: str, working_dir: Path, task_name: str, shell: str, preamble: str
+    ) -> None:
+        """Execute a multi-line command via temporary script file.
+
+        Args:
+            cmd: Multi-line command string
+            working_dir: Working directory
+            task_name: Task name (for error messages)
+            shell: Shell to use for script execution
+            preamble: Preamble text to prepend to script
+
+        Raises:
+            ExecutionError: If command execution fails
+        """
+        # Determine file extension based on platform
+        is_windows = platform.system() == "Windows"
+        script_ext = ".bat" if is_windows else ".sh"
+
+        # Create temporary script file
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            suffix=script_ext,
+            delete=False,
+        ) as script_file:
+            script_path = script_file.name
+
+            # On Unix/macOS, add shebang if not present
+            if not is_windows and not cmd.startswith("#!"):
+                # Use the configured shell in shebang
+                shebang = f"#!/usr/bin/env {shell}\n"
+                script_file.write(shebang)
+
+            # Add preamble if provided
+            if preamble:
+                script_file.write(preamble)
+                if not preamble.endswith("\n"):
+                    script_file.write("\n")
+
+            # Write command to file
+            script_file.write(cmd)
+            script_file.flush()
+
+        try:
+            # Make executable on Unix/macOS
+            if not is_windows:
+                os.chmod(script_path, os.stat(script_path).st_mode | stat.S_IEXEC)
+
+            # Execute script file
+            try:
+                subprocess.run(
+                    [script_path],
+                    cwd=working_dir,
+                    check=True,
+                    capture_output=False,
+                )
+            except subprocess.CalledProcessError as e:
+                raise ExecutionError(
+                    f"Task '{task_name}' failed with exit code {e.returncode}"
+                )
+        finally:
+            # Clean up temporary file
+            try:
+                os.unlink(script_path)
+            except OSError:
+                pass  # Ignore cleanup errors
 
     def _substitute_args(self, cmd: str, args_dict: dict[str, Any]) -> str:
         """Substitute arguments in command string.
@@ -352,8 +537,9 @@ class Executor:
             task: Task that was executed
             args_dict: Arguments used for execution
         """
-        # Compute hashes
-        task_hash = hash_task(task.cmd, task.outputs, task.working_dir, task.args)
+        # Compute hashes (include effective environment)
+        effective_env = self._get_effective_env_name(task)
+        task_hash = hash_task(task.cmd, task.outputs, task.working_dir, task.args, effective_env)
         args_hash = hash_args(args_dict) if args_dict else None
         cache_key = make_cache_key(task_hash, args_hash)
 

tasktree/hasher.py

@@ -5,7 +5,7 @@ import json
 from typing import Any
 
 
-def hash_task(cmd: str, outputs: list[str], working_dir: str, args: list[str]) -> str:
+def hash_task(cmd: str, outputs: list[str], working_dir: str, args: list[str], env: str = "") -> str:
     """Compute task definition hash.
 
     The hash includes:
@@ -13,6 +13,7 @@ def hash_task(cmd: str, outputs: list[str], working_dir: str, args: list[str]) -
     - outputs: Declared output files
     - working_dir: Execution directory
     - args: Parameter definitions (names and types)
+    - env: Environment name (effective environment after resolution)
 
     The hash excludes:
     - deps: Only affects scheduling order
@@ -24,6 +25,7 @@ def hash_task(cmd: str, outputs: list[str], working_dir: str, args: list[str]) -
         outputs: List of output glob patterns
         working_dir: Working directory for execution
         args: List of argument definitions
+        env: Environment name (empty string for platform default)
 
     Returns:
         8-character hex hash string
@@ -34,6 +36,7 @@ def hash_task(cmd: str, outputs: list[str], working_dir: str, args: list[str]) -
         "outputs": sorted(outputs),  # Sort for stability
         "working_dir": working_dir,
         "args": sorted(args),  # Sort for stability
+        "env": env,  # Include effective environment
     }
 
     # Serialize to JSON with sorted keys for deterministic hashing

tasktree/parser.py

@@ -14,6 +14,21 @@ class CircularImportError(Exception):
     pass
 
 
+@dataclass
+class Environment:
+    """Represents an execution environment configuration."""
+
+    name: str
+    shell: str
+    args: list[str] = field(default_factory=list)
+    preamble: str = ""
+
+    def __post_init__(self):
+        """Ensure args is always a list."""
+        if isinstance(self.args, str):
+            self.args = [self.args]
+
+
 @dataclass
 class Task:
     """Represents a task definition."""
@@ -27,6 +42,7 @@ class Task:
     working_dir: str = ""
     args: list[str] = field(default_factory=list)
     source_file: str = ""  # Track which file defined this task
+    env: str = ""  # Environment name to use for execution
 
     def __post_init__(self):
         """Ensure lists are always lists."""
@@ -46,6 +62,9 @@ class Recipe:
 
     tasks: dict[str, Task]
     project_root: Path
+    environments: dict[str, Environment] = field(default_factory=dict)
+    default_env: str = ""  # Name of default environment
+    global_env_override: str = ""  # Global environment override (set via CLI --env)
 
     def get_task(self, name: str) -> Task | None:
         """Get task by name.
@@ -62,6 +81,17 @@ class Recipe:
         """Get all task names."""
         return list(self.tasks.keys())
 
+    def get_environment(self, name: str) -> Environment | None:
+        """Get environment by name.
+
+        Args:
+            name: Environment name
+
+        Returns:
+            Environment if found, None otherwise
+        """
+        return self.environments.get(name)
+
 
 def find_recipe_file(start_dir: Path | None = None) -> Path | None:
     """Find recipe file (tasktree.yaml or tt.yaml) in current or parent directories.
@@ -94,6 +124,68 @@ def find_recipe_file(start_dir: Path | None = None) -> Path | None:
     return None
 
 
+def _parse_file_with_env(
+    file_path: Path,
+    namespace: str | None,
+    project_root: Path,
+    import_stack: list[Path] | None = None,
+) -> tuple[dict[str, Task], dict[str, Environment], str]:
+    """Parse file and extract tasks and environments.
+
+    Args:
+        file_path: Path to YAML file
+        namespace: Optional namespace prefix for tasks
+        project_root: Root directory of the project
+        import_stack: Stack of files being imported (for circular detection)
+
+    Returns:
+        Tuple of (tasks, environments, default_env_name)
+    """
+    # Parse tasks normally
+    tasks = _parse_file(file_path, namespace, project_root, import_stack)
+
+    # Load YAML again to extract environments (only from root file)
+    environments: dict[str, Environment] = {}
+    default_env = ""
+
+    # Only parse environments from the root file (namespace is None)
+    if namespace is None:
+        with open(file_path, "r") as f:
+            data = yaml.safe_load(f)
+
+        if data and "environments" in data:
+            env_data = data["environments"]
+            if isinstance(env_data, dict):
+                # Extract default environment name
+                default_env = env_data.get("default", "")
+
+                # Parse each environment definition
+                for env_name, env_config in env_data.items():
+                    if env_name == "default":
+                        continue  # Skip the default key itself
+
+                    if not isinstance(env_config, dict):
+                        raise ValueError(
+                            f"Environment '{env_name}' must be a dictionary"
+                        )
+
+                    # Parse environment configuration
+                    shell = env_config.get("shell", "")
+                    if not shell:
+                        raise ValueError(
+                            f"Environment '{env_name}' must specify 'shell'"
+                        )
+
+                    args = env_config.get("args", [])
+                    preamble = env_config.get("preamble", "")
+
+                    environments[env_name] = Environment(
+                        name=env_name, shell=shell, args=args, preamble=preamble
+                    )
+
+    return tasks, environments, default_env
+
+
 def parse_recipe(recipe_path: Path) -> Recipe:
     """Parse a recipe file and handle imports recursively.
 
@@ -115,9 +207,16 @@ def parse_recipe(recipe_path: Path) -> Recipe:
     project_root = recipe_path.parent
 
     # Parse main file - it will recursively handle all imports
-    tasks = _parse_file(recipe_path, namespace=None, project_root=project_root)
+    tasks, environments, default_env = _parse_file_with_env(
+        recipe_path, namespace=None, project_root=project_root
+    )
 
-    return Recipe(tasks=tasks, project_root=project_root)
+    return Recipe(
+        tasks=tasks,
+        project_root=project_root,
+        environments=environments,
+        default_env=default_env,
+    )
 
 
 def _parse_file(
@@ -198,10 +297,14 @@ def _parse_file(
 
             tasks.update(nested_tasks)
 
+    # Determine where tasks are defined
+    # Tasks can be either at root level OR inside a "tasks:" key
+    tasks_data = data.get("tasks", data) if "tasks" in data else data
+
     # Process local tasks
-    for task_name, task_data in data.items():
-        # Skip import declarations
-        if task_name == "import":
+    for task_name, task_data in tasks_data.items():
+        # Skip special sections (only relevant if tasks are at root level)
+        if task_name in ("import", "environments", "tasks"):
             continue
 
         if not isinstance(task_data, dict):

{tasktree-0.0.2.dist-info → tasktree-0.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktree
-Version: 0.0.2
+Version: 0.0.3
 Summary: A task automation tool with incremental execution
 Requires-Python: >=3.11
 Requires-Dist: click>=8.1.0
@@ -72,11 +72,12 @@ tt --list         # Show all available tasks
 
 Task Tree only runs tasks when necessary. A task executes if:
 
-- Its definition (command, outputs, working directory) has changed
+- Its definition (command, outputs, working directory, environment) has changed
 - Any input files have changed since the last run
 - Any dependencies have re-run
 - It has never been executed before
 - It has no inputs or outputs (always runs)
+- The execution environment has changed (CLI override or environment config change)
 
 ### Automatic Input Inheritance
 
@@ -105,17 +106,25 @@ All state lives in `.tasktree-state` at your project root. Stale entries are aut
 ```yaml
 task-name:
   desc: Human-readable description (optional)
-  deps: [other-task]              # Task dependencies
-  inputs: [src/**/*.go]            # Explicit input files (glob patterns)
-  outputs: [dist/binary]           # Output files (glob patterns)
-  working_dir: subproject/         # Execution directory (default: project root)
-  args: [param1, param2:path=default]   # Task parameters
-  cmd: go build -o dist/binary     # Command to execute
+  deps: [other-task]                     # Task dependencies
+  inputs: [src/**/*.go]                  # Explicit input files (glob patterns)
+  outputs: [dist/binary]                 # Output files (glob patterns)
+  working_dir: subproject/               # Execution directory (default: project root)
+  env: bash-strict                       # Execution environment (optional)
+  args: [param1, param2:path=default]    # Task parameters
+  cmd: go build -o dist/binary           # Command to execute
 ```
 
 ### Commands
 
-Multi-line commands using YAML literal blocks:
+**Single-line commands** are executed directly via the configured shell:
+
+```yaml
+build:
+  cmd: cargo build --release
+```
+
+**Multi-line commands** are written to temporary script files for proper execution:
 
 ```yaml
 deploy:
@@ -125,7 +134,9 @@ deploy:
     rsync -av dist/ server:/opt/app/
 ```
 
-Or folded blocks for long single-line commands:
+Multi-line commands preserve shell syntax (line continuations, heredocs, etc.) and support shebangs on Unix/macOS.
+
+Or use folded blocks for long single-line commands:
 
 ```yaml
 compile:
@@ -136,6 +147,58 @@ compile:
     -L lib -lm
 ```
 
+### Execution Environments
+
+Configure custom shell environments for task execution:
+
+```yaml
+environments:
+  default: bash-strict
+
+  bash-strict:
+    shell: bash
+    args: ['-c']              # For single-line: bash -c "command"
+    preamble: |               # For multi-line: prepended to script
+      set -euo pipefail
+
+  python:
+    shell: python
+    args: ['-c']
+
+  powershell:
+    shell: powershell
+    args: ['-ExecutionPolicy', 'Bypass', '-Command']
+    preamble: |
+      $ErrorActionPreference = 'Stop'
+
+tasks:
+  build:
+    # Uses 'default' environment (bash-strict)
+    cmd: cargo build --release
+
+  analyze:
+    env: python
+    cmd: |
+      import sys
+      print(f"Analyzing with Python {sys.version}")
+      # ... analysis code ...
+
+  windows-task:
+    env: powershell
+    cmd: |
+      Compress-Archive -Path dist/* -DestinationPath package.zip
+```
+
+**Environment resolution priority:**
+1. CLI override: `tt --env python build`
+2. Task's `env` field
+3. Recipe's `default` environment
+4. Platform default (bash on Unix, cmd on Windows)
+
+**Platform defaults** when no environments are configured:
+- **Unix/macOS**: bash with `-c` args
+- **Windows**: cmd with `/c` args
+
 ### Parameterised Tasks
 
 Tasks can accept arguments with optional defaults:
@@ -202,12 +265,19 @@ Input and output patterns support standard glob syntax:
 
 ### How State Works
 
-Each task is identified by a hash of its definition (command, outputs, working directory). State tracks:
+Each task is identified by a hash of its definition. The hash includes:
 
+- Command to execute
+- Output patterns
+- Working directory
+- Argument definitions
+- Execution environment
+
+State tracks:
 - When the task last ran
 - Timestamps of input files at that time
 
-Tasks are re-run when their definition changes or inputs are newer than the last run.
+Tasks are re-run when their definition changes, inputs are newer than the last run, or the environment changes.
 
 ### What's Not In The Hash
 
@@ -222,6 +292,72 @@ Changes to these don't invalidate cached state:
 
 At the start of each invocation, state is checked for invalid task hashes and non-existent ones are automatically removed. Delete a task from your recipe file and its state disappears the next time you run `tt <cmd>`
 
+## Command-Line Options
+
+Task Tree provides several command-line options for controlling task execution:
+
+### Execution Control
+
+```bash
+# Force re-run (ignore freshness checks)
+tt --force build
+tt -f build
+
+# Run only the specified task, skip dependencies (implies --force)
+tt --only deploy
+tt -o deploy
+
+# Override environment for all tasks
+tt --env python analyze
+tt -e powershell build
+```
+
+### Information Commands
+
+```bash
+# List all available tasks
+tt --list
+tt -l
+
+# Show detailed task definition
+tt --show build
+
+# Show dependency tree (without execution)
+tt --tree deploy
+
+# Show version
+tt --version
+tt -v
+
+# Create a blank recipe file
+tt --init
+```
+
+### State Management
+
+```bash
+# Remove state file (reset task cache)
+tt --clean
+tt --clean-state
+tt --reset
+```
+
+### Common Workflows
+
+```bash
+# Fresh build of everything
+tt --force build
+
+# Run a task without rebuilding dependencies
+tt --only test
+
+# Test with a different shell/environment
+tt --env python test
+
+# Force rebuild and deploy
+tt --force deploy production
+```
+
 ## Example: Full Build Pipeline
 
 ```yaml

tasktree-0.0.3.dist-info/RECORD

@@ -0,0 +1,13 @@
+tasktree/__init__.py,sha256=MVmdvKb3JdqLlo0x2_TPGMfgFC0HsDnP79HAzGnFnjI,1081
+tasktree/cli.py,sha256=hfxKF4N8nKPvy3WwyQgENHNH8YbUD3Zd7DLHGuHdeHU,14400
+tasktree/executor.py,sha256=_E37tShHuiOj0Mvx2GbS9y3GIozC3hpzAVhAjbvYJqg,18638
+tasktree/graph.py,sha256=9ngfg93y7EkOIN_lUQa0u-JhnwiMN1UdQQvIFw8RYCE,4181
+tasktree/hasher.py,sha256=xOeth3vufP-QrjnVgTDh02clkZb867aJPD6HSjhMNsg,2336
+tasktree/parser.py,sha256=apLfN3_YVa7lQIy0rcHFwo931Pg-8mKG1044AQE6fLQ,12690
+tasktree/state.py,sha256=rxKtS3SbsPtAuraHbN807RGWfoYYkQ3pe8CxUstwo2k,3535
+tasktree/tasks.py,sha256=2QdQZtJAX2rSGbyXKG1z9VF_siz1DUzdvzCgPkykxtU,173
+tasktree/types.py,sha256=wrBzO-Z2ebCTRjWyOWNvuCjqAq-74Zyb9E4FQ4beF38,3751
+tasktree-0.0.3.dist-info/METADATA,sha256=qlpV-egfSY502xJKLmmam1CTUVpVEiU4oS10LntL7gE,11961
+tasktree-0.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tasktree-0.0.3.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
+tasktree-0.0.3.dist-info/RECORD,,

tasktree-0.0.2.dist-info/RECORD

@@ -1,13 +0,0 @@
-tasktree/__init__.py,sha256=MVmdvKb3JdqLlo0x2_TPGMfgFC0HsDnP79HAzGnFnjI,1081
-tasktree/cli.py,sha256=VZGB8FJ8glZLn_z2bjSLLbmGRfFZ5Zh4nc1cYDLjGck,15904
-tasktree/executor.py,sha256=ZM-qEsgvjfRz77GEZzxF29L3I2d8Uz5W1ev7Mox9Vnc,12287
-tasktree/graph.py,sha256=9ngfg93y7EkOIN_lUQa0u-JhnwiMN1UdQQvIFw8RYCE,4181
-tasktree/hasher.py,sha256=jvXBvIfFH9g6AOBHHd012v8nG5JOgVnHH35mIEtVkwc,2133
-tasktree/parser.py,sha256=F2LbB84NinvBQT8zLONxn036R9Rued2y4XB3WGZ8PLk,9150
-tasktree/state.py,sha256=rxKtS3SbsPtAuraHbN807RGWfoYYkQ3pe8CxUstwo2k,3535
-tasktree/tasks.py,sha256=2QdQZtJAX2rSGbyXKG1z9VF_siz1DUzdvzCgPkykxtU,173
-tasktree/types.py,sha256=wrBzO-Z2ebCTRjWyOWNvuCjqAq-74Zyb9E4FQ4beF38,3751
-tasktree-0.0.2.dist-info/METADATA,sha256=yUoIhImEiwFND5rcCwzVdHosfW6BMvwbvdQgqF8EjnE,9145
-tasktree-0.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-tasktree-0.0.2.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
-tasktree-0.0.2.dist-info/RECORD,,