Crate flodl_cli 

flodl-cli — library side of the fdl binary.

This crate is both a library and a binary. The binary (fdl) is the user-facing driver; the library exposes the pieces that other crates (e.g. a flodl-based training binary) need to integrate with the fdl ecosystem:

• FdlArgs — derive macro + trait for argv parsing and schema emission
• parse_or_schema — intercepts --fdl-schema / --help and dispatches
• Schema, OptionSpec, ArgSpec — the canonical schema shape

Example

use flodl_cli::{FdlArgs, parse_or_schema};

/// My training binary.
#[derive(FdlArgs, Debug)]
struct Cli {
    /// Model to run.
    #[option(short = 'm', default = "all")]
    model: String,

    /// Write a report instead of training.
    #[option(default = "runs/report.md")]
    report: Option<String>,
}

fn main() {
    let cli: Cli = parse_or_schema();
    // ... use cli.model, cli.report, etc.
}

Re-exports

pub use args::parse_or_schema;

pub use args::parse_or_schema_from;

pub use args::FdlArgsTrait;

pub use config::ArgSpec;

pub use config::OptionSpec;

pub use config::Schema;

Modules

api_ref

Structured API reference for flodl itself (fdl api-ref), used by AI porting tools and as a machine-readable surface index. API reference generator: extracts the public API surface from flodl source.

args

Argv parsing primitives and the FdlArgsTrait contract that #[derive(FdlArgs)] implements. Argv parser and FdlArgs trait — the library side of the #[derive(FdlArgs)] machinery.

builtins

Built-in fdl sub-commands (setup, install, completions, schema, config, libtorch, diagnose, init, skill, …). Registry of built-in commands. Single source of truth for dispatch, help listing, collision detection, and shell completion.

completions

Shell completion script generation and per-project completion enrichment driven by cached schemas. Shell completion generation and one-shot setup.

config

fdl.yml manifest loading, validation, and resolved-command types. fdl.yaml configuration loading and discovery.

context

Cross-cutting context passed to sub-command handlers (resolved config, verbosity, overlay selection, working directory, …). Execution context: project-local vs global (~/.flodl).

diagnose

Hardware and compatibility diagnostics (fdl diagnose). fdl diagnose – system and GPU diagnostics.

dispatch

Top-level command dispatch: routing argv to built-ins vs. manifest entries, resolving the three command kinds (run / path / preset). Pure command-graph dispatch.

init

Project scaffolding (fdl init): generates Dockerfile, fdl.yml, training template, .gitignore. fdl init <name> – scaffold a new floDl project.

libtorch

libtorch variant management (download, build, list, activate, remove, info) used by both fdl libtorch and the standalone-manager flow.

overlay

Environment overlay loader (--env, FDL_ENV, first-arg convention) with per-field origin annotations for fdl config show. Multi-environment configuration overlays.

run

Runtime: invoking resolved commands, streaming their output, and mapping exit codes through fdl. Command resolution and execution.

schema

fdl schema sub-command: discover every cache under the project, report fresh / stale / orphan states, and clear or refresh on demand. The Schema type itself lives in config. fdl schema — inspect, clear, and refresh cached --fdl-schema outputs across the project.

schema_cache

--fdl-schema binary contract and per-command cache mechanics. Caches live at <cmd_dir>/.fdl/schema-cache/<cmd>.json with mtime + binary hash metadata for staleness detection. --fdl-schema binary contract: probe, validate, and cache.

setup

First-run and reconfiguration wizard (fdl setup). fdl setup – interactive guided setup wizard.

skill

AI-skill bundles: packaging and installing the /port skill and similar assistant integrations. AI coding assistant skill management.

style

ANSI styling primitives and the --ansi / --no-ansi / NO_COLOR resolution chain used by the help renderer and CLI output. Terminal colors and formatting.

util

Miscellaneous helpers shared by the other modules.

Macros

cli_error

Print a red-prefixed error: <formatted> line to stderr.

Derive Macros

FdlArgs

Derive macro for FdlArgs. Generates argv parsing, --fdl-schema emission, and --help rendering from a single struct definition. Derive FdlArgs on a struct with named fields to generate an argv parser, --fdl-schema JSON emitter, and ANSI-coloured --help renderer. See the crate-level docs for the attribute reference and a worked example.