etlplus 0.4.1__py3-none-any.whl → 0.4.7__py3-none-any.whl

etlplus/cli/app.py

@@ -28,12 +28,18 @@ Subcommands
 
 Notes
 -----
-- Use ``-`` to read from stdin and ``--output -`` (or ``load ... file -``) to
-    write to stdout.
-- ``extract`` supports ``--from`` and ``load`` supports ``--to`` to override
-    inferred resource types.
+- Use ``-`` to read from stdin or to write to stdout.
+- Commands ``extract`` and ``transform`` support the command-line option
+    ``--from`` to override inferred resource types.
+- Commands ``transform`` and ``load`` support the command-line option ``--to``
+    to override inferred resource types.
 """
 
+# Pylint struggles with large CLI surfaces that legitimately require
+# numerous arguments in a single module.
+# pylint: disable=too-many-lines
+# pylint: disable=too-many-arguments,too-many-positional-arguments
+
 from __future__ import annotations
 
 import argparse
@@ -41,6 +47,7 @@ import sys
 from collections.abc import Collection
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Annotated
 from typing import Final
 
 import typer
@@ -66,6 +73,19 @@ __all__ = [
 ]
 
 
+# SECTION: INTERNAL CONSTANTS =============================================== #
+
+
+_DB_SCHEMES = (
+    'postgres://',
+    'postgresql://',
+    'mysql://',
+)
+
+_SOURCE_CHOICES: Final[frozenset[str]] = frozenset(DataConnectorType.choices())
+_FORMAT_CHOICES: Final[frozenset[str]] = frozenset(FileFormat.choices())
+
+
 # SECTION: CONSTANTS ======================================================== #
 
 
@@ -75,67 +95,168 @@ CLI_DESCRIPTION: Final[str] = '\n'.join(
         '',
         '    Provide a subcommand and options. Examples:',
         '',
-        '    etlplus extract file in.csv -o out.json',
+        '    etlplus extract in.csv > out.json',
         '    etlplus validate in.json --rules \'{"required": ["id"]}\'',
-        '    etlplus transform in.json --operations \'{"select": ["id"]}\'',
-        '    etlplus load in.json file out.json',
+        (
+            '    etlplus transform --from file in.json '
+            '--operations \'{"select": ["id"]}\' --to file -o out.json'
+        ),
+        '    etlplus extract in.csv | etlplus load --to file out.json',
+        '    cat data.json | etlplus load --to api https://example.com/data',
         '',
-        '    Enforce error if --format is provided for files. Examples:',
+        '    Override format inference when extensions are misleading:',
         '',
-        '    etlplus extract file in.csv --format csv --strict-format',
-        '    etlplus load in.json file out.csv --format csv --strict-format',
+        '    etlplus extract data.txt --source-format csv',
+        '    etlplus load payload.bin --target-format json',
     ],
 )
 
 CLI_EPILOG: Final[str] = '\n'.join(
     [
-        'Environment:',
-        (
-            '    ETLPLUS_FORMAT_BEHAVIOR controls behavior when '
-            '--format is provided for files.'
-        ),
-        '    Values:',
-        '        - error|fail|strict: treat as error',
-        '        - warn (default): print a warning',
-        '        - ignore|silent: no message',
-        '',
-        'Note:',
-        '    --strict-format overrides the environment behavior.',
+        'Tip:',
+        '    --source-format and --target-format override format inference '
+        'based on filename extensions when needed.',
     ],
 )
 
 PROJECT_URL: Final[str] = 'https://github.com/Dagitali/ETLPlus'
 
-EXTRACT_ARGS = typer.Argument(
-    ...,
-    metavar='[SOURCE_TYPE] SOURCE',
-    help=(
-        'Extract from a SOURCE. You may provide SOURCE_TYPE explicitly as '
-        'the first positional argument, or omit it and use --from or let '
-        'etlplus infer it from the SOURCE.'
+
+# SECTION: TYPE ALIASES ==================================================== #
+
+
+SourceInputArg = Annotated[
+    str,
+    typer.Argument(
+        ...,
+        metavar='SOURCE',
+        help=(
+            'Extract from SOURCE. Use --from/--source-type to override the '
+            'inferred connector when needed.'
+        ),
     ),
-)
-LOAD_ARGS = typer.Argument(
-    ...,
-    metavar='[SOURCE] [TARGET_TYPE] TARGET',
-    help=(
-        'Load SOURCE into a target. SOURCE defaults to - (stdin). You may '
-        'provide legacy positional form: SOURCE TARGET_TYPE TARGET.'
+]
+
+StreamingSourceArg = Annotated[
+    str,
+    typer.Argument(
+        ...,
+        metavar='SOURCE',
+        help=(
+            'Data source to transform or validate (path, JSON payload, or '
+            '- for stdin).'
+        ),
     ),
-)
+]
 
+TargetInputArg = Annotated[
+    str,
+    typer.Argument(
+        ...,
+        metavar='TARGET',
+        help=(
+            'Load JSON data from stdin into TARGET. Use --to/--target-type '
+            'to override connector inference when needed. Source data must '
+            'be piped into stdin.'
+        ),
+    ),
+]
 
-# SECTION: INTERNAL CONSTANTS =============================================== #
+SourceOverrideOption = Annotated[
+    str | None,
+    typer.Option(
+        '--source-type',
+        metavar='CONNECTOR',
+        show_default=False,
+        rich_help_panel='I/O overrides',
+        help='Override the inferred source type (file, database, api).',
+    ),
+]
 
+TargetOverrideOption = Annotated[
+    str | None,
+    typer.Option(
+        '--target-type',
+        metavar='CONNECTOR',
+        show_default=False,
+        rich_help_panel='I/O overrides',
+        help='Override the inferred target type (file, database, api).',
+    ),
+]
 
-_DB_SCHEMES = (
-    'postgres://',
-    'postgresql://',
-    'mysql://',
-)
+SourceFormatOption = Annotated[
+    str | None,
+    typer.Option(
+        '--source-format',
+        metavar='FORMAT',
+        show_default=False,
+        rich_help_panel='Format overrides',
+        help=(
+            'Input payload format when SOURCE is - or an inline payload. '
+            'File sources infer format from the extension.'
+        ),
+    ),
+]
 
-_SOURCE_CHOICES: Final[frozenset[str]] = frozenset(DataConnectorType.choices())
-_FORMAT_CHOICES: Final[frozenset[str]] = frozenset(FileFormat.choices())
+StdinFormatOption = Annotated[
+    str | None,
+    typer.Option(
+        '--source-format',
+        metavar='FORMAT',
+        show_default=False,
+        rich_help_panel='Format overrides',
+        help='Input payload format when reading from stdin (default: json).',
+    ),
+]
+
+TargetFormatOption = Annotated[
+    str | None,
+    typer.Option(
+        '--target-format',
+        metavar='FORMAT',
+        show_default=False,
+        rich_help_panel='Format overrides',
+        help=(
+            'Payload format when TARGET is - or a non-file connector. File '
+            'targets infer format from the extension.'
+        ),
+    ),
+]
+
+OperationsJSONOption = Annotated[
+    str,
+    typer.Option(
+        '--operations',
+        help='Transformation operations as JSON string.',
+    ),
+]
+
+RulesJSONOption = Annotated[
+    str,
+    typer.Option(
+        '--rules',
+        help='Validation rules as JSON string.',
+    ),
+]
+
+TargetPathOption = Annotated[
+    str | None,
+    typer.Option(
+        '--target',
+        metavar='PATH',
+        help='Target file for transformed or validated output (- for stdout).',
+    ),
+]
+
+PipelineConfigOption = Annotated[
+    str,
+    typer.Option(
+        ...,
+        '--config',
+        metavar='PATH',
+        help='Path to pipeline YAML configuration file.',
+    ),
+]
 
 
 # SECTION: DATA CLASSES ===================================================== #
@@ -174,6 +295,32 @@ def _ensure_state(
     return ctx.obj
 
 
+def _format_namespace_kwargs(
+    *,
+    format_value: str | None,
+    default: str,
+) -> dict[str, object]:
+    """
+    Return common namespace kwargs for format handling.
+
+    Parameters
+    ----------
+    format_value : str | None
+        User-provided format value from the CLI option.
+    default : str
+        Default format to use when none is provided.
+
+    Returns
+    -------
+    dict[str, object]
+        Keyword arguments for format-related namespace attributes.
+    """
+    return {
+        'format': (format_value or default),
+        '_format_explicit': (format_value is not None),
+    }
+
+
 def _infer_resource_type(
     value: str,
 ) -> str:
@@ -198,12 +345,13 @@ def _infer_resource_type(
     val = (value or '').strip()
     low = val.lower()
 
-    if val == '-':
-        return 'file'
-    if low.startswith(('http://', 'https://')):
-        return 'api'
-    if low.startswith(_DB_SCHEMES):
-        return 'database'
+    match (val, low):
+        case ('-', _):
+            return 'file'
+        case (_, inferred) if inferred.startswith(('http://', 'https://')):
+            return 'api'
+        case (_, inferred) if inferred.startswith(_DB_SCHEMES):
+            return 'database'
 
     path = Path(val)
     if path.exists() or path.suffix:
@@ -240,6 +388,59 @@ def _infer_resource_type_or_exit(
         raise typer.BadParameter(str(exc)) from exc
 
 
+def _infer_resource_type_soft(
+    value: str | None,
+) -> str | None:
+    """
+    Make a best-effort inference that tolerates inline payloads.
+
+    Parameters
+    ----------
+    value : str | None
+        CLI value describing a source/target.
+
+    Returns
+    -------
+    str | None
+        Inferred resource type, or ``None`` if inference failed.
+    """
+    if value is None:
+        return None
+    try:
+        return _infer_resource_type(value)
+    except ValueError:
+        return None
+
+
+def _log_inferred_resource(
+    state: CliState,
+    *,
+    role: str,
+    value: str,
+    resource_type: str | None,
+) -> None:
+    """
+    Emit a uniform verbose message for inferred resource types.
+
+    Parameters
+    ----------
+    state : CliState
+        Current CLI state stored on the Typer context.
+    role : str
+        Friendly label for the resource (e.g., ``source`` or ``target``).
+    value : str
+        Resource value provided on the CLI.
+    resource_type : str | None
+        Inferred resource type or ``None`` if not inferred.
+    """
+    if not state.verbose or resource_type is None:
+        return
+    print(
+        f'Inferred {role}_type={resource_type} for {role}={value}',
+        file=sys.stderr,
+    )
+
+
 def _ns(
     **kwargs: object,
 ) -> argparse.Namespace:
@@ -286,13 +487,65 @@ def _optional_choice(
     return _validate_choice(value, choices, label=label)
 
 
+def _resolve_resource_type(
+    *,
+    explicit_type: str | None,
+    override_type: str | None,
+    value: str,
+    label: str,
+    conflict_error: str | None = None,
+    legacy_file_error: str | None = None,
+) -> str:
+    """
+    Resolve resource type preference order and validate it.
+
+    Parameters
+    ----------
+    explicit_type : str | None
+        Explicit resource type provided by the user.
+    override_type : str | None
+        Resource type provided by an overriding option.
+    value : str
+        Resource value to infer type from if no explicit or override type is
+        given.
+    label : str
+        Friendly label for error messages.
+    conflict_error : str | None
+        Error message to raise if there is a conflict between explicit and
+        override types.
+    legacy_file_error : str | None
+        Error message to raise if the explicit type is a legacy 'file' type.
+
+    Returns
+    -------
+    str
+        Resolved and validated resource type.
+
+    Raises
+    ------
+    typer.BadParameter
+        If there is a conflict between explicit and override types, or if the
+        explicit type is a legacy 'file' type.
+    """
+    if explicit_type is not None:
+        if override_type is not None and conflict_error:
+            raise typer.BadParameter(conflict_error)
+        if legacy_file_error and explicit_type.strip().lower() == 'file':
+            raise typer.BadParameter(legacy_file_error)
+        candidate = explicit_type
+    else:
+        candidate = override_type or _infer_resource_type_or_exit(value)
+    return _validate_choice(candidate, _SOURCE_CHOICES, label=label)
+
+
 def _stateful_namespace(
     state: CliState,
     *,
     command: str,
     **kwargs: object,
 ) -> argparse.Namespace:
-    """Attach CLI state toggles to a handler namespace.
+    """
+    Attach CLI state toggles to a handler namespace.
 
     Parameters
     ----------
@@ -432,34 +685,9 @@ def _root(
 @app.command('extract')
 def extract_cmd(
     ctx: typer.Context,
-    args: list[str] = EXTRACT_ARGS,
-    from_: str | None = typer.Option(
-        None,
-        '--from',
-        help='Override the inferred source type (file, database, api).',
-    ),
-    output: str | None = typer.Option(
-        None,
-        '-o',
-        '--output',
-        help='Output file to save extracted data (JSON). Use - for stdout.',
-    ),
-    strict_format: bool = typer.Option(
-        False,
-        '--strict-format',
-        help=(
-            'Treat providing --format for file sources as an error '
-            '(overrides environment behavior)'
-        ),
-    ),
-    source_format: str | None = typer.Option(
-        None,
-        '--format',
-        help=(
-            'Payload format when not a file (or when SOURCE is -). '
-            'For normal file paths, format is inferred from extension.'
-        ),
-    ),
+    source: SourceInputArg,
+    source_format: SourceFormatOption | None = None,
+    source_type: SourceOverrideOption | None = None,
 ) -> int:
     """
     Extract data from files, databases, or REST APIs.
@@ -468,267 +696,146 @@ def extract_cmd(
     ----------
     ctx : typer.Context
         Typer execution context provided to the command.
-    args : list[str]
-        Positional arguments: either SOURCE, or SOURCE_TYPE SOURCE.
-    from_ : str | None
-        Override the inferred source type.
-    output : str | None
-        Output file to save extracted data.
-    strict_format : bool
-        Whether to enforce strict format behavior.
-    source_format : str | None
+    source : SourceInputArg
+        Data source (file path, URL, DSN, or ``-`` for stdin).
+    source_format : SourceFormatOption | None, optional
         Payload format when not a file.
+    source_type : SourceOverrideOption | None, optional
+        Override the inferred source type.
 
     Returns
     -------
     int
         Zero on success.
 
-    Raises
-    ------
-    typer.BadParameter
-        If invalid parameters are provided.
-
     Examples
     --------
     - Extract from a file (type inferred):
         etlplus extract in.csv
-
-    - Extract from a file (explicit):
-        etlplus extract file in.csv
+    - Extract from a file (explicit via flag):
         etlplus extract --from file in.csv
-
     - Extract from an API:
         etlplus extract https://example.com/data.json
         etlplus extract --from api https://example.com/data.json
-
     - Extract from a database DSN:
         etlplus extract --from database postgresql://user:pass@host/db
-
     - Pipe into transform/load:
         etlplus extract in.csv \
         | etlplus transform --operations '{"select":["a"]}'
+
+    Notes
+    -----
+    - The ``extract`` command always writes JSON to stdout.
+    - CSV output is unsupported for this command.
+    - Use shell redirection (``>``) or pipelines to persist the output.
     """
     state = _ensure_state(ctx)
 
-    if len(args) > 2:
-        raise typer.BadParameter('Provide SOURCE, or SOURCE_TYPE SOURCE.')
-
-    from_ = _optional_choice(from_, _SOURCE_CHOICES, label='from')
+    source_type = _optional_choice(
+        source_type,
+        _SOURCE_CHOICES,
+        label='source_type',
+    )
     source_format = _optional_choice(
         source_format,
         _FORMAT_CHOICES,
-        label='format',
+        label='source_format',
     )
 
-    if len(args) == 2:
-        if from_ is not None:
-            raise typer.BadParameter(
-                'Do not combine --from with an explicit SOURCE_TYPE.',
-            )
-        source_type = _validate_choice(
-            args[0],
-            _SOURCE_CHOICES,
-            label='source_type',
-        )
-        source = args[1]
-    else:
-        source = args[0]
-        if from_ is not None:
-            source_type = from_
-        else:
-            source_type = _infer_resource_type_or_exit(source)
-
-        source_type = _validate_choice(
-            source_type,
-            _SOURCE_CHOICES,
-            label='source_type',
-        )
-
-    if state.verbose:
-        print(
-            f'Inferred source_type={source_type} for source={source}',
-            file=sys.stderr,
-        )
+    resolved_source = source
+    resolved_source_type = source_type or _infer_resource_type_or_exit(
+        resolved_source,
+    )
 
-    ns = _stateful_namespace(
+    _log_inferred_resource(
         state,
-        command='extract',
-        source_type=source_type,
-        source=source,
-        output=output,
-        strict_format=strict_format,
-        format=(source_format or 'json'),
-        _format_explicit=(source_format is not None),
+        role='source',
+        value=resolved_source,
+        resource_type=resolved_source_type,
     )
-    return int(cmd_extract(ns))
 
-
-@app.command('validate')
-def validate_cmd(
-    ctx: typer.Context,
-    source: str = typer.Argument(
-        '-',
-        metavar='SOURCE',
-        help=(
-            'Data source to validate (file path, JSON string, or - for stdin).'
-        ),
-    ),
-    rules: str = typer.Option(
-        '{}',
-        '--rules',
-        help='Validation rules as JSON string',
-    ),
-    output: str | None = typer.Option(
-        None,
-        '-o',
-        '--output',
-        help='Output file to save validated data (JSON). Use - for stdout.',
-    ),
-    input_format: str | None = typer.Option(
-        None,
-        '--input-format',
-        help='Input payload format for stdin (json or csv).',
-    ),
-) -> int:
-    """
-    Validate data against JSON-described rules.
-
-    Parameters
-    ----------
-    ctx : typer.Context
-        Typer execution context provided to the command.
-    source : str
-        Data source (file path or ``-`` for stdin).
-    rules : str
-        Validation rules as a JSON string.
-    output : str | None
-        Optional output path. Use ``-`` for stdout.
-    input_format : str | None
-        Optional stdin format hint (json or csv).
-
-    Returns
-    -------
-    int
-        Zero on success.
-    """
-    input_format = _optional_choice(
-        input_format,
-        _FORMAT_CHOICES,
-        label='input_format',
+    format_kwargs = _format_namespace_kwargs(
+        format_value=source_format,
+        default='json',
     )
-
-    state = _ensure_state(ctx)
-
     ns = _stateful_namespace(
         state,
-        command='validate',
-        source=source,
-        rules=json_type(rules),
-        output=output,
-        input_format=input_format,
+        command='extract',
+        source_type=resolved_source_type,
+        source=resolved_source,
+        **format_kwargs,
     )
-    return int(cmd_validate(ns))
+    return int(cmd_extract(ns))
 
 
-@app.command('transform')
-def transform_cmd(
+@app.command('list')
+def list_cmd(
     ctx: typer.Context,
-    source: str = typer.Argument(
-        '-',
-        metavar='SOURCE',
-        help=(
-            'Data source to transform '
-            '(file path, JSON string, or - for stdin).'
-        ),
-    ),
-    operations: str = typer.Option(
-        '{}',
-        '--operations',
-        help='Transformation operations as JSON string',
+    config: PipelineConfigOption,
+    jobs: bool = typer.Option(
+        False,
+        '--jobs',
+        help='List available job names and exit',
     ),
-    output: str | None = typer.Option(
-        None,
-        '-o',
-        '--output',
-        help='Output file to save transformed data (JSON). Use - for stdout.',
+    pipelines: bool = typer.Option(
+        False,
+        '--pipelines',
+        help='List ETL pipelines',
     ),
-    input_format: str | None = typer.Option(
-        None,
-        '--input-format',
-        help='Input payload format for stdin (json or csv).',
+    sources: bool = typer.Option(False, '--sources', help='List data sources'),
+    targets: bool = typer.Option(False, '--targets', help='List data targets'),
+    transforms: bool = typer.Option(
+        False,
+        '--transforms',
+        help='List data transforms',
     ),
 ) -> int:
     """
-    Transform records using JSON-described operations.
+    Print ETL entities from a pipeline YAML configuration.
 
     Parameters
     ----------
     ctx : typer.Context
         Typer execution context provided to the command.
-    source : str
-        Data source (file path or ``-`` for stdin).
-    operations : str
-        Transformation operations as a JSON string.
-    output : str | None
-        Optional output path. Use ``-`` for stdout.
-    input_format : str | None
-        Optional stdin format hint (json or csv).
+    config : PipelineConfigOption
+        Path to pipeline YAML configuration file.
+    jobs : bool, optional
+        If True, list available job names and exit.
+    pipelines : bool, optional
+        If True, list ETL pipelines.
+    sources : bool, optional
+        If True, list data sources.
+    targets : bool, optional
+        If True, list data targets.
+    transforms : bool, optional
+        If True, list data transforms.
 
     Returns
     -------
     int
         Zero on success.
     """
-    input_format = _optional_choice(
-        input_format,
-        _FORMAT_CHOICES,
-        label='input_format',
-    )
-
     state = _ensure_state(ctx)
-
     ns = _stateful_namespace(
         state,
-        command='transform',
-        source=source,
-        operations=json_type(operations),
-        output=output,
-        input_format=input_format,
+        command='list',
+        config=config,
+        pipelines=pipelines,
+        jobs=jobs,
+        sources=sources,
+        targets=targets,
+        transforms=transforms,
     )
-    return int(cmd_transform(ns))
+    return int(cmd_list(ns))
 
 
 @app.command('load')
 def load_cmd(
     ctx: typer.Context,
-    args: list[str] = LOAD_ARGS,
-    to: str | None = typer.Option(
-        None,
-        '--to',
-        help='Override the inferred target type (file, database, api).',
-    ),
-    strict_format: bool = typer.Option(
-        False,
-        '--strict-format',
-        help=(
-            'Treat providing --format for file targets as an error '
-            '(overrides environment behavior)'
-        ),
-    ),
-    target_format: str | None = typer.Option(
-        None,
-        '--format',
-        help=(
-            'Payload format when not a file (or when TARGET is -). '
-            'For normal file targets, format is inferred from extension.'
-        ),
-    ),
-    input_format: str | None = typer.Option(
-        None,
-        '--input-format',
-        help='Input payload format for stdin (json or csv).',
-    ),
+    target: TargetInputArg,
+    source_format: StdinFormatOption | None = None,
+    target_format: TargetFormatOption | None = None,
+    target_type: TargetOverrideOption | None = None,
 ) -> int:
     """
     Load data into a file, database, or REST API.
@@ -737,107 +844,89 @@ def load_cmd(
     ----------
     ctx : typer.Context
         Typer execution context provided to the command.
-    args : list[str]
-        Positional arguments: TARGET, SOURCE TARGET, or SOURCE TARGET_TYPE
-        TARGET.
-    to : str | None
+    target : TargetInputArg
+        Load destination (file path, URL/DSN, or ``-`` for stdout).
+    source_format : StdinFormatOption | None, optional
+        Hint for parsing stdin payloads (json or csv).
+    target_format : TargetFormatOption | None, optional
+        Payload format when not a file target (or when TARGET is ``-``).
+    target_type : TargetOverrideOption | None, optional
         Override the inferred target type.
-    strict_format : bool
-        Whether to enforce strict format behavior.
-    target_format : str | None
-        Payload format when not a file.
-    input_format : str | None
-        Input payload format for stdin.
 
     Returns
     -------
     int
         Zero on success.
 
-    Raises
-    ------
-    typer.BadParameter
-        If the arguments are invalid
-
     Examples
     --------
     - Pipe into a file:
         etlplus extract in.csv \
         | etlplus transform --operations '{"select":["a"]}' \
         | etlplus load --to file out.json
-
-    - Legacy form:
-        etlplus load in.json file out.json
-
+    - Read from stdin and write to a file:
+        etlplus load out.json
     - Write to stdout:
-        etlplus load in.json file -
+        etlplus load --to file -
+
+    Notes
+    -----
+    - The ``load`` command reads JSON from stdin.
+    - CSV input is unsupported unless ``--source-format csv`` is provided.
+    - Convert upstream before piping into ``load`` when working with other
+        formats.
     """
     state = _ensure_state(ctx)
 
-    if len(args) > 3:
-        raise typer.BadParameter(
-            'Provide TARGET, SOURCE TARGET, or SOURCE TARGET_TYPE TARGET.',
-        )
-
-    to = _optional_choice(to, _SOURCE_CHOICES, label='to')
-    target_format = _optional_choice(
-        target_format,
+    source_format = _optional_choice(
+        source_format,
         _FORMAT_CHOICES,
-        label='format',
+        label='source_format',
     )
-    input_format = _optional_choice(
-        input_format,
-        _FORMAT_CHOICES,
-        label='input_format',
-    )
-
-    # Parse positional args.
-    match args:
-        case [source, target_type_raw, target] if to is None:
-            target_type = _validate_choice(
-                target_type_raw,
-                _SOURCE_CHOICES,
-                label='target_type',
-            )
-        case [_, _, _]:
-            raise typer.BadParameter(
-                'Do not combine --to with the legacy SOURCE TARGET_TYPE '
-                'TARGET form.',
-            )
-        case [source, target]:
-            target_type = to or _infer_resource_type_or_exit(target)
-        case [solo_target]:
-            source = '-'
-            target = solo_target
-            target_type = to or _infer_resource_type_or_exit(target)
-        case []:
-            raise typer.BadParameter(
-                'Provide TARGET, SOURCE TARGET, or legacy SOURCE '
-                'TARGET_TYPE TARGET.',
-            )
-
-    target_type = _validate_choice(
+    target_type = _optional_choice(
         target_type,
         _SOURCE_CHOICES,
         label='target_type',
     )
+    target_format = _optional_choice(
+        target_format,
+        _FORMAT_CHOICES,
+        label='target_format',
+    )
 
-    if state.verbose:
-        print(
-            f'Inferred target_type={target_type} for target={target}',
-            file=sys.stderr,
-        )
+    resolved_target = target
+    resolved_target_type = target_type or _infer_resource_type_or_exit(
+        resolved_target,
+    )
+
+    resolved_source_value = '-'
+    resolved_source_type = _infer_resource_type_soft(resolved_source_value)
+
+    _log_inferred_resource(
+        state,
+        role='source',
+        value=resolved_source_value,
+        resource_type=resolved_source_type,
+    )
+    _log_inferred_resource(
+        state,
+        role='target',
+        value=resolved_target,
+        resource_type=resolved_target_type,
+    )
 
+    format_kwargs = _format_namespace_kwargs(
+        format_value=target_format,
+        default='json',
+    )
     ns = _stateful_namespace(
         state,
         command='load',
-        source=source,
-        target_type=target_type,
-        target=target,
-        strict_format=strict_format,
-        format=(target_format or 'json'),
-        _format_explicit=(target_format is not None),
-        input_format=input_format,
+        source=resolved_source_value,
+        source_format=source_format,
+        target_type=resolved_target_type,
+        target=resolved_target,
+        **format_kwargs,
     )
     return int(cmd_load(ns))
 
@@ -845,21 +934,22 @@ def load_cmd(
 @app.command('pipeline')
 def pipeline_cmd(
     ctx: typer.Context,
-    config: str = typer.Option(
-        ...,
-        '--config',
-        help='Path to pipeline YAML configuration file',
+    config: PipelineConfigOption,
+    job: str | None = typer.Option(
+        None,
+        '--job',
+        metavar='JOB',
+        help='Run a specific job by name',
     ),
-    list_: bool = typer.Option(
+    jobs: bool = typer.Option(
         False,
-        '--list',
+        '--jobs',
         help='List available job names and exit',
     ),
-    run_job: str | None = typer.Option(
+    pipeline: str | None = typer.Option(
         None,
-        '--run',
-        metavar='JOB',
-        help='Run a specific job by name',
+        '--pipeline',
+        help='Run a specific pipeline by name',
     ),
 ) -> int:
     """
@@ -869,12 +959,14 @@ def pipeline_cmd(
     ----------
     ctx : typer.Context
         Typer execution context provided to the command.
-    config : str
+    config : PipelineConfigOption
         Path to pipeline YAML configuration file.
-    list_ : bool
-        If True, list available job names and exit.
-    run_job : str | None
+    job : str | None, optional
         Name of a specific job to run.
+    jobs : bool, optional
+        If True, list available job names and exit.
+    pipeline : str | None, optional
+        Name of a specific pipeline to run.
 
     Returns
     -------
@@ -882,54 +974,47 @@ def pipeline_cmd(
         Zero on success.
     """
     state = _ensure_state(ctx)
+    run_target = job or pipeline
     ns = _stateful_namespace(
         state,
         command='pipeline',
         config=config,
-        list=list_,
-        run=run_job,
+        list=jobs,
+        run=run_target,
     )
     return int(cmd_pipeline(ns))
 
 
-@app.command('list')
-def list_cmd(
+@app.command('run')
+def run_cmd(
     ctx: typer.Context,
-    config: str = typer.Option(
-        ...,
-        '--config',
-        help='Path to pipeline YAML configuration file',
-    ),
-    pipelines: bool = typer.Option(
-        False,
-        '--pipelines',
-        help='List ETL pipelines',
+    config: PipelineConfigOption,
+    job: str | None = typer.Option(
+        None,
+        '-j',
+        '--job',
+        help='Name of the job to run',
     ),
-    sources: bool = typer.Option(False, '--sources', help='List data sources'),
-    targets: bool = typer.Option(False, '--targets', help='List data targets'),
-    transforms: bool = typer.Option(
-        False,
-        '--transforms',
-        help='List data transforms',
+    pipeline: str | None = typer.Option(
+        None,
+        '-p',
+        '--pipeline',
+        help='Name of the pipeline to run',
     ),
 ) -> int:
     """
-    Print ETL entities from a pipeline YAML configuration.
+    Execute an ETL job or pipeline from a YAML configuration.
 
     Parameters
     ----------
     ctx : typer.Context
         Typer execution context provided to the command.
-    config : str
+    config : PipelineConfigOption
         Path to pipeline YAML configuration file.
-    pipelines : bool
-        If True, list ETL pipelines.
-    sources : bool
-        If True, list data sources.
-    targets : bool
-        If True, list data targets.
-    transforms : bool
-        If True, list data transforms.
+    job : str | None, optional
+        Name of the job to run.
+    pipeline : str | None, optional
+        Name of the pipeline to run.
 
     Returns
     -------
@@ -939,62 +1024,216 @@ def list_cmd(
     state = _ensure_state(ctx)
     ns = _stateful_namespace(
         state,
-        command='list',
+        command='run',
         config=config,
-        pipelines=pipelines,
-        sources=sources,
-        targets=targets,
-        transforms=transforms,
+        job=job,
+        pipeline=pipeline,
     )
-    return int(cmd_list(ns))
+    return int(cmd_run(ns))
 
 
-@app.command('run')
-def run_cmd(
+@app.command('transform')
+def transform_cmd(
     ctx: typer.Context,
-    config: str = typer.Option(
-        ...,
-        '--config',
-        help='Path to pipeline YAML configuration file',
-    ),
-    job: str | None = typer.Option(
-        None,
-        '-j',
-        '--job',
-        help='Name of the job to run',
-    ),
-    pipeline: str | None = typer.Option(
-        None,
-        '-p',
-        '--pipeline',
-        help='Name of the pipeline to run',
-    ),
+    operations: OperationsJSONOption = '{}',
+    source: StreamingSourceArg = '-',
+    source_format: SourceFormatOption | None = None,
+    source_type: SourceOverrideOption | None = None,
+    target: TargetPathOption | None = None,
+    target_format: TargetFormatOption | None = None,
+    target_type: TargetOverrideOption | None = None,
 ) -> int:
     """
-    Execute an ETL job or pipeline from a YAML configuration.
+    Transform records using JSON-described operations.
 
     Parameters
     ----------
     ctx : typer.Context
         Typer execution context provided to the command.
-    config : str
-        Path to pipeline YAML configuration file.
-    job : str | None
-        Name of the job to run.
-    pipeline : str | None
-        Name of the pipeline to run.
+    operations : OperationsJSONOption, optional
+        Transformation operations as a JSON string.
+    source : StreamingSourceArg, optional
+        Data source (file path or ``-`` for stdin).
+    source_format : SourceFormatOption | None, optional
+        Input payload format when not a file (or when SOURCE is -).
+    source_type : SourceOverrideOption | None, optional
+        Override the inferred source type.
+    target : TargetPathOption | None, optional
+        Optional output path. Use ``-`` for stdout.
+    target_format : TargetFormatOption | None, optional
+        Output payload format when not a file target (or when OUTPUT is -).
+        Accepts ``--target-format``.
+    target_type : TargetOverrideOption | None, optional
+        Override the inferred target type.
 
     Returns
     -------
     int
         Zero on success.
+
+    Examples
+    --------
+    - Transform data from a file and write to another file:
+        etlplus transform --from file in.json \
+        --operations '{"select": ["id", "name"]}' \
+        --to file out.json
+    - Transform data from stdin and write to stdout:
+        cat in.json \
+        | etlplus transform \
+        --operations '{"filter": {"field": "age", "gt": 30}}'
+    - Transform data from a file and write to stdout:
+        etlplus transform --from file in.csv \
+        --source-format csv \
+        --operations '{"select": ["id", "email"]}'
+    - Transform data from stdin and write to a file:
+        cat in.json \
+        | etlplus transform --operations '{"sort": ["-created_at"]}' \
+        --to file out.json
+
+    Notes
+    -----
+    - The ``transform`` command reads JSON from stdin when SOURCE is ``-``.
+    - CSV input is unsupported for this command.
+    - Convert upstream before piping into ``transform``.
     """
     state = _ensure_state(ctx)
+
+    source_format = _optional_choice(
+        source_format,
+        _FORMAT_CHOICES,
+        label='source_format',
+    )
+    source_type = _optional_choice(
+        source_type,
+        _SOURCE_CHOICES,
+        label='source_type',
+    )
+    target_format = _optional_choice(
+        target_format,
+        _FORMAT_CHOICES,
+        label='target_format',
+    )
+    target_format_kwargs = _format_namespace_kwargs(
+        format_value=target_format,
+        default='json',
+    )
+    target_type = _optional_choice(
+        target_type,
+        _SOURCE_CHOICES,
+        label='target_type',
+    )
+
+    resolved_source_type = source_type or _infer_resource_type_soft(source)
+    resolved_source_value = source if source is not None else '-'
+    resolved_target_value = target if target is not None else '-'
+
+    if resolved_source_type is not None:
+        resolved_source_type = _validate_choice(
+            resolved_source_type,
+            _SOURCE_CHOICES,
+            label='source_type',
+        )
+
+    resolved_target_type = _resolve_resource_type(
+        explicit_type=None,
+        override_type=target_type,
+        value=resolved_target_value,
+        label='target_type',
+    )
+
+    _log_inferred_resource(
+        state,
+        role='source',
+        value=resolved_source_value,
+        resource_type=resolved_source_type,
+    )
+    _log_inferred_resource(
+        state,
+        role='target',
+        value=resolved_target_value,
+        resource_type=resolved_target_type,
+    )
+
     ns = _stateful_namespace(
         state,
-        command='run',
-        config=config,
-        job=job,
-        pipeline=pipeline,
+        command='transform',
+        source=resolved_source_value,
+        source_type=resolved_source_type,
+        operations=json_type(operations),
+        target=resolved_target_value,
+        source_format=source_format,
+        target_type=resolved_target_type,
+        target_format=target_format_kwargs['format'],
+        **target_format_kwargs,
     )
-    return int(cmd_run(ns))
+    return int(cmd_transform(ns))
+
+
+@app.command('validate')
+def validate_cmd(
+    ctx: typer.Context,
+    rules: RulesJSONOption = '{}',
+    source: StreamingSourceArg = '-',
+    source_format: SourceFormatOption | None = None,
+    source_type: SourceOverrideOption | None = None,
+    target: TargetPathOption | None = None,
+) -> int:
+    """
+    Validate data against JSON-described rules.
+
+    Parameters
+    ----------
+    ctx : typer.Context
+        Typer execution context provided to the command.
+    rules : RulesJSONOption, optional
+        Validation rules as a JSON string.
+    source : StreamingSourceArg, optional
+        Data source (file path or ``-`` for stdin).
+    source_format : SourceFormatOption | None, optional
+        Optional stdin format hint (JSON or CSV) when SOURCE is ``-``.
+    source_type : SourceOverrideOption | None, optional
+        Override the inferred source type when heuristics fail.
+    target : TargetPathOption | None, optional
+        Optional output path. Use ``-`` for stdout.
+
+    Returns
+    -------
+    int
+        Zero on success.
+    """
+    source_format = _optional_choice(
+        source_format,
+        _FORMAT_CHOICES,
+        label='source_format',
+    )
+    source_type = _optional_choice(
+        source_type,
+        _SOURCE_CHOICES,
+        label='source_type',
+    )
+    source_format_kwargs = _format_namespace_kwargs(
+        format_value=source_format,
+        default='json',
+    )
+
+    state = _ensure_state(ctx)
+    resolved_source_type = source_type or _infer_resource_type_soft(source)
+
+    _log_inferred_resource(
+        state,
+        role='source',
+        value=source,
+        resource_type=resolved_source_type,
+    )
+
+    ns = _stateful_namespace(
+        state,
+        command='validate',
+        source=source,
+        source_type=resolved_source_type,
+        rules=json_type(rules),  # convert CLI string to dict
+        target=target,
+        source_format=source_format,
+        **source_format_kwargs,
+    )
+    return int(cmd_validate(ns))