Effects

Effects are installable intro animations: they change the way the info appears when xfetch starts. The core renders the module lines, hands them to an effect binary (xfetch-effect-<name>), and plays the returned frames before settling on the final content. Example: the decrypt effect reveals each line from scrambled glyphs.

Effects are opt-in — without the binary installed, xfetch renders normally.

Install

From the effects repository (default: xfetch-cli/effects):

xfetch effects install decrypt

Or from a local path:

xfetch effects install ./effects/decrypt

Manage installed effects:

xfetch effects list
xfetch effects list --verbose
xfetch effects info decrypt
xfetch effects search <query>
xfetch effects available
xfetch effects remove decrypt

search reads the effects catalog (index.json), filters by name, description or runtime, and prints the matching install command. available lists the whole catalog, --json emits JSON, and XFETCH_EFFECT_INDEX overrides the catalog URL.

After a successful install, xfetch prints the "effects" config entry, the declared capabilities and the manifest limits. list --verbose adds the manifest kind, runtime, version and whether the effect is enabled; info prints the details for one effect. Direct wasm files and URLs accept --name and --manifest; directory and repository installs use their own name and manifest.

Binaries are stored in ~/.config/xfetch/effects/. Use --repo <url> (or the XFETCH_EFFECT_REPO env var) to install from a fork or mirror.

WebAssembly Effects

Effects can be compiled to WebAssembly and installed exactly like native ones. The core detects the binary header and runs the guest in the sandbox, enforcing the manifest limits through wasmtime epochs. Examples include a Rust core module (wasm-matrix) and a Python component (wasm-python-pulse).

xfetch effects install ./effects/wasm-matrix
xfetch effects install ./effects/wasm-python-pulse

Effects produce frames on stdout like any other plugin, so the same manifest and host-call rules apply. See WASM.md.

Pin an effect with --sha256 <64-hex-digest> from a channel independent of the artifact; the digest is enforced on downloaded, checked-in, built and direct-file wasm installs. A manifest sha256 field is checked too, but it is integrity-only because it shares the artifact's origin. A mismatch aborts the install; an unpinned download prints an unverified integrity warning.

Native effects run as ordinary processes, unsandboxed, with your user privileges; only wasm effects use the wasmtime sandbox.

Configuration

{
    "effects": [
        { "plugin": "glitch", "duration_ms": 700, "fps": 30 },
        { "plugin": "decrypt", "duration_ms": 1500, "fps": 30 }
    ]
}

The effects value accepts a single object or a list; a list plays the effects in sequence. Each effect receives the same rendered lines and settles on them, so chaining glitch → decrypt flows seamlessly into the final fetch.

Field	Type	Default	Description
`plugin`	string	—	Effect name (binary `xfetch-effect-<name>`).
`style`	string	none	Effect-specific style selector, passed to the effect.
`duration_ms`	number	effect default	Total animation length in milliseconds.
`fps`	number	effect default	Frames per second.
`args`	object	none	Free-form parameters passed to the effect.
`timeout_secs`	number	30	Safety net: kills the effect process if it runs longer. Unset uses the 30 s default; `0` disables the cap.

Writing an effect

Effects speak the xfetch-effect-api protocol (see xfetch-cli/api): read an EffectRequest from stdin (the rendered lines plus style/duration_ms/fps/args) and write an EffectResponse with a non-empty list of { delay_ms, lines } frames. The last frame should reach the final content.

Effect implementations live in xfetch-cli/effects (one crate per effect, binary xfetch-effect-<name>).