rich-gradient-cli 0.1.0__tar.gz

rich_gradient_cli-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.3
+Name: rich-gradient-cli
+Version: 0.1.0
+Summary: CLI for printing text in gradient color using the rich-gradient library.
+Author: Maxwell Ludden
+Author-email: Maxwell Ludden <maxludden@me.com>
+Requires-Dist: typer>=0.21.1
+Requires-Dist: rich>=14.3.2
+Requires-Dist: rich-color-ext>=0.1.9
+Requires-Dist: rich-gradient>=0.3.9
+Requires-Dist: ruff>=0.15.0
+Requires-Dist: mkdocs>=1.6.0 ; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5.0 ; extra == 'docs'
+Requires-Dist: mkdocstrings>=0.25.0 ; extra == 'docs'
+Requires-Dist: mkdocstrings-python>=1.10.0 ; extra == 'docs'
+Requires-Python: >=3.14
+Provides-Extra: docs
+Description-Content-Type: text/markdown
+
+# rich-gradient-cli
+
+ `rich-gradient-cli`  is a CLI for [`rich-gradient`](https://github.com/maxludden/rich-gradient). The tool allows you to create colorful gradients in your terminal output, making it easier to visualize data or simply add some flair to your command-line applications.
+
+## Installation
+
+You can install rich-gradient-cli from PyPI
+
+### uv (recommended)
+
+```shell
+uv add rich-gradient-cli
+```
+
+### pip
+
+```shell
+pip install rich-gradient-cli
+```
+
+## Usage
+
+
+### Print
+
+To use the `rich-gradient-cli`, you can run the following command in your terminal:
+
+```bash
+gradient print --colors 'red,#ff9900,#ffff00' "This is gradient text that starts red, transitions through orange, and ends in yellow\!"
+```
+
+![Gradient Text Example](print-example.svg)
+
+
+### Rule
+
+You can also create gradient rules using the `rule` command:
+
+```bash
+gradient rule --colors 'blue,#00ff00,cyan' "Blue to Green to Cyan Rule"
+```
+
+![Gradient Rule Example](rule-example.svg)
+
+### Panel
+
+To create a gradient panel, you can use the `panel` command:
+
+```bash
+gradient panel --colors "red,#ff9999" -t "Error" --title-style "bold #ffffff" --title-align left 'This is an error message with a red to pink gradient background.'
+```
+
+![Gradient Panel Example](panel-example.svg)
+
+### Markdown
+
+You can also render Markdown with gradients:
+
+```bash
+echo "# Hello\n\n- This is **bold**.\n- This is *italic*." | gradient markdown -
+```
+
+![Gradient Markdown Example](markdown-example.svg)
+
+## Docs
+
+Build and preview the documentation locally with MkDocs:
+
+```bash
+uv pip install -e ".[docs]"
+mkdocs serve
+```
+
+
+
+<div align="center">
+  <a href="https://github.com/maxludden/maxludden" style="text-decoration:none; color:inherit;">
+      <p>Designed by Max Ludden</p>
+  </a>
+  <br />
+  <a href="https://github.com/maxludden/maxludden" style="text-decoration:none; color:inherit;">
+    <img
+      src="https://github.com/maxludden/maxludden/blob/f3913ecf11f90c97435e2b55d2e43dadd51c1fe4/Images/MaxLogo-animated.svg"
+      alt="Max Ludden's Logo"
+      width="20%"
+    />
+  </a>
+</div>

rich_gradient_cli-0.1.0/README.md

@@ -0,0 +1,88 @@
+# rich-gradient-cli
+
+ `rich-gradient-cli`  is a CLI for [`rich-gradient`](https://github.com/maxludden/rich-gradient). The tool allows you to create colorful gradients in your terminal output, making it easier to visualize data or simply add some flair to your command-line applications.
+
+## Installation
+
+You can install rich-gradient-cli from PyPI
+
+### uv (recommended)
+
+```shell
+uv add rich-gradient-cli
+```
+
+### pip
+
+```shell
+pip install rich-gradient-cli
+```
+
+## Usage
+
+
+### Print
+
+To use the `rich-gradient-cli`, you can run the following command in your terminal:
+
+```bash
+gradient print --colors 'red,#ff9900,#ffff00' "This is gradient text that starts red, transitions through orange, and ends in yellow\!"
+```
+
+![Gradient Text Example](print-example.svg)
+
+
+### Rule
+
+You can also create gradient rules using the `rule` command:
+
+```bash
+gradient rule --colors 'blue,#00ff00,cyan' "Blue to Green to Cyan Rule"
+```
+
+![Gradient Rule Example](rule-example.svg)
+
+### Panel
+
+To create a gradient panel, you can use the `panel` command:
+
+```bash
+gradient panel --colors "red,#ff9999" -t "Error" --title-style "bold #ffffff" --title-align left 'This is an error message with a red to pink gradient background.'
+```
+
+![Gradient Panel Example](panel-example.svg)
+
+### Markdown
+
+You can also render Markdown with gradients:
+
+```bash
+echo "# Hello\n\n- This is **bold**.\n- This is *italic*." | gradient markdown -
+```
+
+![Gradient Markdown Example](markdown-example.svg)
+
+## Docs
+
+Build and preview the documentation locally with MkDocs:
+
+```bash
+uv pip install -e ".[docs]"
+mkdocs serve
+```
+
+
+
+<div align="center">
+  <a href="https://github.com/maxludden/maxludden" style="text-decoration:none; color:inherit;">
+      <p>Designed by Max Ludden</p>
+  </a>
+  <br />
+  <a href="https://github.com/maxludden/maxludden" style="text-decoration:none; color:inherit;">
+    <img
+      src="https://github.com/maxludden/maxludden/blob/f3913ecf11f90c97435e2b55d2e43dadd51c1fe4/Images/MaxLogo-animated.svg"
+      alt="Max Ludden's Logo"
+      width="20%"
+    />
+  </a>
+</div>

rich_gradient_cli-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "rich-gradient-cli"
+version = "0.1.0"
+description = "CLI for printing text in gradient color using the rich-gradient library."
+readme = "README.md"
+authors = [
+    { name = "Maxwell Ludden", email = "maxludden@me.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "typer>=0.21.1",
+    "rich>=14.3.2",
+    "rich-color-ext>=0.1.9",
+    "rich-gradient>=0.3.9",
+    "ruff>=0.15.0",
+]
+
+[project.optional-dependencies]
+docs = [
+    "mkdocs>=1.6.0",
+    "mkdocs-material>=9.5.0",
+    "mkdocstrings>=0.25.0",
+    "mkdocstrings-python>=1.10.0",
+]
+
+[project.scripts]
+gradient = "rich_gradient_cli:app"
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"

rich_gradient_cli-0.1.0/src/rich_gradient_cli/__init__.py

@@ -0,0 +1,96 @@
+"""rich-gradient CLI entry point."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Sequence
+
+import click
+import typer
+
+from .common import VERSION
+from .help import RichTyperCommand, RichTyperGroup
+from .markdown_command import markdown_command
+from .panel_command import panel_command
+from .rule_command import rule_command
+from .text_command import print_command
+
+
+class DefaultTyperGroup(RichTyperGroup):
+    """Route unknown commands/options to the default command."""
+
+    def __init__(
+        self,
+        name: str | None = None,
+        commands: dict[str, click.Command] | Sequence[click.Command] | None = None,
+        invoke_without_command: bool = False,
+        no_args_is_help: bool | None = None,
+        subcommand_metavar: str | None = None,
+        chain: bool = False,
+        result_callback: Any | None = None,
+        *,
+        default_cmd_name: str = "print",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            name=name,
+            commands=commands,
+            invoke_without_command=invoke_without_command,
+            no_args_is_help=no_args_is_help,
+            subcommand_metavar=subcommand_metavar,
+            chain=chain,
+            result_callback=result_callback,
+            **kwargs,
+        )
+        self.default_cmd_name = default_cmd_name
+
+    def resolve_command(
+        self, ctx: click.Context, args: list[str]
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        if args:
+            cmd = self.get_command(ctx, args[0])
+            if cmd is None or args[0].startswith("-"):
+                args.insert(0, self.default_cmd_name)
+        return super().resolve_command(ctx, args)
+
+
+app = typer.Typer(
+    cls=DefaultTyperGroup,
+    invoke_without_command=True,
+    add_completion=False,
+    help="Create gradient-rich text, panels, and markdown.",
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"], "color": True},
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Show the version and exit.",
+        is_eager=True,
+    ),
+) -> None:
+    """CLI entry callback for version handling and default routing."""
+    if version:
+        typer.echo(f"gradient version {VERSION}")
+        raise typer.Exit()
+    if ctx.invoked_subcommand is None:
+        if ctx.args or not sys.stdin.isatty():
+            print_command(text=list(ctx.args) if ctx.args else None)
+            raise typer.Exit()
+        typer.echo(ctx.get_help())
+
+
+app.command("print", cls=RichTyperCommand)(print_command)
+app.command("panel", cls=RichTyperCommand)(panel_command)
+app.command("rule", cls=RichTyperCommand)(rule_command)
+app.command("markdown", cls=RichTyperCommand)(markdown_command)
+
+
+cli = app
+
+__all__ = ["app", "cli"]

rich_gradient_cli-0.1.0/src/rich_gradient_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Executable entry point for python -m rich_gradient_cli."""
+
+from . import app
+
+if __name__ == "__main__":
+    app()

rich_gradient_cli-0.1.0/src/rich_gradient_cli/common.py

@@ -0,0 +1,87 @@
+"""Shared helpers and configuration for the rich-gradient CLI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+from rich.console import Console, RenderableType
+from rich.padding import Padding
+from rich.style import Style
+from rich_gradient.theme import GRADIENT_TERMINAL_THEME
+
+console = Console()
+VERSION = "0.3.10"
+
+HEADER_TEXT = (
+    "[#ff5500]r[/][#ff6f00]i[/][#ff8300]c[/]"
+    "[#ff9500]h[/][#ffa600]-[/][#ffb600]g[/][#ffc500]r[/]"
+    "[#ffd400]a[/][#ffe500]d[/][#fff400]i[/][#f9ff00]e[/]"
+    "[#e2ff00]n[/][#c8ff00]t[/][#a9ff00] [/][bold #fff]CLI[/]"
+)
+
+FOOTER_TEXT = (
+    "[#ff5500]\U0001f308[/][#ff7400] [/][#ff8c00]h[/]"
+    "[#ffa100]t[/][#ffb500]t[/][#ffc700]p[/][#ffdc00]s[/]"
+    "[#ffef00]:[/][#fbff00]/[/][#dfff00]/[/][#bdff00]m[/]"
+    "[#9aff00]a[/][#73ff00]x[/][#2aff00]l[/][#00ff5c]u[/]"
+    "[#00ff83]d[/][#00ffa6]d[/][#00ffd1]e[/][#00fff3]n[/]"
+    "[#00f4ff].[/][#00e1ff]g[/][#00ccff]i[/][#00baff]t[/]"
+    "[#00a6ff]h[/][#2192ff]u[/][#3b81ff]b[/][#4c6cff].[/]"
+    "[#6061ff]i[/][#725bff]o[/][#8253ff]/[/][#9648ff]r[/]"
+    "[#a83bff]i[/][#c22eff]c[/][#e122ff]h[/][#fb0cff]-[/]"
+    "[#ff00e6]g[/][#ff00c6]r[/][#ff00a4]a[/][#ff0089]d[/]"
+    "[#ff0066]i[/][#ff004b]e[/][#ff0036]n[/][#ff0000]t[/]"
+)
+
+
+USAGE_PREFIX = "[bold #00ff00]Usage:[/]"
+USAGE_PROG_STYLE = "#af00ff"
+USAGE_CMD_STYLE = "#0099ff"
+USAGE_BRACKET_STYLE = "#ffffff"
+
+
+def parse_colors(colors: Optional[str]) -> Optional[List[str]]:
+    """Parse comma-separated color tokens into a list."""
+    if colors is None:
+        return None
+    return [c.strip() for c in colors.split(",") if c.strip()]
+
+
+def parse_style(style: Optional[str]) -> Style:
+    """Parse a Rich style string or return a null style."""
+    if style is None:
+        return Style.null()
+    return Style.parse(style)
+
+
+def export_svg(
+    renderable: RenderableType, svg_path: str, *, end: str = "\n", no_wrap: bool = False
+) -> None:
+    """Render a Rich renderable to an SVG file."""
+    svg_console = Console(record=True, force_terminal=True, color_system="truecolor")
+    padded = Padding(renderable, (1, 4))
+    svg_console.print(padded, end=end, no_wrap=no_wrap)
+
+    Path(svg_path).write_text(
+        svg_console.export_svg(
+            title="rich-gradient",
+            theme=GRADIENT_TERMINAL_THEME,
+        ),
+        encoding="utf-8",
+    )
+
+
+__all__ = [
+    "VERSION",
+    "console",
+    "parse_colors",
+    "parse_style",
+    "HEADER_TEXT",
+    "FOOTER_TEXT",
+    "USAGE_PREFIX",
+    "USAGE_PROG_STYLE",
+    "USAGE_CMD_STYLE",
+    "USAGE_BRACKET_STYLE",
+    "export_svg",
+]

rich_gradient_cli-0.1.0/src/rich_gradient_cli/help.py

@@ -0,0 +1,231 @@
+"""Custom Rich help rendering for Typer commands."""
+
+from __future__ import annotations
+
+import io
+import re
+from dataclasses import dataclass
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+import click
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from typer.core import TyperCommand, TyperGroup
+
+from .common import (
+    FOOTER_TEXT,
+    HEADER_TEXT,
+    USAGE_BRACKET_STYLE,
+    USAGE_CMD_STYLE,
+    USAGE_PREFIX,
+    USAGE_PROG_STYLE,
+)
+
+
+@dataclass(frozen=True)
+class HelpStyles:
+    border: str = "#2a4fff"
+    option_name: str = "cyan"
+    metavar: str = "bold #99ff00"
+    help_text: str = "white"
+    dim: str = "dim"
+
+
+_STYLES = HelpStyles()
+
+
+def _usage_markup(command_path: str, pieces: Sequence[str]) -> str:
+    parts = command_path.split()
+    prog = parts[0] if parts else ""
+    subcommands = parts[1:]
+
+    def color_token(token: str) -> str:
+        if token.startswith("[") and token.endswith("]"):
+            inner = token[1:-1]
+            return (
+                f"[{USAGE_BRACKET_STYLE}][[/][{USAGE_CMD_STYLE}]"
+                f"{inner}[/][{USAGE_BRACKET_STYLE}]][/]"
+            )
+        if token.startswith("[") and token.endswith("]..."):
+            inner = token[1:-4]
+            return (
+                f"[{USAGE_BRACKET_STYLE}][[/][{USAGE_CMD_STYLE}]"
+                f"{inner}[/][{USAGE_BRACKET_STYLE}]][/]"
+                f"[{USAGE_CMD_STYLE}]...[/]"
+            )
+        if token.isupper() or re.match(r"^[A-Z_]+(\.\.\.)?$", token):
+            return f"[{USAGE_CMD_STYLE}]{token}[/]"
+        return token
+
+    colored_prog = f"[{USAGE_PROG_STYLE}]{prog}[/]" if prog else ""
+    colored_subcommands = " ".join(
+        f"[{USAGE_CMD_STYLE}]{cmd}[/]" for cmd in subcommands
+    )
+    args = " ".join(color_token(piece) for piece in pieces)
+    if args:
+        args = f"  {args}"
+    usage = " ".join(p for p in [colored_prog, colored_subcommands] if p)
+    return f"{USAGE_PREFIX} {usage}{args}".strip()
+
+
+def _split_option_name(name: str) -> Tuple[str, str]:
+    parts = name.split()
+    if not parts:
+        return name, ""
+    last = parts[-1]
+    if not last.startswith("-") and last.isupper():
+        return " ".join(parts[:-1]), last
+    return name, ""
+
+
+def _normalize_metavar(metavar: str) -> str:
+    value = metavar.strip()
+    if value.startswith("[") and value.endswith("]..."):
+        value = value[1:-4]
+    elif value.startswith("[") and value.endswith("]"):
+        value = value[1:-1]
+    if value.endswith("..."):
+        value = value[:-3]
+    return value
+
+
+def _build_arguments_table(
+    args: Iterable[click.Argument], ctx: click.Context
+) -> Optional[Table]:
+    rows: List[Tuple[str, str]] = []
+    for arg in args:
+        metavar = _normalize_metavar(arg.make_metavar(ctx))
+        rows.append((metavar, metavar))
+
+    if not rows:
+        return None
+
+    table = Table.grid(padding=(0, 2))
+    table.add_column(justify="left", style="bold #ffff00", no_wrap=True)
+    table.add_column(justify="left", style=_STYLES.metavar)
+    for name, meta in rows:
+        table.add_row(name, meta)
+    return table
+
+
+def _build_options_table(
+    options: Iterable[click.Option], ctx: click.Context
+) -> Optional[Table]:
+    rows: List[Tuple[str, str, Text]] = []
+    for opt in options:
+        record = opt.get_help_record(ctx)
+        if record is None:
+            continue
+        name, help_text = record
+        opt_names, metavar = _split_option_name(name)
+        help_rich = Text.from_markup(help_text, style=_STYLES.help_text)
+        rows.append((opt_names, metavar, help_rich))
+
+    if not rows:
+        return None
+
+    table = Table.grid(padding=(0, 2))
+    table.add_column(justify="left", style="bold #ffff00", no_wrap=True)
+    table.add_column(justify="left", style=_STYLES.metavar, no_wrap=True)
+    table.add_column(justify="left", style=_STYLES.help_text)
+    for opt_names, metavar, help_rich in rows:
+        table.add_row(opt_names, metavar, help_rich)
+    return table
+
+
+def _build_commands_table(group: click.Group) -> Optional[Table]:
+    if not group.commands:
+        return None
+
+    table = Table.grid(padding=(0, 2))
+    table.add_column(justify="left", style="bold #ffff00", no_wrap=True)
+    table.add_column(justify="left", style=_STYLES.help_text)
+    for name, cmd in group.commands.items():
+        help_text = cmd.get_short_help_str() if cmd.help else ""
+        table.add_row(name, help_text)
+    return table
+
+
+def render_help(command: click.Command, ctx: click.Context) -> str:
+    """Render help text for a Click command using Rich for formatting."""
+    console = Console(
+        record=True,
+        force_terminal=True,
+        color_system="truecolor",
+        file=io.StringIO(),
+    )
+
+    console.print(Text.from_markup(HEADER_TEXT))
+    console.print()
+
+    usage_line = _usage_markup(ctx.command_path, command.collect_usage_pieces(ctx))
+    console.print(Text.from_markup(usage_line))
+
+    if command.help:
+        console.print()
+        console.print(Text.from_markup(command.help))
+
+    args = [p for p in command.params if isinstance(p, click.Argument)]
+    options = [p for p in command.params if isinstance(p, click.Option)]
+
+    args_table = _build_arguments_table(args, ctx)
+    if args_table is not None:
+        console.print()
+        console.print(
+            Panel(
+                args_table,
+                title="[b #ffffff]Arguments[/]",
+                title_align="left",
+                border_style=_STYLES.border,
+                box=box.SQUARE,
+            )
+        )
+
+    options_table = _build_options_table(options, ctx)
+    if options_table is not None:
+        console.print()
+        console.print(
+            Panel(
+                options_table,
+                title="[b #ffffff]Options[/]",
+                title_align="left",
+                border_style=_STYLES.border,
+                box=box.SQUARE,
+            )
+        )
+
+    if isinstance(command, click.Group):
+        commands_table = _build_commands_table(command)
+        if commands_table is not None:
+            console.print()
+            console.print(
+                Panel(
+                    commands_table,
+                    title="[b #ffffff]Commands[/]",
+                    title_align="left",
+                    border_style=_STYLES.border,
+                    box=box.SQUARE,
+                )
+            )
+
+    console.print()
+    console.print(Text.from_markup(FOOTER_TEXT))
+
+    return console.export_text(styles=True)
+
+
+class RichTyperCommand(TyperCommand):
+    """Custom TyperCommand that uses Rich for help rendering."""
+
+    def get_help(self, ctx: click.Context) -> str:  # type: ignore[override]
+        return render_help(self, ctx).rstrip("\n")
+
+
+class RichTyperGroup(TyperGroup):
+    """Custom TyperGroup that uses Rich for help rendering."""
+
+    def get_help(self, ctx: click.Context) -> str:  # type: ignore[override]
+        return render_help(self, ctx).rstrip("\n")

rich_gradient_cli-0.1.0/src/rich_gradient_cli/markdown_command.py

@@ -0,0 +1,168 @@
+"""Markdown command wiring for the CLI."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional, cast
+
+import typer
+from rich.align import AlignMethod, VerticalAlignMethod
+
+from rich_gradient.animated_markdown import AnimatedMarkdown
+from rich_gradient.markdown import Markdown
+
+from .common import console, export_svg, parse_colors, parse_style
+
+
+def markdown_command(
+    markdown: str = typer.Argument(..., metavar="MARKDOWN"),
+    colors: Optional[str] = typer.Option(
+        None,
+        "-c",
+        "--colors",
+        metavar="COLORS",
+        help=(
+            "Comma-separated list of colors for the gradient. [dim](e.g., "
+            "`[/][red]red[/][dim], [/][#ff9900]#ff9900[/][dim], [/][yellow]yellow[/][dim]`). "
+            "If no colors are provided, the color stops are automatically generated."
+        ),
+    ),
+    bgcolors: Optional[str] = typer.Option(
+        None,
+        "--bgcolors",
+        metavar="BGCOLORS",
+        help=(
+            "Comma-separated list of background colors for the gradient. [dim](e.g., "
+            "`[/][red]red[/][dim], [/][#ff9900]#ff9900[/][dim], [/][#ff0]#ff0[/][dim]`). "
+            "Defaults to [/][bold #fff]transparent[/][dim].[/dim]"
+        ),
+    ),
+    rainbow: bool = typer.Option(
+        False,
+        "-r",
+        "--rainbow",
+        help="[#ff0000]U[/][#ff3b00]s[/][#ff5100]e[/][#ff7400] [/]\
+[#ff9000]r[/][#ffa900]a[/][#ffc000]i[/][#ffd700]n[/]\
+[#ffee00]b[/][#f7ff00]o[/][#d3ff00]w[/][#a7ff00] [/] \
+[#7dff00]c[/][#2eff00]o[/][#00ff64]l[/][#00ff8e]o[/][#00ffc0]r[/]\
+[#00ffec]s[/][#00f4ff] [/][#00ddff]f[/][#00c5ff]o[/][#00afff]r[/]\
+[#1596ff] [/][#3b81ff]t[/][#4e67ff]h[/][#675fff]e[/][#7b57ff] [/]\
+[#924bff]g[/][#a73bff]r[/][#c72cff]a[/][#eb1cff]d[/][#ff00f2]i[/]\
+[#ff00ce]e[/][#ff00a4]n[/][#ff0084]t[/][#ff0054].[/]",
+    ),
+    hues: int = typer.Option(
+        7,
+        "--hues",
+        metavar="HUES",
+        help="The number of hues to use for a random gradient.",
+        show_default=True,
+    ),
+    style: Optional[str] = typer.Option(
+        None,
+        "--style",
+        metavar="STYLE",
+        help=(
+            "The style to apply to the markdown text. [dim italic]*Only non-color styles "
+            "will be applied as the gradient's colors override color styles.[/]"
+        ),
+    ),
+    justify: Literal["left", "center", "right"] = typer.Option(
+        "left",
+        "-j",
+        "--justify",
+        metavar="JUSTIFY",
+        help="Justification of the markdown text. [lime](left, center, right)[/]",
+        show_default=True,
+        case_sensitive=False,
+    ),
+    vertical_justify: Literal["top", "middle", "bottom"] = typer.Option(
+        "top",
+        "--vertical-justify",
+        metavar="VERTICAL_JUSTIFY",
+        help="Vertical justification of the markdown text. [lime](top, middle, bottom)[/]",
+        show_default=True,
+        case_sensitive=False,
+    ),
+    no_wrap: bool = typer.Option(
+        False,
+        "--no-wrap",
+        help="Disable wrapping of markdown text.",
+        show_default=True,
+    ),
+    end: str = typer.Option(
+        "\n",
+        "--end",
+        metavar="END",
+        help=(
+            "String appended after the text is printed. [dim]\\[default: '\\n'][/dim]"
+        ),
+    ),
+    animate: bool = typer.Option(
+        False,
+        "--animate",
+        help="Animate the gradient markdown text.",
+    ),
+    duration: float = typer.Option(
+        5.0,
+        "-d",
+        "--duration",
+        metavar="DURATION",
+        help="Duration of the animation in seconds (only used if --animate).",
+    ),
+    svg: Optional[str] = typer.Option(
+        None,
+        "--svg",
+        metavar="SVG",
+        help="Save output as an SVG file.",
+    ),
+) -> None:
+    """Render markdown text with gradient colors in a rich console."""
+    if markdown == "-":
+        markdown = typer.get_text_stream("stdin").read().rstrip("\n")
+        if not markdown:
+            raise typer.UsageError("Missing markdown argument.")
+
+    _colors = parse_colors(colors)
+    _bgcolors = parse_colors(bgcolors)
+    markdown_kwargs: dict[str, Any] = {}
+    if style:
+        markdown_kwargs["style"] = parse_style(style)
+
+    justify_value = cast(AlignMethod, justify)
+    vertical_value = cast(VerticalAlignMethod, vertical_justify)
+
+    if animate and svg:
+        raise typer.UsageError("--svg is not supported with --animate.")
+    if animate and console.is_terminal is True:
+        console.clear()
+        animated = AnimatedMarkdown(
+            markdown,
+            colors=_colors,
+            rainbow=rainbow,
+            hues=hues,
+            justify=justify_value,
+            vertical_justify=vertical_value,
+            bg_colors=_bgcolors,
+            markdown_kwargs=markdown_kwargs or None,
+            animate=True,
+            duration=duration,
+        )
+        animated.run()
+        return
+
+    md = Markdown(
+        markdown,
+        colors=_colors,
+        rainbow=rainbow,
+        hues=hues,
+        justify=justify_value,
+        vertical_justify=vertical_value,
+        bg_colors=_bgcolors,
+        markdown_kwargs=markdown_kwargs or None,
+    )
+    if svg:
+        export_svg(md, svg, end=end, no_wrap=no_wrap)
+        return
+    console.print(md, end=end, no_wrap=no_wrap)
+
+
+__all__ = ["markdown_command"]

rich_gradient_cli-0.1.0/src/rich_gradient_cli/panel_command.py

@@ -0,0 +1,290 @@
+"""Panel command wiring for the CLI."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Literal, Optional, Tuple, cast
+
+import typer
+from rich.align import Align, AlignMethod, VerticalAlignMethod
+
+from rich_gradient.animated_panel import AnimatedPanel
+from rich_gradient.panel import Panel
+
+from .common import console, export_svg, parse_colors, parse_style
+
+
+def panel_command(
+    renderable: str = typer.Argument(..., metavar="TEXT"),
+    colors: Optional[str] = typer.Option(
+        None,
+        "-c",
+        "--colors",
+        metavar="COLORS",
+        help=(
+            "Comma-separated list of colors for the gradient. [dim](e.g., "
+            "`[/][red]red[/][dim], [/][#ff9900]#ff9900[/][dim], [/][yellow]yellow[/][dim]`). "
+            "If no colors are provided, the color stops are automatically generated."
+        ),
+    ),
+    bgcolors: Optional[str] = typer.Option(
+        None,
+        "--bgcolors",
+        metavar="BGCOLORS",
+        help=(
+            "Comma-separated list of background colors for the gradient. [dim](e.g., "
+            "`[/][red]red[/][dim],[/][#ff9900]#ff9900[/][dim],[/][#ff0]#ff0[/][dim]`). "
+            "Defaults to [/][bold #fff]transparent[/][dim].[/dim]"
+        ),
+    ),
+    rainbow: bool = typer.Option(
+        False,
+        "-r",
+        "--rainbow",
+        help="[#ff0000]U[/][#ff3b00]s[/][#ff5100]e[/][#ff7400] [/]\
+[#ff9000]r[/][#ffa900]a[/][#ffc000]i[/][#ffd700]n[/]\
+[#ffee00]b[/][#f7ff00]o[/][#d3ff00]w[/][#a7ff00] [/] \
+[#7dff00]c[/][#2eff00]o[/][#00ff64]l[/][#00ff8e]o[/][#00ffc0]r[/]\
+[#00ffec]s[/][#00f4ff] [/][#00ddff]f[/][#00c5ff]o[/][#00afff]r[/]\
+[#1596ff] [/][#3b81ff]t[/][#4e67ff]h[/][#675fff]e[/][#7b57ff] [/]\
+[#924bff]g[/][#a73bff]r[/][#c72cff]a[/][#eb1cff]d[/][#ff00f2]i[/]\
+[#ff00ce]e[/][#ff00a4]n[/][#ff0084]t[/][#ff0054].[/]",
+    ),
+    hues: int = typer.Option(
+        5,
+        "--hues",
+        metavar="HUES",
+        help="The number of hues to use for a random gradient.",
+        show_default=True,
+    ),
+    title: Optional[str] = typer.Option(
+        None,
+        "-t",
+        "-title",
+        "--title",
+        metavar="TITLE",
+        help="Title of the panel.",
+    ),
+    title_style: str = typer.Option(
+        "bold",
+        "--title-style",
+        metavar="TITLE_STYLE",
+        help="Style of the panel title text (requires -t/--title).",
+    ),
+    title_align: Literal["left", "center", "right"] = typer.Option(
+        "center",
+        "--title-align",
+        metavar="TITLE_ALIGN",
+        help="Alignment of the panel title. [lime](left, center, right)[/]",
+        show_default=True,
+        case_sensitive=False,
+    ),
+    subtitle: Optional[str] = typer.Option(
+        None,
+        "-s",
+        "--subtitle",
+        metavar="SUBTITLE",
+        help="Subtitle of the panel.",
+    ),
+    subtitle_style: Optional[str] = typer.Option(
+        None,
+        "--subtitle-style",
+        metavar="SUBTITLE_STYLE",
+        help="Style of the panel subtitle text (requires --subtitle).",
+    ),
+    subtitle_align: Literal["left", "center", "right"] = typer.Option(
+        "right",
+        "--subtitle-align",
+        metavar="SUBTITLE_ALIGN",
+        help="Alignment of the panel subtitle. [lime](left, center, right)[/]",
+        show_default=True,
+        case_sensitive=False,
+    ),
+    style: Optional[str] = typer.Option(
+        None,
+        "--style",
+        metavar="STYLE",
+        help="The style to apply to the panel.",
+    ),
+    border_style: Optional[str] = typer.Option(
+        None,
+        "--border-style",
+        metavar="BORDER_STYLE",
+        help=(
+            "The style to apply to the panel border. [dim italic]*Only non-color styles "
+            "will be applied as the gradient's colors override color styles.[/]"
+        ),
+    ),
+    padding: Optional[str] = typer.Option(
+        "0,1",
+        "-p",
+        "--padding",
+        metavar="PADDING",
+        help="Padding inside the panel (1, 2, or 4 comma-separated integers).",
+    ),
+    vertical_justify: Literal["top", "middle", "bottom"] = typer.Option(
+        "top",
+        "-V",
+        "--vertical-justify",
+        metavar="VERTICAL_JUSTIFY",
+        help="Vertical justification of the panel inner text. [lime](top, middle, bottom)[/]",
+        show_default=True,
+        case_sensitive=False,
+    ),
+    text_justify: Literal["left", "center", "right"] = typer.Option(
+        "left",
+        "-J",
+        "--text-justify",
+        metavar="TEXT_JUSTIFY",
+        help="Justification of the text inside the panel. [lime](left, center, right)[/]",
+        show_default=True,
+        case_sensitive=False,
+    ),
+    justify: Literal["left", "center", "right"] = typer.Option(
+        "left",
+        "-j",
+        "--justify",
+        metavar="JUSTIFY",
+        help="Justification of the panel itself. [lime](left, center, right)[/]",
+        show_default=True,
+        case_sensitive=False,
+    ),
+    expand: bool = typer.Option(
+        True,
+        "--expand/--no-expand",
+        help="Whether to expand the panel to fill the width.",
+    ),
+    width: Optional[int] = typer.Option(
+        None,
+        "--width",
+        metavar="WIDTH",
+        help="Width of the panel (requires --no-expand if set).",
+    ),
+    height: Optional[int] = typer.Option(
+        None,
+        "--height",
+        metavar="HEIGHT",
+        help="Height of the panel; content determines by default.",
+    ),
+    end: str = typer.Option(
+        "\n",
+        "--end",
+        metavar="END",
+        help=(
+            "String appended after the text is printed. [dim]\\[default: '\\n'][/dim]"
+        ),
+    ),
+    box: Literal["SQUARE", "ROUNDED", "HEAVY", "DOUBLE", "ASCII"] = typer.Option(
+        "ROUNDED",
+        "--box",
+        metavar="BOX",
+        help=(
+            "Box style for the panel border. [dim](e.g., SQUARE, ROUNDED, HEAVY, "
+            "DOUBLE, ASCII).[/dim]"
+        ),
+        case_sensitive=False,
+    ),
+    animate: bool = typer.Option(
+        False,
+        "-a",
+        "--animate",
+        help="Animate the panel gradient.",
+    ),
+    duration: float = typer.Option(
+        5.0,
+        "-d",
+        "--duration",
+        metavar="DURATION",
+        help="Duration of the panel animation in seconds (only used if --animate).",
+    ),
+    svg: Optional[str] = typer.Option(
+        None,
+        "--svg",
+        metavar="SVG",
+        help="Save output as an SVG file.",
+    ),
+) -> None:
+    """Display a renderable inside a gradient panel."""
+    if renderable == "-":
+        renderable = typer.get_text_stream("stdin").read().rstrip("\n")
+        if not renderable:
+            raise typer.UsageError("Missing text argument.")
+
+    fg_list = parse_colors(colors)
+    bg_list = parse_colors(bgcolors)
+    style_obj = parse_style(style)
+    _text_justify = cast(AlignMethod, text_justify)
+    padding_tuple: Optional[Tuple[int, ...]] = None
+    if padding:
+        padding_tuple = tuple(int(x) for x in padding.split(",") if x.strip())
+
+    from rich import box as rich_box
+
+    box_map: dict[str, Any] = {
+        "SQUARE": rich_box.SQUARE,
+        "ROUNDED": rich_box.ROUNDED,
+        "HEAVY": rich_box.HEAVY,
+        "DOUBLE": rich_box.DOUBLE,
+        "ASCII": rich_box.ASCII,
+    }
+    box_style = box_map.get(box.upper(), rich_box.ROUNDED)
+
+    if animate and svg:
+        raise typer.UsageError("--svg is not supported with --animate.")
+    if animate and console.is_terminal is True:
+        animated_panel: AnimatedPanel = AnimatedPanel(
+            Align(renderable, align=_text_justify),
+            colors=cast(Any, fg_list),
+            rainbow=rainbow,
+            hues=hues,
+            bg_colors=cast(Any, bg_list),
+            title=title,
+            title_style=parse_style(title_style),
+            title_align=cast(AlignMethod, title_align),
+            subtitle=subtitle,
+            subtitle_style=parse_style(subtitle_style),
+            subtitle_align=cast(AlignMethod, subtitle_align),
+            style=style_obj,
+            border_style=parse_style(border_style),
+            padding=cast(Any, padding_tuple),
+            vertical_justify=cast(Any, vertical_justify),
+            justify=cast(AlignMethod, justify),
+            expand=expand,
+            width=width,
+            height=height,
+            box=box_style,
+            animate=True,
+            duration=duration,
+        )
+        animated_panel.run()
+        sys.exit(0)
+
+    panel = Panel(
+        Align(renderable, align=_text_justify),
+        colors=cast(Any, fg_list),
+        rainbow=rainbow,
+        hues=hues,
+        bg_colors=cast(Any, bg_list),
+        title=title,
+        title_style=parse_style(title_style),
+        title_align=cast(AlignMethod, title_align),
+        subtitle=subtitle,
+        subtitle_style=parse_style(subtitle_style),
+        subtitle_align=cast(AlignMethod, subtitle_align),
+        style=style_obj,
+        border_style=parse_style(border_style),
+        padding=cast(Any, padding_tuple),
+        vertical_justify=cast(Any, vertical_justify),
+        justify=cast(AlignMethod, justify),
+        expand=expand,
+        width=width,
+        height=height,
+        box=box_style,
+    )
+    if svg:
+        export_svg(panel, svg, end=end)
+        return
+    console.print(panel, end=end)
+
+
+__all__ = ["panel_command"]

rich_gradient_cli-0.1.0/src/rich_gradient_cli/rule_command.py

@@ -0,0 +1,128 @@
+"""Rule command wiring for the CLI."""
+
+from __future__ import annotations
+
+from typing import Literal, Optional, cast
+
+import typer
+from rich.align import AlignMethod
+
+from rich_gradient.rule import Rule
+
+from .common import console, export_svg, parse_colors, parse_style
+
+
+def rule_command(
+    title: Optional[str] = typer.Option(
+        None,
+        "-t",
+        "--title",
+        metavar="TITLE",
+        help="Title of the rule.",
+    ),
+    title_style: Optional[str] = typer.Option(
+        "bold",
+        "-s",
+        "--title-style",
+        metavar="TITLE_STYLE",
+        help=(
+            "The style of the rule's title text. [dim italic]*Only non-color styles "
+            "will be applied as the gradient's colors override color styles.[/]"
+        ),
+        show_default=True,
+    ),
+    colors: Optional[str] = typer.Option(
+        "",
+        "-c",
+        "--colors",
+        metavar="COLORS",
+        help=(
+            "Comma-separated list of colors for the gradient. [dim](e.g., "
+            "`[/][red]red[/][dim], [/][#ff9900]#ff9900[/][dim], [/][yellow]yellow[/][dim]`)."
+        ),
+        show_default=True,
+    ),
+    bgcolors: Optional[str] = typer.Option(
+        "",
+        "--bgcolors",
+        metavar="BGCOLORS",
+        help=(
+            "Comma-separated list of background colors for the gradient. [dim](e.g., "
+            "`[/][red]red[/][dim], [/][#ff9900]#ff9900[/][dim], [/][#ff0]#ff0[/][dim]`). "
+            "Defaults to [/][bold #fff]transparent[/][dim].[/dim]"
+        ),
+    ),
+    rainbow: bool = typer.Option(
+        False,
+        "-r",
+        "--rainbow",
+        help="[#ff0000]U[/][#ff3b00]s[/][#ff5100]e[/][#ff7400] [/]\
+[#ff9000]r[/][#ffa900]a[/][#ffc000]i[/][#ffd700]n[/]\
+[#ffee00]b[/][#f7ff00]o[/][#d3ff00]w[/][#a7ff00] [/] \
+[#7dff00]c[/][#2eff00]o[/][#00ff64]l[/][#00ff8e]o[/][#00ffc0]r[/]\
+[#00ffec]s[/][#00f4ff] [/][#00ddff]f[/][#00c5ff]o[/][#00afff]r[/]\
+[#1596ff] [/][#3b81ff]t[/][#4e67ff]h[/][#675fff]e[/][#7b57ff] [/]\
+[#924bff]g[/][#a73bff]r[/][#c72cff]a[/][#eb1cff]d[/][#ff00f2]i[/]\
+[#ff00ce]e[/][#ff00a4]n[/][#ff0084]t[/][#ff0054].[/]",
+    ),
+    hues: int = typer.Option(
+        10,
+        "--hues",
+        metavar="HUES",
+        help="The number of hues to use for a random gradient.",
+        show_default=True,
+    ),
+    end: str = typer.Option(
+        "\n",
+        "--end",
+        metavar="END",
+        help=(
+            "String appended after the text is printed. [dim]\\[default: '\\n'][/dim]"
+        ),
+    ),
+    thickness: int = typer.Option(
+        2,
+        "-T",
+        "--thickness",
+        metavar="THICKNESS",
+        help="Thickness of the rule line (choices 0-3).",
+    ),
+    align: Literal["left", "center", "right"] = typer.Option(
+        "center",
+        "-a",
+        "--align",
+        metavar="ALIGN",
+        help="Alignment of the rule in the console. [lime](left, center, right)[/]",
+        show_default=True,
+        case_sensitive=False,
+    ),
+    svg: Optional[str] = typer.Option(
+        None,
+        "--svg",
+        metavar="SVG",
+        help="Save output as an SVG file.",
+    ),
+) -> None:
+    """Display a gradient rule in the console."""
+    _colors = parse_colors(colors)
+    _bgcolors = parse_colors(bgcolors)
+    _title_style = parse_style(title_style)
+
+    rule = Rule(
+        title=title or "",
+        title_style=_title_style,
+        colors=_colors,
+        rainbow=rainbow,
+        hues=hues,
+        bg_colors=_bgcolors,
+        thickness=thickness,
+        end=end,
+        align=cast(AlignMethod, align),
+    )
+    if svg:
+        export_svg(rule, svg, end=end)
+        return
+    console.print(rule)
+
+
+__all__ = ["rule_command"]

rich_gradient_cli-0.1.0/src/rich_gradient_cli/text_command.py

@@ -0,0 +1,139 @@
+"""Text/print command wiring for the CLI."""
+
+from __future__ import annotations
+
+import sys
+from typing import List, Literal, Optional, cast
+
+import typer
+from rich.console import JustifyMethod, OverflowMethod
+
+from rich_gradient.text import Text
+
+from .common import console, export_svg, parse_colors, parse_style
+
+
+def print_command(
+    text: Optional[List[str]] = typer.Argument(None),
+    colors: Optional[str] = typer.Option(
+        None,
+        "-c",
+        "--colors",
+        metavar="COLORS",
+        help=(
+            "Comma-separated list of colors for the gradient. [dim](e.g., "
+            "`[/][red]red[/][dim], [/][#ff9900]#ff9900[/][dim], [/][yellow]yellow[/][dim]`). "
+            "If no colors are provided, the color stops are automatically generated."
+        ),
+    ),
+    rainbow: bool = typer.Option(
+        False,
+        "-r",
+        "--rainbow",
+        help="[#ff0000]U[/][#ff3b00]s[/][#ff5100]e[/][#ff7400] [/]\
+[#ff9000]r[/][#ffa900]a[/][#ffc000]i[/][#ffd700]n[/]\
+[#ffee00]b[/][#f7ff00]o[/][#d3ff00]w[/][#a7ff00] [/] \
+[#7dff00]c[/][#2eff00]o[/][#00ff64]l[/][#00ff8e]o[/][#00ffc0]r[/]\
+[#00ffec]s[/][#00f4ff] [/][#00ddff]f[/][#00c5ff]o[/][#00afff]r[/]\
+[#1596ff] [/][#3b81ff]t[/][#4e67ff]h[/][#675fff]e[/][#7b57ff] [/]\
+[#924bff]g[/][#a73bff]r[/][#c72cff]a[/][#eb1cff]d[/][#ff00f2]i[/]\
+[#ff00ce]e[/][#ff00a4]n[/][#ff0084]t[/][#ff0054].[/]",
+    ),
+    hues: int = typer.Option(
+        7,
+        "-h",
+        "--hues",
+        metavar="HUES",
+        help="The number of hues to use for a random gradient.",
+        show_default=True,
+    ),
+    style: Optional[str] = typer.Option(
+        None,
+        "--style",
+        metavar="STYLE",
+        help=(
+            "The style to apply to the text. [dim italic]*Only non-color styles "
+            "will be applied as the gradient's colors override color styles.[/]"
+        ),
+    ),
+    justify: Literal["left", "center", "right"] = typer.Option(
+        "left",
+        "-j",
+        "--justify",
+        metavar="JUSTIFY",
+        help="Justification of the text. [lime](left, center, right)[/]",
+        show_default=True,
+        case_sensitive=False,
+    ),
+    overflow: Literal["crop", "fold", "ellipsis"] = typer.Option(
+        "fold",
+        "--overflow",
+        metavar="OVERFLOW",
+        help="How to handle overflow of text. [lime](crop, fold, ellipsis)[/]",
+        show_default=True,
+        case_sensitive=False,
+    ),
+    no_wrap: bool = typer.Option(
+        False,
+        "--no-wrap",
+        help="Disable wrapping of text.",
+        show_default=True,
+    ),
+    end: str = typer.Option(
+        "\n",
+        "--end",
+        metavar="END",
+        help=(
+            "String appended after the text is printed. [dim]\\[default: '\\n'][/dim]"
+        ),
+    ),
+    bgcolors: Optional[str] = typer.Option(
+        None,
+        "--bgcolors",
+        metavar="BGCOLORS",
+        help="Optional comma separated string of background colors. [dim]If not provided, background is transparent.[/]",
+    ),
+    svg: Optional[str] = typer.Option(
+        None,
+        "--svg",
+        metavar="SVG",
+        help="Save output as an SVG file.",
+    ),
+) -> None:
+    """Print text in gradient color to the console."""
+    if text:
+        if len(text) == 1 and text[0] == "-":
+            content = typer.get_text_stream("stdin").read().rstrip("\n")
+            if not content:
+                raise typer.BadParameter("Missing text argument.")
+        else:
+            content = " ".join(text)
+    else:
+        if sys.stdin.isatty():
+            raise typer.BadParameter("Missing text argument.")
+        content = typer.get_text_stream("stdin").read().rstrip("\n")
+        if not content:
+            raise typer.BadParameter("Missing text argument.")
+
+    fg_list = parse_colors(colors)
+    bg_list = parse_colors(bgcolors)
+    style_obj = parse_style(style)
+    gradient = Text(
+        content,
+        colors=fg_list,
+        rainbow=rainbow,
+        hues=hues,
+        style=style_obj,
+        justify=cast(JustifyMethod, justify),
+        overflow=cast(OverflowMethod, overflow),
+        end=end,
+        no_wrap=no_wrap,
+        bg_colors=bg_list,
+    )
+    if svg:
+        export_svg(gradient, svg, end="")
+        return
+    console.print(gradient)
+
+
+__all__ = ["print_command"]