ExpLedger

Getting started

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

Getting started

ExpLedger keeps coding experiments as folders in your project. Each folder has structured metadata, independent notes, and a script you can run in place. There is no database or automatic Git provenance. ExpLedger is in active development; expect breaking changes.

Install

Follow the installation guide to install the CLI and add it to your PATH. The installed CLI has no Git dependency. Running experiment scripts requires macOS or Linux.

Installation

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

Installation

The planned first release is v0.1.0. It has not been published yet; the release installation examples below become available when it is published.

Release archives

Download the archive for your machine and checksums.txt from the same GitHub Release. Archives support macOS (darwin) and Linux (linux), each on arm64 and amd64. Apple Silicon uses darwin_arm64; Intel Macs use darwin_amd64.

For example, on Apple Silicon, after downloading both files:

shasum -a 256 --ignore-missing -c checksums.txt
tar -xzf expledger_0.1.0_darwin_arm64.tar.gz
mkdir -p "$HOME/.local/bin"
install -m 755 expledger "$HOME/.local/bin/expledger"

Confirm the downloaded archive is reported OK before extracting it. Each archive contains expledger and the MIT LICENSE. Add $HOME/.local/bin to your PATH if needed. Archives are not Apple-notarized.

Configuration

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

Configuration

The initialized project root contains expledger.yaml, exactly one YAML mapping with optional settings:

experiments_dir: experiments
experiment_format: "{date:20060102}-{slug}"
remote_url: https://github.com/owner/repo/tree/main/experiments
sources:
 - .
 - ../experiment-worktree
 - /Users/me/projects/another-worktree

Set remote_url when initializing a project; edit the config for other settings:

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

For an existing project, edit remote_url in its root expledger.yaml explicitly. build and serve use it for each experiment's View remote link. It must point to the published experiments directory, not the repository home page.

Running experiments

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

Running experiments

expledger new creates an executable <experiments_dir>/<id>/run.sh stub that exits with configuration guidance. Replace it with the experiment's commands, using a shebang and fixed parameters. For example, with experiment.py beside it:

#!/bin/sh
exec uv run --locked python experiment.py --seed 42

Follow Getting started to initialize a project and create a record, then prepare the code and dependencies you want. Git is not required. Run:

expledger run <id>

ExpLedger executes ./run.sh directly from the existing experiment directory. Use the full ID relative to the configured experiments folder, including any grouping path such as 2026-10-06/baseline. The script inherits your environment and writes results wherever it chooses. Keep parameters in the script or nearby configuration; additional arguments and revision-selection options are rejected. Both run.sh and experiment.yaml must be regular files, and run.sh must be executable. Supporting files are left to the script.

Experiment format

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

Experiment format

Each experiment has <experiments_dir>/<id>/experiment.yaml under the initialized project root. The directory defaults to experiments; see Configuration to customize it and the creation format. This file is the sole source of ExpLedger metadata. README.md holds independent notes; other files can hold scripts, artifacts, or another tool's metadata. new creates a README and an executable run.sh stub; neither file is required for catalog reads. An optional report.yaml declares a browser report using Markdown and CSV results; see Experiment reports.

Experiment reports

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

Experiment reports

Add an optional report.yaml beside an experiment's experiment.yaml to compose a report from Markdown and CSV results. build bundles each report into its self-contained HTML snapshot; serve refreshes reports as their files change. Experiments without report.yaml remain ordinary catalog entries.

Reports follow the project's configured experiments_dir and experiment ID, including IDs with nested grouping folders. For example, an experiment with ID 2026-10-06/baseline under experiments_dir: trials keeps its report at trials/2026-10-06/baseline/report.yaml.

Versions and releases

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

Versions and releases

v0.1.0 is the planned first release, not an existing published release. Maintainers choose versions manually. There is no release per PR and no version inference from commit messages.

Compatibility policy

ExpLedger follows Semantic Versioning. Within SemVer's initial development phase, this project uses these conventions:

During 0.x, compatible fixes and small internal improvements increment the patch version (for example, 0.1.0 to 0.1.1).
New functionality or breaking changes increment the minor version (for example, 0.1.1 to 0.2.0). Breaking changes require clear migration notes.
1.0.0 marks a stable public interface. After that, incompatible public changes increment major, compatible features minor, and compatible fixes patch.

The public interface includes commands, flags, configuration, experiment records, and documented execution behavior. Internal Go packages are not part of that interface.

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

ExpLedger

Getting started

Getting started

Install

Installation

Installation

Release archives

Configuration

Configuration

Running experiments

Running experiments

Experiment format

Experiment format

Experiment reports

Experiment reports

Versions and releases

Versions and releases

Compatibility policy

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