Skip to main content

Crate flodl_cli

Crate flodl_cli 

Source
Expand description

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:

§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§

add
Ecosystem-crate scaffolding (fdl add <target>): drops a configured sub-project inside a flodl project for hands-on discovery. Currently supports flodl-hf. fdl add flodl-hf – two modes for wiring flodl-hf into a project.
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.
cluster
Cluster-mode env preparation. fdl-cli sets FLODL_INTERNAL_FULL_CLUSTER_JSON
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.
gpus
--gpus flag parsing + single-host cluster envelope synthesis (loopback, one host, N ranks). Used when --gpus is set on a cluster-aware command and no cluster: block is configured in YAML. --gpus flag parsing + single-host cluster envelope synthesis.
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.
nccl
NCCL source builds (fdl nccl build). Drops a standalone libnccl.so into libtorch/nccl/builds/<ver>-<archs>/ for the LD_PRELOAD bridge pattern used by cross-host heterogeneous-arch clusters. NCCL source builds (libtorch bundled-NCCL bridge).
overlay
Environment overlay loader (@env, --env, FDL_ENV) with per-field origin annotations for fdl config show. Multi-environment configuration overlays.
prebuild
Pre-flight build for cluster commands. Builds the target binary locally (in Docker on the controller) for each remote host’s libtorch ABI before fan-out, delivering it via the shared project-root mount so the remote can exec it directly without a cargo / rustc toolchain. Pre-flight build for cluster commands.
probe
Cluster readiness probe (fdl probe): GPU + libtorch arch + shared-data path + NCCL discovery. Pre-training gate; the foundation for fdl deploy and the transparent launcher dispatch. fdl probe — check host readiness for training.
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; staleness is mtime-based against the command’s config AND, for a compile: true command, the sources its schema is compiled from. --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.
status
Live run status (fdl status): fetches the controller’s state.json (membership + lifecycle phase) and pretty-prints it. fdl status — live cluster run status.
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.
update_check
Daily update check against crates.io for flodl-cli and project-pinned flodl / flodl-hf. Opt out via FDL_NO_UPDATE_CHECK=1 or the global config file. Daily update check for fdl and the user-facing flodl crates.
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 to generate an argv parser, --fdl-schema JSON emitter, and ANSI-coloured --help renderer.