mediar-ai/cmd-art

cmd-art

Render and design terminal visual effects with fx, a living-template engine: an Effect ABC + a @register decorator + pkgutil auto-discovery, so effects, themes, and multi-effect shows all compose. Pure Python stdlib (optional pyfiglet for fonts, PIL for real images). Truecolor + ANSI, tuned for Windows Terminal but works on any VT-capable terminal.

When to use

• User asks for a terminal/CMD animation or ANSI art: "spinning ball", "donut", "matrix rain", "plasma", "fire", "game of life", "3D title", "rainbow banner", "starfield", "tunnel", "fireworks".
• User wants a static ASCII title/banner with a color gradient, or an image turned into ASCII.
• User wants to invent a new console effect (drop one file in fx/effects/).

The 18 effects (registry names)

Run python -m fx list for the live catalog. Names + aliases as registered:

| name | kind | what | aliases | |------|------|------|---------| | sphere | anim | rotating Lambert-shaded 3D ball ("spinning ball") | | | donut | anim | THE spinning ASCII torus (Sloane donut.c) | | | cube | anim | rotating wireframe cube | | | tunnel | anim | demoscene tunnel fly-through | | | starfield | anim | perspective starfield warp | | | plasma | anim | full-screen sine interference field | wave | | fire | anim | demoscene fire (heat buffer + cooling) | | | rain | anim | matrix digital rain | | | life | anim | Conway's Game of Life, toroidal | game_of_life | | boids | anim | Reynolds flocking | | | fireworks | anim | rising shells → gravity sparks | | | sparkle | anim | dim text under bright glints | | | text3d | anim* | big figlet/block banner, gradient; shimmer animates | banner | | gradient_text | anim | lolcat rainbow / theme-gradient text | lolcat | | banner_scroll | anim | scrolling figlet marquee | marquee | | typewriter | anim | char-by-char reveal with a cursor | | | decrypt | anim | scramble-to-plaintext reveal | | | image2ascii | static | image → half-block truecolor / ASCII ramp | img |

*text3d is static unless --set shimmer=true. image2ascii is a StaticEffect (one frame to the normal screen). Everything else animates in the alt-screen.

How to run

From skills/cmd-art, run the package:

python -m fx <command> [args]

Or by path from any cwd (a PEP-366 prelude bootstraps the package):

python skills/cmd-art/fx/cli.py <command> [args]

Legacy compat shim (preserves the old surface, translates to fx play):

python skills/cmd-art/scripts/ascii_fx.py [--fps N] [--seconds N] [--once] [--width W] [--height H] <sphere|plasma|wave|rain|text3d> [args]

Prefer the fx CLI for new work; use the shim only for old commands/imports.

Commands

• list [--tag T] [--json] — every registered effect (kind, tags, description, aliases). --tag filters (e.g. 3d, text, particles, classic, field, matrix). --json emits full param schemas.
• show <name> — one effect's details: animated?, tags, aliases, preferred theme, and every --set param (kind, default, choices, range, help), plus a ready-to-run example. show also plays scripted shows via --seq/--script (see Compose a show).
• play <name> [flags] — play one effect. Bounded by default (10s on a TTY when no --seconds/--frames). Flags:
  • --theme NAME — palette (see Themes). Defaults to the effect's preferred_theme.
  • --seconds N — stop after N seconds.
  • --frames N — stop after N frames.
  • --once — render ONE frame to the normal screen and exit (best for text3d, image2ascii, previews).
  • --forever — explicitly unbounded (until Ctrl-C).
  • --fps N — frame rate (default: the effect's own default_fps).
  • --width W / --height H — 0 = terminal size (height leaves 1 row headroom).
  • --set K=V — override an effect param (repeatable). Unknown keys fail loudly.
• gallery [--seconds-per N] [--tag T] [--theme NAME] — tour every animated effect back-to-back in one alt-screen (default 3s each).
• random [play-flags] — play a random animated effect with a random theme (defaults to 8s).

Non-TTY safety: play/shows degrade to a single plain frame when stdout is not a terminal, and the play loop always restores the terminal (cursor, wrap, alt-screen) via try/finally. Prefer --seconds/--once in automated contexts so the process always terminates.

Themes

--theme names (from fx/theme.py, live via theme_names()): mono, fire, ocean, synthwave, viridis, pastel, matrix-green, rainbow. Default theme is synthwave. Effects never bake in hex; they sample the active Theme (color_at(t) gradient, cycle(phase) HSV/lolcat sweep, .primary/.accent/.base), so swapping the theme restyles every effect for free. Unknown --theme on play fails loud; on shows it falls back to default.

Example commands

• Spinning ball, 5s, ocean: python -m fx play sphere --seconds 5 --theme ocean
• THE donut, faster spin: python -m fx play donut --set speed=2 --seconds 8
• Matrix rain: python -m fx play rain --seconds 8
• Fire, taller flames: python -m fx play fire --set cool=2
• Game of Life, dense start: python -m fx play life --set fill=0.35 --seconds 10
• 3D title, one static frame: python -m fx play text3d --set text=KIRO --once
• Shimmering animated title: python -m fx play text3d --set text=KIRO --set shimmer=true --seconds 6
• Rainbow lolcat text: python -m fx play gradient_text --set text="hello" --theme rainbow
• Image → ASCII (half-block): python -m fx play image2ascii --set path=pic.png --once
• Tour everything: python -m fx gallery --seconds-per 3
• Surprise me: python -m fx random

Compose a show

Play a timed sequence of segments in ONE alt-screen (no flicker between segments) via show:

• Compact --seq grammar effect[:theme[:seconds]],..., with left|right split-screen in the effect slot:

  python -m fx show --seq "donut:fire:4,plasma::3,rain:matrix-green:5"
  python -m fx show --seq "donut|fire:synthwave:6"   # donut left, fire right
  

• JSON --script show.json (list of segment objects):

  [
    {"effect": "donut", "theme": "fire", "seconds": 4, "params": {"speed": 2}},
    {"split": ["donut", "fire"], "themes": ["ocean", "fire"], "seconds": 6}
  ]
  

--seconds-per sets the default per-segment duration; --theme is the fallback for segments without one. Each segment gets a local clock (t restarts at 0). Split is a combinator built from two real effects, not a registered effect.

Knowledge base — look before you build

Before inventing or tuning an effect, consult the SmartCLI knowledge graph at D:/Project/SmartCLI/knowledge/INDEX.md. Its effects/ domain carries exact-formula notes for most of what ships here — [[donut-torus]], [[plasma]], [[fire-lode]] / [[fire-doom-psx]], [[matrix-rain]], [[game-of-life]], [[boids]], [[starfield]], [[tunnel]], [[rotating-cube]], [[ascii-luminance-ramp]] — plus [[color-interpolation]] and [[hsv-cycling-lolcat]] for theme/lolcat color. The works/ wing ([[donut-c]], [[lolcat]], [[cmatrix]], [[terminaltexteffects]], ...) is the design brain for a NEW effect: pick your lane — replica a real effect by measuring its source math, or compose a new one from documented primitives. Read the relevant note before writing render code from scratch; references/effects.md is the local techniques sampler, the graph is the sourced depth.

Add a NEW effect

Drop one module in fx/effects/ — pkgutil auto-imports it, @register wires it into list/show/play/gallery. A module that fails to import is reported (stderr + registry.load_errors()) but never takes the catalog down.

Minimal contract (fx/base.py):

• Subclass Effect (or StaticEffect for one-shot art). Set class metadata: name (lowercase, unique registry key), description, tags, optional aliases, preferred_theme, default_fps, and a params tuple of Param(...).
• Param(name, kind, default, help, choices=None, min=None, max=None) — kind ∈ int float str bool color. The CLI lists/parses/validates --set against these; unknown keys and out-of-range values fail loud. color accepts #RRGGBB/RRGGBB (empty = None).
• Implement render(self, ctx: FrameCtx) -> str: return ONE full frame — ctx.height rows joined by \n, no trailing newline, EVERY cell written. Effects are pure frame producers: never print, sleep, or touch ANSI modes — the play loop owns the terminal.
• ctx: FrameCtx fields: t (seconds since start), frame_index, width, height, theme (active Theme, never None), params (coerced dict).
• Optional lifecycle: setup() (allocate buffers/particles before the first frame) and teardown() (release state; also runs on error/Ctrl-C). Override is_animated(cls, params) for effects that are static by default but animate on a flag (see text3d's shimmer, gradient_text).

Skeleton:

from fx.base import Effect, FrameCtx, Param
from fx.registry import register

@register
class Swirl(Effect):
    name = "swirl"
    description = "example: a themed diagonal sweep."
    tags = ("field", "demo")
    default_fps = 24.0
    params = (Param("speed", "float", 1.0, "sweep speed", min=0.0, max=10.0),)

    def render(self, ctx: FrameCtx) -> str:
        rows = []
        for y in range(ctx.height):
            cells = []
            for x in range(ctx.width):
                t = ((x + y) / max(1, ctx.width + ctx.height)
                     + ctx.t * ctx.params["speed"] * 0.1) % 1.0
                r, g, b = ctx.theme.color_at(t)
                cells.append(f"\x1b[38;2;{r};{g};{b}m#")
            rows.append("".join(cells) + "\x1b[0m")
        return "\n".join(rows)

Then python -m fx play swirl --theme rainbow --seconds 5. Duplicate names raise RegistryError (pass @register(replace=True) to intentionally override a built-in).

Constraints / gotchas

• Keep frames exactly ctx.height rows and ctx.width cells; auto-size leaves 1 row headroom so the top doesn't scroll off.
• plasma and full-field effects are the heaviest (O(width×height) escapes/frame); shrink dimensions or lower --fps if they stutter.
• pyfiglet powers text3d/banner_scroll/gradient_text --set big=true if importable; otherwise a built-in block font covers A-Z, 0-9, space. image2ascii uses PIL if present, else a PNM/built-in demo fallback.
• ANSI on Windows is enabled automatically at startup (enable_vt()), no action needed.
• references/effects.md is a techniques sampler — it works a few effects in depth (sphere/block-text projection, plasma field, fire kernel, rain fade), not one section per shipped effect. Read it, plus the per-effect formula notes in knowledge/effects/ (see Knowledge base above), when adding or tuning an effect.
• Paths above are relative to this skill's folder.

Optional tmux launchers

The play loop already owns a single alt-screen session, so tmux is never required. For convenience, tmux/ ships two POSIX-sh launchers that drop an effect into a tmux popup or split pane:

• tmux/fx-popup.sh <effect|gallery|random> [fx args] — display-popup -E (tmux >= 3.2).
• tmux/fx-split.sh [-v] EFFECT [EFFECT2] [fx args] — split the current window (one effect in a new pane, or a 2-up of two).

Both guard on command -v tmux: with no tmux they print the direct/compositor alternative plus install hints and exit 0. play/random runs get a default --seconds 10 bound. Truecolor through tmux needs set -g default-terminal "tmux-256color" + set -ga terminal-overrides ",*:Tc". See tmux/README.md. For a seamless side-by-side without tmux, use the compositor: python -m fx show --seq "donut|fire:synthwave:6".