CLI reference on ExpLedger

expledger

Mon, 01 Jan 0001 00:00:00 +0000

expledger

Manage experiment records in an initialized project

Synopsis

Manage experiment records and run scripts in an initialized project. Run init once in the project directory. Other commands find the nearest expledger.yaml in the current directory or its parents. Help needs no project. See https://marcfranquesa.github.io/expledger/ for guides and configuration.

Examples

 expledger init
 expledger new baseline
 expledger list

Options

 -h, --help help for expledger
 -v, --version version for expledger

expledger build

Mon, 01 Jan 0001 00:00:00 +0000

expledger build

Build a static experiment web page

Synopsis

Write a self-contained index.html snapshot, newest experiments first. Include optional report.yaml blocks and their Markdown and CSV sources. Create the output directory if needed and replace its index.html on each build. Other files in the directory are left unchanged. The root expledger.yaml's optional remote_url supplies the full browser URL of the remote experiments directory. Each ID path segment is escaped and appended; omit remote_url for a local-only catalog. Only the current project is included; sources applies only to serve. The generated page needs no running ExpLedger server and does not poll.

expledger init

Mon, 01 Jan 0001 00:00:00 +0000

expledger init

Initialize an ExpLedger project in the current directory

Synopsis

Create expledger.yaml in the current directory. Existing valid config is left unchanged. Use --remote-url for the full browser URL of the remote experiments directory.

expledger init [flags]

Examples

 expledger init
 expledger init --remote-url https://github.com/owner/repo/tree/main/experiments

Options

 -h, --help help for init
 --remote-url URL Full browser URL of the remote experiments directory

expledger list

Mon, 01 Jan 0001 00:00:00 +0000

expledger list

List experiment IDs and titles

Synopsis

Read experiment.yaml files recursively under the configured experiments_dir. The project expledger.yaml defaults experiments_dir to experiments. Display IDs and titles by created_at, newest first. Each YAML id must exactly match its path relative to experiments_dir. IDs containing whitespace, quotes, or non-printable characters are double-quoted, using Go-style escapes such as \t and \n. Title whitespace is collapsed to spaces; other non-printable characters are escaped. Explore grouping directories, but do not scan inside experiment folders. Report invalid metadata with its path.

expledger new

Mon, 01 Jan 0001 00:00:00 +0000

expledger new

Create an experiment folder, metadata, README, and run.sh

Synopsis

Create experiment.yaml, README.md, and executable run.sh in a new experiment folder. Configure experiments_dir and experiment_format in the project expledger.yaml. Defaults are experiments/ and {date:20060102}-{slug}, producing experiments/YYYYMMDD-SLUG/. Use {date}/{slug} for date folders or {date}/{time}-{slug} for timestamps. {date} inserts the local YYYY-MM-DD date, {time} the local HH-MM-SS time, and {slug} the positional slug. Customize with native Go time.Time.Format layouts: 2006 for the year, 01 for the month, 02 for the day, 15 for the hour (24-hour clock), 04 for the minute, and 05 for the second. Use {time:15:04} for hours:minutes or {time:05:04:15} for seconds:minutes:hours. Unrecognized layout text remains literal. See https://pkg.go.dev/time#Time.Format for the reference-time layout syntax. Literal text is unchanged. Placeholders can repeat or be omitted. Slugs contain lowercase letters, digits, and single hyphens between words. Existing experiments are never overwritten. Validate only the direct parents named by --based-on. Each must have a valid experiment.yaml whose id exactly matches its path relative to experiments_dir.

expledger run

Mon, 01 Jan 0001 00:00:00 +0000

expledger run

Run an experiment's run.sh in its existing folder

Synopsis

Execute ./run.sh from experiments_dir/ID/ with the current checkout and environment. The project expledger.yaml configures experiments_dir, defaulting to experiments. Keep workload parameters in run.sh or its input files; extra arguments are rejected. The script chooses output paths. Metadata is not changed and no provenance is recorded. Git is not required. The shebang selects the runtime. Standard streams and exit status are forwarded. Ctrl+C stops the workload and its ordinary child processes. Requires macOS or Linux; supports batch workloads, not interactive terminal input or daemons.

expledger serve

Mon, 01 Jan 0001 00:00:00 +0000

expledger serve

Browse experiments in a local web page

Synopsis

Serve experiments on 127.0.0.1 with live list and lineage views. Include optional report.yaml blocks with shared chart styling. Poll configuration, records, and report sources every few seconds without reloading the page. Use sources in expledger.yaml, or repeat --source to replace that list. Paths name project roots; relative paths resolve from the current project config directory. No ~ or environment-variable expansion is performed. The first source wins each ID, including its relationships and remote links. Other commands remain scoped to the current project. Failed refreshes keep the last valid view until recovery. Press Ctrl+C to stop the server.

expledger validate

Mon, 01 Jan 0001 00:00:00 +0000

expledger validate

Validate experiment metadata

Synopsis

Check experiments_dir/ID/experiment.yaml at the project root. The project expledger.yaml configures experiments_dir, defaulting to experiments. Require schema: expledger/v1 and valid id, title, and created_at fields. The YAML id must match its path relative to experiments_dir. README.md is independent. Report the first error with its file path; no files are changed.

expledger validate <id> [flags]

Examples

 expledger validate 20260924-my-idea

Options

 -h, --help help for validate

CLI reference on ExpLedger

expledger

expledger

Synopsis

Examples

Options

SEE ALSO

expledger build

expledger build

Synopsis

expledger init

expledger init

Synopsis

Examples

Options

SEE ALSO

expledger list

expledger list

Synopsis

expledger new

expledger new

Synopsis

expledger run

expledger run

Synopsis

expledger serve

expledger serve

Synopsis

expledger validate

expledger validate

Synopsis

Examples

Options

SEE ALSO