🖥️ CLI Reference

Usage

fimod s -i <INPUT> -m <MOLD> [OPTIONS]
fimod s -i <INPUT> -e '<EXPRESSION>' [OPTIONS]
fimod s --no-input -m <MOLD> [OPTIONS]

🎯 Core options

📄 Format control

Supported values: json · json-compact · ndjson · yaml · toml · csv · txt · lines · raw (output-only) · http (input-only)

🔍 Auto-detection

🔥 Your input can be an HTTPS request!

Awesome: the input can be an HTTPS request. The -i flag accepts URLs exactly like file paths — fimod fetches, parses, and transforms in a single command. No curl, no wget, no pipes.

# Fetch JSON from an API
fimod s -i https://api.github.com/repos/pytgaen/fimod -e 'data["name"]' --output-format txt

# Multiple URLs in batch mode
fimod s -i https://jsonplaceholder.typicode.com/users/1 https://jsonplaceholder.typicode.com/users/2 -e 'data' -o responses/

Format auto-detection: the response's Content-Type header is used as fallback when --input-format is not set (application/json → JSON, text/csv → CSV, etc.). You can always override explicitly.

HTTP options

# Authenticated API
fimod s -i https://api.github.com/user \
    --http-header "Authorization: Bearer $GITHUB_TOKEN" \
    -e 'data["login"]' --output-format txt

# Disable redirects to inspect the Location header
fimod s -i https://github.com/pytgaen/fimod/releases/latest \
    --input-format http --no-follow \
    -e 'data["headers"]["location"]' --output-format txt

--input-format http — raw HTTP response

When you need the full HTTP response (status code, headers, body), use --input-format http. Instead of parsing the body, fimod gives you a dict:

data = {
    "status": 200,
    "headers": {"content-type": "application/json", "location": "..."},
    "body": "...",          # raw response body as a string
    "body_size": 1234,      # response size in bytes
    "content_type": "application/json",
    "url": "https://example.com/api/data"
}

# Get the redirect target of a URL
fimod s -i https://github.com/pytgaen/fimod/releases/latest \
    --input-format http --no-follow \
    -e 'data["headers"]["location"].split("/")[-1]' --output-format txt
# → v0.3.0

# Combine with set_input_format() to re-parse the body
fimod s -i https://api.github.com/repos/pytgaen/fimod/releases/latest \
    --input-format http \
    -e 'set_input_format("json"); data["body"]' \
    -e 'data["tag_name"]' --output-format txt

📥 Slurp mode (--slurp / -s)

-s has two distinct uses depending on whether you pass a single input or multiple -i entries.

Single input — NDJSON / concatenated JSON

Reads multiple concatenated JSON values from a single source and collects them into an array.

# 🔗 Two separate JSON objects → array of two
printf '{"a":1}\n{"b":2}' | fimod s --slurp -e 'len(data)'
# → 2

# 📂 Combine multiple JSON files via cat (JSON only)
cat file1.json file2.json | fimod s --slurp -e '[item for item in data if item.get("active")]'

For non-JSON formats, --slurp wraps the single parsed value in a one-element array.

Multiple inputs — multi-file slurp

When combined with two or more -i flags, -s switches to multi-file slurp mode: all files are parsed (each in their own format) and combined into a single data structure. The mold runs once against the combined result.

Two sub-modes controlled by the -i syntax:

Rules: - All entries must use : or none must (mixing → error) - Auto stem uses the filename without extension; duplicate stems → error (use explicit aliases) - Incompatible with --in-place and -o <directory> - URLs cannot carry a :alias suffix (the :// scheme separator collides with the alias delimiter, so URLs are always treated as bare entries). When mixing HTTP inputs with local files, list mode is the only option — access via data[0], data[1], … in input order.

# ➕ List mode — access by index, cross-format (JSON + YAML)
fimod s -i base.json -i override.yaml -s -e 'data[1]["env"]'

# 🏷️ Named mode — auto stem as key
fimod s -i defaults.json: -i prod.toml: -s \
  -e 'data["defaults"]["timeout"]'

# 🏷️ Named mode — explicit aliases (resolves stem collisions)
fimod s -i config/base.json:base -i other/base.json:fallback -s \
  -e 'data["fallback"]["host"]'

# 🔍 Diff two files (with df_ helpers, once implemented)
fimod s -i before.json:old -i after.json:new -s \
  -e 'df_diff(data["old"], data["new"])'

# 💾 Write result to a file
fimod s -i a.yaml -i b.yaml -s -e 'data[0]' -o merged.yaml

🚫 No-input mode (--no-input)

Skip input entirely — data is None in Python. Use to generate data from scratch.

fimod s --no-input -e '{"status": "ok", "ts": args["ts"]}' --arg ts="2024-01-01"

fimod s --no-input -m generate.py --arg count=5

# generate.py
def transform(data, args, env, headers):
    n = int(args["count"])
    return [{"id": i, "value": i * i} for i in range(n)]

✅ Check mode (--check)

Suppresses stdout and uses the truthiness of the result as the exit code.

• Exit 0 — result is truthy
• Exit 1 — result is falsy

See Exit Codes for the full truthiness table.

# ✅ Validate a record
fimod s -i record.json -e 'data.get("email") and data.get("name")' --check

# 🔀 Use in a shell conditional
if fimod s -i config.json -m validate.py --check; then
    echo "✅ Config is valid"
else
    echo "❌ Config has errors" >&2
    exit 1
fi

⚙️ Setup

fimod setup <category> defaults installs the canonical configuration for a category. It's what the install scripts call after downloading the binary, but you can re-run it at any time.

fimod setup all defaults --yes          # 🚀 registry + sandbox in one go
fimod setup registry defaults --yes     # community registries only
fimod setup sandbox defaults --yes      # sandbox policy only

What each target does:

• registry — installs the community registries in ~/.config/fimod/sources.toml. Idempotent; safe to re-run. Same effect as the legacy fimod registry setup.
• sandbox — writes the recommended sandbox policy to ~/.config/fimod/sandbox.toml. Refuses to overwrite without --force.
• all — runs registry then sandbox, stopping at the first error.

See Sandbox policy for what the sandbox file controls and how it is resolved.

🗂️ Mold registries

Registries are named collections of molds (local directories or remote repos). Use @name or @registry/name with -m to reference a mold by name.

fimod registry add my ~/molds/                          # ➕ Add local registry
fimod registry add corp https://github.com/org/molds    # ➕ Add GitHub registry
fimod registry list                                      # 📋 List registries
fimod registry show my                                   # 🔍 Show details
fimod registry remove my                                 # 🗑️ Remove
fimod registry set-priority corp 0                       # ⭐ Set P0 (highest priority)
fimod registry set-priority mycompany 1                  # 📌 Set priority P1
fimod registry set-priority mycompany --clear            # 📌 Clear priority
fimod registry build-catalog ./molds                     # 📦 Generate catalog.toml from a directory
fimod registry build-catalog --registry my               # 📦 Generate catalog.toml for a registered registry
fimod registry cache info                                # 📊 Show cache location and usage
fimod registry cache clear                               # 🧹 Clear all cached catalogs and molds

Config stored in ~/.config/fimod/sources.toml. Cache stored in ~/.cache/fimod/.

registry setup — first-run onboarding

fimod registry setup adds the fimod example molds registry (P99) if not already present. It remains operational for backward compatibility but delegates to the new setup path internally.

fimod registry setup           # interactive — asks before adding
fimod registry setup --yes     # non-interactive / CI — skips the prompt

Behaviour:

• Already configured (same URL found) → no-op, prints "already configured".
• Legacy "official" registry detected → prompts to migrate it to "examples" (P99).
• Fresh install → adds "examples" at P99 (not default — your own registries take precedence).
• Non-interactive (no TTY) → skips silently unless --yes is passed.

Priority-based resolution

When you use @mold (without a registry prefix), fimod searches all configured registries in priority order until the mold is found:

$ fimod registry list
  corp        [github]  github.com/org/fimod-powered       P0
  mycompany   [http]    registry.corp.com/fimod             P1
  internal    [local]   /home/user/molds                    P2
  examples    [github]  github.com/pytgaen/fimod            P99

With @registry/mold (explicit prefix), only that specific registry is searched.

set-priority — assign a priority rank

fimod registry set-priority mycompany 1    # Set mycompany to P1
fimod registry set-priority internal 2     # Set internal to P2
fimod registry set-priority mycompany --clear  # Remove priority

When the requested rank is already taken, the behaviour depends on context:

• Swap (default) — if both registries already have a rank, they exchange positions:

  # Before: mycompany=P1, internal=P2
  $ fimod registry set-priority internal 1
  # After:  internal=P1, mycompany=P2
  

• Cascade — if the source had no prior rank (or --cascade is passed), existing entries shift down:

  # Before: mycompany=P1, internal=P2
  $ fimod registry set-priority newreg 1
  # After:  newreg=P1, mycompany=P2, internal=P3
  

Use --cascade to force cascade behaviour even when both registries already have a rank.

sources.toml format

[priority]
corp = 0
mycompany = 1
internal = 2
examples = 99

[sources.corp]
type = "github"
url = "https://github.com/org/fimod-powered"

[sources.mycompany]
type = "http"
url = "https://registry.corp.com/fimod"

[sources.internal]
type = "local"
path = "/home/user/molds"

[sources.examples]
type = "github"
url = "https://github.com/pytgaen/fimod/tree/main/molds"

The [priority] section is optional. Without it, registries are searched in file order.

FIMOD_REGISTRY — ephemeral registries for CI

In CI/CD or ephemeral environments, use the FIMOD_REGISTRY environment variable instead of fimod registry add. Comma-separated entries, optionally named:

# Anonymous — resolves @mold
FIMOD_REGISTRY=./molds fimod s -i data.json -m @clean

# Named — resolves @ci/mold and @mold
FIMOD_REGISTRY="ci=./molds,staging=https://github.com/org/molds" fimod s -i data.json -m @ci/clean

# Mixed anonymous + named
FIMOD_REGISTRY="ci=./molds,/opt/shared-molds" fimod s -i data.json -m @clean

FIMOD_REGISTRY takes priority over sources.toml (env overrides config, standard Unix convention). Named entries support @name/mold resolution.

# Register a local collection once…
fimod registry add my ~/molds/

# …then reference molds by name
fimod s -i messy.csv -m @cleanup          # searches all registries in priority order
fimod s -i messy.csv -m @my/cleanup       # explicit registry

Authentication — tokens are resolved automatically, or overridden per-registry:

GitHub URL formats

fimod accepts different URL forms depending on the Git ref type you want to pin to:

For branches and semver tags, pass the standard github.com/tree/… URL — fimod converts it to a raw URL automatically, using refs/heads/ for branches and refs/tags/ for semver-looking refs.

For non-semver tags (e.g. stable, latest), fimod cannot distinguish them from branch names based on the ref string alone. Pass the raw.githubusercontent.com URL with the full ref path instead:

# Branch — standard github.com URL
fimod registry add mylib https://github.com/org/repo/tree/main/molds

# Semver tag — standard github.com URL
fimod registry add mylib https://github.com/org/repo/tree/v1.2.0/molds

# Non-semver tag — raw URL required
fimod registry add mylib https://raw.githubusercontent.com/org/repo/refs/tags/stable/molds

Browsing available molds

fimod mold list              # list molds in all registries
fimod mold list examples     # list molds in a specific registry
fimod mold show pick_fields  # show metadata for a mold

Both mold list and mold show accept --output-format json for machine-readable output.

For local registries, mold names and descriptions are discovered by scanning .py files. For remote registries (GitHub, GitLab, HTTP), a catalog.toml must be present at the root of the registry.

Maintainers generate it with:

fimod registry build-catalog ./molds         # scans directory and writes catalog.toml
fimod registry build-catalog --registry my   # same, resolving path from a registered registry

The catalog.toml is a simple TOML file committed alongside the molds:

[molds.normalize]
description = "Normalise field names to snake_case"

[molds.filter_active]
description = "Keep only active records"

Mold descriptions come from the module-level docstring at the top of each script:

"""Normalise field names to snake_case."""
def transform(data, args, env, headers):
    ...

Cache management

Remote catalogs and molds are cached locally in ~/.cache/fimod/ to avoid re-fetching on every invocation.

Catalog caching uses HTTP ETags: on subsequent requests, fimod sends If-None-Match and skips the download on 304 Not Modified.

Mold caching uses content hashes from the catalog: build-catalog computes a hash per mold directory, and the client only re-downloads when the hash changes.

fimod registry cache info              # show cache location and disk usage
fimod registry cache clear             # wipe all cached data
fimod registry cache clear @name       # wipe a specific mold (planned)
fimod s -i data.json -m @mold --no-cache  # bypass cache for this invocation

Override the cache directory with FIMOD_CACHE_DIR. For direct-URL molds (not registry-based), cache TTL is controlled by FIMOD_CACHE_TTL (minutes, default 360, 0 = infinite, negative = disabled).

🛡️ Sandbox policy

Every fimod s invocation runs the mold under a sandbox that limits what it can do on the host. A policy controls three things:

• Clock access — whether datetime.now() / date.today() resolve to real values or raise.
• Environment access — which os.getenv(KEY) calls are allowed (glob-matched).
• Hard resource limits — wall-clock duration and peak memory.

Resolution

The policy is resolved in this order (first match wins):

1. --sandbox-file <path> — CLI flag.
2. $FIMOD_SANDBOX_FILE — environment variable.
3. ~/.config/fimod/sandbox.toml — per-user canonical config.
4. (none of the above) — zero-authorization defaults.

Special cases:

• --sandbox-file="" (empty string) forces zero-authorization regardless of $FIMOD_SANDBOX_FILE or the canonical file. Portable across Linux/macOS/Windows.
• If $FIMOD_SANDBOX_FILE points to a missing path, fimod errors out explicitly rather than falling back silently.

Bootstrap the canonical file with fimod setup sandbox defaults --yes.

Hard limits

Apply even with zero authorization:

On violation, fimod exits with code 137 and a stderr message like:

sandbox exploded: max_duration exceeded (2m)
sandbox exploded: max_memory exceeded (1024 MB)

sandbox.toml schema

[sandbox]
allow_clock  = true              # allow datetime.now() / date.today()
max_duration = "2m"              # "30s", "2m", "unlimited"
max_memory   = "1GB"             # "500MB", "1GB", "unlimited"
allow_env    = ["LANG", "TZ_*"]  # glob patterns: "*", "PREFIX_*", "EXACT"

allow_env = [] (default) blocks every os.getenv() call. Patterns match the key name exactly, as a prefix (TZ_*), or anything (*).

Denied calls raise PermissionError inside the mold — catch it if you want a graceful fallback:

import os
lang = None
try:
    lang = os.getenv("LANG")
except PermissionError:
    pass  # sandbox forbids env access

📊 CSV options

# 🔀 CSV → TSV
fimod s -i data.csv -e 'data' --output-format csv --csv-output-delimiter '\t'

When the input CSV has a header row, a headers global is automatically available in your script — see Mold Scripting — CSV headers.

⚡ Inline expressions vs scripts

fimod s -i users.json -e '[u for u in data if u["active"]]'
fimod s -i data.json -e '{"name": data["first"].upper()}'
fimod s -i data.json -e 're_findall(r"\d+", data["text"])'

# cleanup.py
def transform(data, args, env, headers):
    for row in data:
        row["name"] = row["name"].strip().title()
    return data

fimod s -i messy.csv -m cleanup.py -o clean.json

fimod s -i data.json -m https://example.com/transforms/normalize.py

🎛️ Special output formats

Sometimes you need to control the output format for chaining with other tools, without changing the file extension:

# 📦 Compact JSON: one-line JSON for piping
fimod s -i data.json -e 'data' --output-format json-compact
# {"name":"Alice","age":30}

# 🐚 TXT: evaluate string without JSON quotes (ideal for shell variables)
NAME=$(fimod s -i data.json -e 'data["name"]' --output-format txt)
echo "Hello $NAME"   # Hello Alice

# 📑 Lines: one array element per line (shell-friendly lists)
fimod s -i users.json -e '[u["email"] for u in data]' --output-format lines

# 📥 Raw: download binary streams or raw bytes (no parsing, bypass pipeline)
fimod shape -i https://example.com/file.bin --output-format raw -o file.bin

📎 Passing variables (--arg)

fimod s -i users.json --arg threshold=30 -e '
  [u for u in data if u["age"] > int(args["threshold"])]
'

# Or via mold:
fimod s -i data.json -m filter.py --arg threshold=30 --arg prefix="A"

Access via args["key"] in the transform(data, args, env, headers) function.

🔀 Format conversion

Pass-through expression for pure format conversion:

fimod s -i config.yaml -e 'data' -o config.toml
fimod s -i data.csv -e 'data' --output-format json
fimod s -i users.json -e 'data' --output-format lines

🐛 Debug mode (--debug / -d)

Prints pipeline diagnostics to stderr (stdout stays clean for piping):

fimod s -i data.json -m transform.py --debug

Output includes: input/output format, per-step identification (step N/M (label)), full script, input data, output data, phase timings (parse, execute, serialize, total).

Each step in a chain is logged with its 1-based index, the chain length, and a short label (the raw -m reference, or -e '<expr>' for inline expressions, truncated to ~50 chars). Steps injected at runtime via pipeline.insert_next / pipeline.append are annotated with injected by step P:

[debug] step 1/3 (./normalize.py)
[debug] step 2/3 (@common/flatten)
[debug] step 3/3 (-e 'data', injected by step 2)

The same identifier is prepended to runtime errors, so the failing step is always unambiguous:

Error: in step 2/3 (@common/flatten): Python error in mold:
KeyError: 'foo'

Timings are always emitted in seconds with millisecond precision (0.045s) for easy parsing:

[debug] parse: 0.002s
[debug] execute: 0.045s
[debug] serialize: 0.001s
[debug] total: 0.048s

# extract execute time of a run
fimod s -i big.json -m heavy.py --debug 2>&1 1>/dev/null \
  | awk '/\[debug\] execute:/ {print $3}'

📢 Message verbosity (--quiet / --msg-level)

Control which msg_* functions in mold scripts produce output:

fimod s -i data.json -m transform.py --quiet              # errors only
fimod s -i data.json -m transform.py --msg-level=verbose  # + msg_verbose()
fimod s -i data.json -m transform.py --msg-level=trace    # + msg_trace()

--quiet and --msg-level are mutually exclusive. See built-ins reference for the full visibility table.

✏️ In-place editing (--in-place)

Modify the input file directly:

fimod s -i config.json -e '{"host": data["host"], "port": data["port"]}' --in-place

Requires -i. Incompatible with -o.

👀 Watch mode (--watch / -w)

Re-runs the transform whenever the input file or a local mold script changes — handy for iterating on a mold while editing it in another window:

fimod s -i data.json -m cleanup.py -o out.json --watch

Output goes to the usual destination (-o file or stdout). Status messages stream on stderr, so piping still works:

fimod s -i data.json -m cleanup.py --watch | jq .name
# stderr: [watch] watching data.json, cleanup.py
# stderr: [watch] run #1 ok (42ms)
# stderr: [watch] run #2 ok (38ms)   (after editing cleanup.py)
# stdout: "alice"
# stdout: "alice"

A run that fails (Python error, parse error, missing file) is reported but does not exit the watch loop — fix the script and the next save triggers another run:

[watch] run #3 failed (12ms)
  in step 1/1 (cleanup.py): Python error in mold:
  NameError: name 'foo' is not defined

What is watched:

• -i <file> (the input file, must be local — not stdin or HTTP).
• Each -m <file.py> that points to a local file (registry molds @reg/name and inline -e expressions are not watched).

Refused combinations (each emits an explicit error):

If the input is removed mid-watch (e.g. git checkout of a branch that deletes it, or a rm between two cp commands), the watcher logs:

[watch] warn: input removed, waiting for it to reappear...

and keeps running. The next time the file reappears, a normal re-run fires. Atomic saves (vim, VSCode tmp + rename pattern) stay silent — only sustained absence triggers the warning.

Implementation details: events go through a two-level debounce. The first level (150 ms, hard-coded) absorbs the multiple notify events a single :w produces. The second level (default 500 ms, override via FIMOD_WATCH_QUIET_MS=<ms>) waits for the filesystem to be quiet before firing the re-run — needed under WSL2 / inotify cross-process latency where event bursts can stretch beyond 400 ms. Parent directories are watched so atomic-rename editors (vim, VSCode) work correctly. The mold script is reloaded from disk on every iteration; no in-memory cache to invalidate.

The feature can be disabled at compile time with cargo build --no-default-features --features=reqwest (omits notify and ~25 transitive crates). A binary built without watch rejects the flag with a clear error.

🔌 Stdin / stdout

# 📥 Read from stdin
cat data.json | fimod s -e '{"count": len(data)}'

# 🔗 Pipe chain
curl -s https://jsonplaceholder.typicode.com/todos | fimod s -e '[d for d in data if d["completed"]]' | jq .

🐍 Monty REPL (fimod monty repl)

Start an interactive Python REPL powered by the embedded Monty engine — no system Python needed.

fimod monty repl
# Monty REPL v0.0.8 — fimod v0.1.0-alpha.1 (exit or Ctrl+D to quit)
# >>> 2 + 2
# 4
# >>> [x ** 2 for x in range(5)]
# [0, 1, 4, 9, 16]
# >>> exit

Features:

• >>>/... prompts with automatic multi-line continuation (blocks, implicit line joins)
• Command history (arrow keys, via rustyline)
• Exit with exit or ++ctrl+d++

🐚 Shell completion

Fimod provides dynamic shell completions: subcommands, flags, format names, mold @references, and registry source names are all completed contextually.

Add one line to your shell rc — fimod setup completions prints the activation script on stdout, you eval it. The shell is auto-detected from $SHELL; pass --shell <SHELL> to override.

echo 'eval "$(fimod setup completions --shell bash)"' >> ~/.bashrc

echo 'eval "$(fimod setup completions --shell zsh)"' >> ~/.zshrc

fimod setup completions --shell fish > ~/.config/fish/completions/fimod.fish

echo 'eval (fimod setup completions --shell elvish | slurp)' >> ~/.elvish/rc.elv

Add-Content $PROFILE 'fimod setup completions --shell powershell | Out-String | Invoke-Expression'

What gets completed