mayhem-cli 0.5.1__py3-none-any.whl

mayhem/cli/app.py

@@ -0,0 +1,154 @@
+"""Root CLI assembly and top-level error -> exit-code mapping.
+
+The tree is registered here; every group is a :class:`PrefixGroup`, so unique
+prefix resolution works at every level. ``main()`` is the single place where
+mayhem exceptions become documented exit codes — handlers raise typed domain
+errors and never format exit codes themselves.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+import click
+
+from mayhem.cli import style
+from mayhem.cli.campaign import campaign
+from mayhem.cli.config_cmd import config
+from mayhem.cli.context import CliContext
+from mayhem.cli.dependency import dependency
+from mayhem.cli.exit_codes import ExitCode
+from mayhem.cli.experiment import experiment
+from mayhem.cli.lifecycle import history, janitor, maniac, plan, recover, run, status, validate
+from mayhem.cli.resolver import PREFIX_HELP, CommandResolutionError, PrefixGroup
+from mayhem.cli.toolkit import toolkit
+from mayhem.cli.topology import topology
+from mayhem.controller.planner import PlanningError
+from mayhem.controller.safety import SafetyRefusedError
+from mayhem.domain.errors import (
+    DomainError,
+    InvariantViolationError,
+    SchemaValidationError,
+    TargetDriftError,
+    TargetResolutionError,
+)
+from mayhem.domain.maniac import ManiacError
+from mayhem.toolkit.tool_runner import ToolError
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+_STATE: dict[str, str] = {"debug": "", "engine": ""}
+
+
+@click.group(
+    cls=PrefixGroup,
+    epilog=PREFIX_HELP,
+    help="mayhem — safe-by-construction chaos experiments.",
+    no_args_is_help=True,
+)
+@click.option("--db", default=None, help="SQLite database path [default: mayhem.db].")
+@click.option("--config", "config_path", default=None, help="Path to mayhem.yaml.")
+@click.option("--profile", default=None, help="Configuration profile name.")
+@click.option("--allow-critical", is_flag=True, help="Acknowledge critical-risk faults.")
+@click.option(
+    "--skip-gate",
+    is_flag=True,
+    help="Run even when the impact gate proved some faults inert.",
+)
+@click.option(
+    "-p",
+    "--podman",
+    "podman",
+    is_flag=True,
+    default=False,
+    help="Use Podman instead of Docker.",
+)
+@click.option("-d", "--debug", is_flag=True, help="Re-raise errors instead of rendering them.")
+@click.pass_context
+def app(
+    ctx: click.Context,
+    db: str | None,
+    config_path: str | None,
+    profile: str | None,
+    allow_critical: bool,
+    skip_gate: bool,
+    podman: bool,
+    debug: bool,
+) -> None:
+    _STATE["debug"] = "1" if debug else ""
+    _STATE["engine"] = "podman" if podman else ""
+    _STATE["gate"] = "0" if skip_gate else "1"
+    ctx.obj = CliContext(
+        db=db or "mayhem.db",
+        config=config_path,
+        profile=profile,
+        allow_critical=allow_critical,
+        debug=debug,
+    )
+
+
+for _cmd in (validate, plan, run, maniac, status, history, recover, janitor, dependency):
+    app.add_command(_cmd)
+for _group in (experiment, topology, toolkit, config, campaign):
+    app.add_command(_group)
+app.add_command(config, "cfg")
+
+
+def _fail(message: str, code: int) -> int:
+    click.echo(f"{style.danger('error:')} {message}", err=True)
+    return code
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Dispatch argv and map every failure mode onto a documented exit code."""
+    try:
+        app.main(
+            args=list(argv) if argv is not None else sys.argv[1:],
+            prog_name="mayhem",
+            standalone_mode=False,
+            windows_expand_args=False,
+        )
+    except CommandResolutionError as exc:
+        code = ExitCode.USAGE_ERROR if not exc.candidates else ExitCode.AMBIGUOUS_COMMAND
+        return _fail(str(exc), int(code))
+    except click.UsageError as exc:
+        exc.show()
+        return int(ExitCode.USAGE_ERROR)
+    except click.exceptions.Exit as exc:
+        return int(exc.exit_code)
+    except click.exceptions.Abort:
+        return _fail("aborted.", int(ExitCode.GENERAL_FAILURE))
+    except SafetyRefusedError as exc:
+        return _fail(f"safety refused: {exc}", int(ExitCode.SAFETY_REFUSAL))
+    except SchemaValidationError as exc:
+        code = (
+            ExitCode.CONFIG_ERROR
+            if getattr(exc, "subject", "") == "config"
+            else ExitCode.VALIDATION_ERROR
+        )
+        return _fail(str(exc), int(code))
+    except (
+        InvariantViolationError,
+        ManiacError,
+        PlanningError,
+        TargetResolutionError,
+        TargetDriftError,
+        FileNotFoundError,
+    ) as exc:
+        return _fail(str(exc), int(ExitCode.VALIDATION_ERROR))
+    except ToolError as exc:
+        return _fail(str(exc), int(ExitCode.TOOLKIT_ERROR))
+    except DomainError as exc:
+        return _fail(str(exc), int(ExitCode.GENERAL_FAILURE))
+    except Exception as exc:  # last-resort boundary; see exit-code contract
+        if _STATE["debug"]:
+            raise
+        return _fail(f"{type(exc).__name__}: {exc}", int(ExitCode.GENERAL_FAILURE))
+    return int(ExitCode.SUCCESS)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mayhem/cli/campaign.py

@@ -0,0 +1,496 @@
+"""CLI commands for campaigns (ADR-0023)."""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC
+from typing import TYPE_CHECKING
+
+import click
+
+from mayhem.cli import style
+from mayhem.cli.exit_codes import ExitCode
+from mayhem.cli.resolver import make_group
+from mayhem.cli.services import (
+    build_graph,
+    engine_for,
+    open_store,
+    plan_from_spec,
+    prepare,
+    run_campaign_sequence,
+)
+
+if TYPE_CHECKING:
+    from click import Context
+
+    from mayhem.controller.executor import RunResult
+
+
+def _ctx(ctx: Context):
+    from mayhem.cli.context import CliContext
+
+    obj = ctx.obj
+    assert isinstance(obj, CliContext)
+    return obj
+
+
+campaign = make_group("campaign", "Create, list, and inspect chaos campaigns.")
+
+
+@campaign.command("list")
+@click.option("--db", "db_opt", default=None, help="SQLite database path.")
+@click.option("--json", "as_json", is_flag=True, help="Emit as JSON.")
+@click.pass_context
+def list_campaigns(ctx: Context, db_opt: str | None, as_json: bool) -> None:
+    """List all campaigns."""
+    db = db_opt or _ctx(ctx).db
+    store = open_store(db)
+    try:
+        rows = store.query("SELECT id, name, status, created_at FROM campaigns ORDER BY created_at")
+        if as_json:
+            click.echo(json.dumps([dict(r) for r in rows], indent=2))
+        else:
+            if not rows:
+                click.echo("No campaigns.")
+                return
+            for row in rows:
+                click.echo(f"{row['id']:<32} {row['name']:<24} {style.state(row['status'])}")
+    finally:
+        store.close()
+
+
+@campaign.command("create")
+@click.argument("name")
+@click.option("--description", "-d", default="", help="Campaign description.")
+@click.option("--hypothesis", "-h", default=None, help="Campaign hypothesis.")
+@click.option("--db", "db_opt", default=None, help="SQLite database path.")
+@click.option("--json", "as_json", is_flag=True, help="Emit as JSON.")
+@click.pass_context
+def create_campaign(
+    ctx: Context,
+    name: str,
+    description: str,
+    hypothesis: str | None,
+    db_opt: str | None,
+    as_json: bool,
+) -> None:
+    """Create a new campaign in draft status."""
+    import uuid
+    from datetime import datetime
+
+    db = db_opt or _ctx(ctx).db
+    store = open_store(db)
+    try:
+        campaign_id = f"camp-{uuid.uuid4().hex[:12]}"
+        now = datetime.now(UTC).isoformat()
+        with store.write() as conn:
+            conn.execute(
+                "INSERT INTO campaigns (id, name, description, status, created_at, updated_at)"
+                " VALUES (?, ?, ?, 'draft', ?, ?)",
+                (campaign_id, name, description, now, now),
+            )
+        if as_json:
+            row = store.query(
+                "SELECT id, name, description, status, created_at, updated_at"
+                " FROM campaigns WHERE id = ?",
+                (campaign_id,),
+            )
+            click.echo(json.dumps(dict(row[0]), indent=2))
+        else:
+            click.echo(style.ok(f"Campaign '{campaign_id}' created successfully."))
+    finally:
+        store.close()
+
+
+@campaign.command("show")
+@click.argument("campaign_id")
+@click.option("--db", "db_opt", default=None, help="SQLite database path.")
+@click.option("--json", "as_json", is_flag=True, help="Emit as JSON.")
+@click.pass_context
+def show_campaign(ctx: Context, campaign_id: str, db_opt: str | None, as_json: bool) -> None:
+    """Show campaign details."""
+    db = db_opt or _ctx(ctx).db
+    store = open_store(db)
+    try:
+        rows = store.query("SELECT * FROM campaigns WHERE id = ?", (campaign_id,))
+        if not rows:
+            click.echo(f"{style.danger('error:')} Campaign {campaign_id!r} not found.", err=True)
+            raise FileNotFoundError(f"campaign not found: {campaign_id}")
+        row = dict(rows[0])
+        runs = [
+            dict(r)
+            for r in store.query(
+                "SELECT run_id, data_json, timestamp FROM observations"
+                " WHERE source = ? AND kind = 'campaign_run' ORDER BY timestamp",
+                (campaign_id,),
+            )
+        ]
+        if as_json:
+            for key in ("experiments_json", "window_json", "policy_json", "labels_json"):
+                if row.get(key):
+                    row[key] = json.loads(row[key])
+            parsed_runs = []
+            for r in runs:
+                spec = json.loads(r["data_json"]).get("spec", "")
+                parsed_runs.append(
+                    {"spec_path": spec, "run_id": r["run_id"], "timestamp": r["timestamp"]}
+                )
+            row["runs"] = parsed_runs
+            click.echo(json.dumps(row, indent=2))
+        else:
+            click.echo(f"Campaign: {row['name']} ({row['id']})")
+            click.echo(f"  Status: {style.state(row['status'])}")
+            if row.get("description"):
+                click.echo(f"  Description: {row['description']}")
+            click.echo(f"  Created: {row['created_at']}")
+            if runs:
+                click.echo("  Runs:")
+                for r in runs:
+                    spec = json.loads(r["data_json"]).get("spec", "?")
+                    click.echo(f"    - {spec} -> {r['run_id']} ({r['timestamp']})")
+    finally:
+        store.close()
+
+
+@campaign.command("status")
+@click.argument("campaign_id")
+@click.option("--db", "db_opt", default=None, help="SQLite database path.")
+@click.pass_context
+def campaign_status(ctx: Context, campaign_id: str, db_opt: str | None) -> None:
+    """Show the status of a campaign."""
+    db = db_opt or _ctx(ctx).db
+    store = open_store(db)
+    try:
+        rows = store.query("SELECT id, name, status FROM campaigns WHERE id = ?", (campaign_id,))
+        if not rows:
+            click.echo(f"{style.danger('error:')} Campaign {campaign_id!r} not found.", err=True)
+            raise FileNotFoundError(f"campaign not found: {campaign_id}")
+        row = dict(rows[0])
+        click.echo(f"{row['id']} {row['name']} {style.state(row['status'])}")
+    finally:
+        store.close()
+
+
+@campaign.command("delete")
+@click.argument("campaign_id")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation.")
+@click.option("--db", "db_opt", default=None, help="SQLite database path.")
+@click.option("--json", "as_json", is_flag=True, help="Emit as JSON.")
+@click.pass_context
+def delete_campaign(
+    ctx: Context, campaign_id: str, yes: bool, db_opt: str | None, as_json: bool
+) -> None:
+    """Delete a campaign (only drafts)."""
+    db = db_opt or _ctx(ctx).db
+    store = open_store(db)
+    try:
+        rows = store.query("SELECT id, name, status FROM campaigns WHERE id = ?", (campaign_id,))
+        if not rows:
+            click.echo(f"{style.danger('error:')} Campaign {campaign_id!r} not found.", err=True)
+            raise FileNotFoundError(f"campaign not found: {campaign_id}")
+        row = dict(rows[0])
+        if row["status"] != "draft":
+            click.echo(
+                f"Cannot delete campaign in '{row['status']}' status (must be 'draft').",
+                err=True,
+            )
+            raise click.UsageError(f"cannot delete campaign in '{row['status']}' status")
+        if not yes:
+            click.confirm(f"Delete campaign '{row['name']}' ({campaign_id})?", abort=True)
+        with store.write() as conn:
+            conn.execute("DELETE FROM campaigns WHERE id = ?", (campaign_id,))
+        if as_json:
+            click.echo(json.dumps({"deleted": campaign_id}))
+        else:
+            click.echo(style.ok(f"Campaign '{campaign_id}' deleted."))
+    finally:
+        store.close()
+
+
+@campaign.command("start")
+@click.argument("campaign_id")
+@click.option("--db", "db_opt", default=None, help="SQLite database path.")
+@click.option("--json", "as_json", is_flag=True, help="Emit as JSON.")
+@click.pass_context
+def start_campaign(ctx: Context, campaign_id: str, db_opt: str | None, as_json: bool) -> None:
+    """Start a draft campaign (set status to 'running')."""
+    from datetime import datetime
+
+    db = db_opt or _ctx(ctx).db
+    store = open_store(db)
+    try:
+        rows = store.query("SELECT id, name, status FROM campaigns WHERE id = ?", (campaign_id,))
+        if not rows:
+            click.echo(f"{style.danger('error:')} Campaign {campaign_id!r} not found.", err=True)
+            raise FileNotFoundError(f"campaign not found: {campaign_id}")
+        row = dict(rows[0])
+        if row["status"] != "draft":
+            click.echo(
+                f"Cannot start campaign in '{row['status']}' status (must be 'draft').",
+                err=True,
+            )
+            raise click.UsageError(f"cannot start campaign in '{row['status']}' status")
+        now = datetime.now(UTC).isoformat()
+        with store.write() as conn:
+            conn.execute(
+                "UPDATE campaigns SET status = 'running', updated_at = ? WHERE id = ?",
+                (now, campaign_id),
+            )
+        if as_json:
+            rows2 = store.query("SELECT * FROM campaigns WHERE id = ?", (campaign_id,))
+            r = dict(rows2[0])
+            for key in ("experiments_json", "window_json", "policy_json", "labels_json"):
+                if r.get(key):
+                    r[key] = json.loads(r[key])
+            click.echo(json.dumps(r, indent=2))
+        else:
+            click.echo(style.ok(f"Campaign '{campaign_id}' started."))
+    finally:
+        store.close()
+
+
+@campaign.command("archive")
+@click.argument("campaign_id")
+@click.option("--db", "db_opt", default=None, help="SQLite database path.")
+@click.option("--json", "as_json", is_flag=True, help="Emit as JSON.")
+@click.pass_context
+def archive_campaign(ctx: Context, campaign_id: str, db_opt: str | None, as_json: bool) -> None:
+    """Archive a campaign (set status to 'completed')."""
+    from datetime import datetime
+
+    db = db_opt or _ctx(ctx).db
+    store = open_store(db)
+    try:
+        rows = store.query("SELECT id, name, status FROM campaigns WHERE id = ?", (campaign_id,))
+        if not rows:
+            click.echo(f"{style.danger('error:')} Campaign {campaign_id!r} not found.", err=True)
+            raise FileNotFoundError(f"campaign not found: {campaign_id}")
+        now = datetime.now(UTC).isoformat()
+        with store.write() as conn:
+            conn.execute(
+                "UPDATE campaigns SET status = 'completed', updated_at = ? WHERE id = ?",
+                (now, campaign_id),
+            )
+        if as_json:
+            rows2 = store.query("SELECT * FROM campaigns WHERE id = ?", (campaign_id,))
+            r = dict(rows2[0])
+            for key in ("experiments_json", "window_json", "policy_json", "labels_json"):
+                if r.get(key):
+                    r[key] = json.loads(r[key])
+            click.echo(json.dumps(r, indent=2))
+        else:
+            click.echo(style.ok(f"Campaign '{campaign_id}' archived."))
+    finally:
+        store.close()
+
+
+@campaign.command("abort")
+@click.argument("campaign_id")
+@click.option("--db", "db_opt", default=None, help="SQLite database path.")
+@click.pass_context
+def abort_campaign(ctx: Context, campaign_id: str, db_opt: str | None) -> None:
+    """Abort a draft campaign (set status to 'aborted')."""
+    from datetime import datetime
+
+    db = db_opt or _ctx(ctx).db
+    store = open_store(db)
+    try:
+        rows = store.query("SELECT id, name, status FROM campaigns WHERE id = ?", (campaign_id,))
+        if not rows:
+            click.echo(f"{style.danger('error:')} Campaign {campaign_id!r} not found.", err=True)
+            raise FileNotFoundError(f"campaign not found: {campaign_id}")
+        now = datetime.now(UTC).isoformat()
+        with store.write() as conn:
+            conn.execute(
+                "UPDATE campaigns SET status = 'aborted', updated_at = ? WHERE id = ?",
+                (now, campaign_id),
+            )
+        click.echo(style.ok(f"Campaign '{campaign_id}' aborted."))
+    finally:
+        store.close()
+
+
+@campaign.command("add-experiment")
+@click.argument("campaign_id")
+@click.argument("experiment_path", type=click.Path(exists=True))
+@click.option("--db", "db_opt", default=None, help="SQLite database path.")
+@click.option("--json", "as_json", is_flag=True, help="Emit as JSON.")
+@click.pass_context
+def add_experiment(
+    ctx: Context,
+    campaign_id: str,
+    experiment_path: str,
+    db_opt: str | None,
+    as_json: bool,
+) -> None:
+    """Add an experiment spec file to a campaign."""
+    from datetime import datetime
+
+    db = db_opt or _ctx(ctx).db
+    store = open_store(db)
+    try:
+        rows = store.query("SELECT * FROM campaigns WHERE id = ?", (campaign_id,))
+        if not rows:
+            click.echo(f"{style.danger('error:')} Campaign {campaign_id!r} not found.", err=True)
+            raise FileNotFoundError(f"campaign not found: {campaign_id}")
+        row = dict(rows[0])
+        experiments = json.loads(row.get("experiments_json") or "[]")
+        experiments.append(experiment_path)
+        now = datetime.now(UTC).isoformat()
+        with store.write() as conn:
+            conn.execute(
+                "UPDATE campaigns SET experiments_json = ?, updated_at = ? WHERE id = ?",
+                (json.dumps(experiments), now, campaign_id),
+            )
+        if as_json:
+            click.echo(
+                json.dumps({"campaign_id": campaign_id, "experiments": experiments}, indent=2)
+            )
+        else:
+            click.echo(style.ok(f"Added experiment to campaign '{campaign_id}'."))
+    finally:
+        store.close()
+
+
+def _resolve_engine_from_state() -> str:
+    from mayhem.cli.app import _STATE
+    from mayhem.cli.topology import _resolve_engine
+
+    return _resolve_engine(str(_STATE.get("engine", ""))) or "podman"
+
+
+@campaign.command("run")
+@click.argument("campaign_id")
+@click.option("--compose", "-c", type=str, default=None, help="Compose file path.")
+@click.option("--no-gate", is_flag=True, help="Skip the impact gate for this run.")
+@click.option("--db", "db_opt", default=None, help="SQLite database path.")
+@click.option("--json", "as_json", is_flag=True, help="Emit as JSON.")
+@click.pass_context
+def run_campaign(
+    ctx: Context,
+    campaign_id: str,
+    compose: str | None,
+    no_gate: bool,
+    db_opt: str | None,
+    as_json: bool,
+) -> None:
+    """Execute a campaign's experiments sequentially (ADR-0023).
+
+    Each experiment spec is compiled and executed against the compose
+    topology. The campaign's policy_json failure policy and window_json
+    deadline/cooldown are honored; per-experiment results are recorded in the
+    observations table.
+    """
+    from datetime import datetime
+
+    from mayhem.cli.lifecycle import _gate_bypasses, _gate_enabled, _graph_from
+
+    obj = _ctx(ctx)
+    db = db_opt or obj.db
+    store = open_store(db)
+    try:
+        rows = store.query("SELECT * FROM campaigns WHERE id = ?", (campaign_id,))
+        if not rows:
+            click.echo(f"{style.danger('error:')} Campaign {campaign_id!r} not found.", err=True)
+            raise FileNotFoundError(f"campaign not found: {campaign_id}")
+        row = dict(rows[0])
+        experiments = json.loads(row.get("experiments_json") or "[]")
+        if not experiments:
+            click.echo(
+                f"{style.danger('error:')} Campaign has no experiments; add one with"
+                " `mayhem campaign add-experiment`.",
+                err=True,
+            )
+            raise click.UsageError("campaign has no experiments", ctx=ctx)
+        if row["status"] not in ("draft", "scheduled", "running", "paused"):
+            click.echo(
+                "Cannot run campaign in "
+                f"'{row['status']}' status (must be draft/scheduled/running/paused).",
+                err=True,
+            )
+            raise click.UsageError(f"cannot run campaign in '{row['status']}' status")
+
+        graph, resolved_compose = _graph_from(ctx, compose)
+        engine_name = _resolve_engine_from_state()
+        gate = _gate_enabled() and not no_gate
+
+        now = datetime.now(UTC).isoformat()
+        with store.write() as conn:
+            conn.execute(
+                "UPDATE campaigns SET status = 'running', updated_at = ? WHERE id = ?",
+                (now, campaign_id),
+            )
+
+        def _run_one(spec_path: str) -> RunResult:
+            from mayhem.cli.lifecycle import _debug_progress
+
+            prepared = prepare(
+                config_path=obj.config,
+                profile=obj.profile,
+                allow_critical=obj.allow_critical,
+                store=store,
+                graph=graph,
+                compose=resolved_compose,
+                spec_path=spec_path,
+            )
+            compiled = plan_from_spec(spec_path, graph, prepared=prepared, engine=engine_name)
+            bypass: dict[tuple[str, str], str] = {}
+            if gate:
+                bypass = _gate_bypasses(engine_name, compiled.plan, graph)
+            eng = engine_for(
+                store,
+                engine_name,
+                live_graph=lambda: build_graph(resolved_compose),
+                on_event=_debug_progress() if obj.debug else None,
+                bypass=bypass,
+            )
+            return eng.execute(compiled.plan)
+
+        outcome = run_campaign_sequence(
+            campaign_id=campaign_id,
+            experiments=experiments,
+            policy=json.loads(row.get("policy_json") or "{}"),
+            window=json.loads(row.get("window_json") or "{}"),
+            store=store,
+            run_one=_run_one,
+        )
+
+        final_status = "completed" if outcome.status == "completed" else "aborted"
+        now = datetime.now(UTC).isoformat()
+        with store.write() as conn:
+            conn.execute(
+                "UPDATE campaigns SET status = ?, updated_at = ? WHERE id = ?",
+                (final_status, now, campaign_id),
+            )
+
+        if as_json:
+            click.echo(
+                json.dumps(
+                    {
+                        "campaign_id": campaign_id,
+                        "status": outcome.status,
+                        "runs": [
+                            {
+                                "spec_path": e.spec_path,
+                                "run_id": e.run_id,
+                                "status": e.status,
+                            }
+                            for e in outcome.runs
+                        ],
+                    },
+                    indent=2,
+                )
+            )
+        else:
+            for entry in outcome.runs:
+                mark = style.ok("ok") if entry.status == "completed" else style.danger("FAIL")
+                click.echo(f"  [{mark}] {entry.spec_path} -> {entry.run_id} ({entry.status})")
+            click.echo(
+                f"Campaign {style.cyan(campaign_id)} finished with status"
+                f" {style.state(outcome.status)}."
+            )
+
+        if outcome.status != "completed":
+            ctx.exit(int(ExitCode.EXPERIMENT_FAILURE))
+    finally:
+        store.close()

mayhem/cli/config_cmd.py

@@ -0,0 +1,47 @@
+"""``config`` group: show and validate layered configuration."""
+
+from __future__ import annotations
+
+import json
+
+import click
+
+from mayhem.cli import style
+from mayhem.cli.resolver import make_group
+from mayhem.cli.services import effective_config
+
+config = make_group("config", "Inspect the effective layered mayhem configuration.")
+
+
+@config.command("show")
+@click.option("--json", "as_json", is_flag=True, help="Emit resolved config as JSON.")
+@click.pass_context
+def show(ctx: click.Context, as_json: bool) -> None:
+    """Print the effective configuration after all layers are merged."""
+    from mayhem.cli.context import CliContext
+
+    obj = ctx.obj
+    assert isinstance(obj, CliContext)
+    cfg, sources = effective_config(obj.config, obj.profile)
+    if as_json:
+        payload = {"config": cfg.model_dump(mode="json", by_alias=True), "sources": sources}
+        click.echo(json.dumps(payload, indent=2))
+        return
+    import yaml
+
+    click.echo(yaml.safe_dump(cfg.model_dump(mode="json", by_alias=True), sort_keys=False))
+    click.echo("# sources:")
+    for layer, origin in sources.items():
+        click.echo(f"#   {layer}: {origin}")
+
+
+@config.command("validate")
+@click.pass_context
+def validate(ctx: click.Context) -> None:
+    """Load every configuration layer; refuse unknown keys or versions."""
+    from mayhem.cli.context import CliContext
+
+    obj = ctx.obj
+    assert isinstance(obj, CliContext)
+    _cfg, sources = effective_config(obj.config, obj.profile)
+    click.echo(style.ok(f"configuration valid ({len(sources)} layer(s))"))