Skip to main content

expctl — Experiment Control

A universal, local-first experiment lifecycle manager inspired by Git.

CI PyPI Python 3.11+ MIT license

English · Русская документация

Git tracks how code changes. expctl tracks how experiments happen.

expctl records experiments, immutable runs, changes, failures, retries, arbitrary results, artifacts, observations, and conclusions. It works for software, hardware, scientific, and manual experiments without embedding assumptions about a particular domain.

EXP-... experiment
├── RUN-001 failed
│   └── CHG-001 fix
│       └── RUN-002 retry completed
├── RUN-003 completed · BEST
├── notes and next actions
└── derived experiments

Why expctl?

A Git commit tells you which code existed. It does not tell you:

  • which command or physical procedure was executed;
  • whether the run failed, was interrupted, or produced incomplete outputs;
  • which change led to a retry;
  • which metrics, typed conditions, and artifacts were recorded;
  • which result is currently considered best;
  • what should happen next;
  • whether the experiment can be transferred to another project.

expctl stores that missing experiment history while using Git when it is available.

Principles

  • Universal: no required ML, robotics, or scientific vocabulary.
  • Local-first: SQLite plus human-readable JSON and Markdown records.
  • Git-aware, not Git-dependent: software and manual experiments use the same core.
  • Immutable runs: retry and resume create linked records rather than rewriting history.
  • Validated success: exit code 0 can still become incomplete when required outputs are missing.
  • Extensible metadata: free-form tags, arbitrary metrics, and typed custom fields.
  • Portable: experiments can be exported and imported as ZIP bundles.

Installation

For command-line applications, pipx is recommended:

pipx install expctl

Using pip is also supported:

python3 -m pip install expctl

Check the installation:

expctl --version
# expctl 0.3.0

Quick start

mkdir my-experiment && cd my-experiment
expctl init --name my-project

expctl new \
  --name baseline \
  --goal "Check the current implementation" \
  --command "python3 task.py" \
  --metrics "out/metrics.json" \
  --required-file "out/result.bin" \
  --required-metric score \
  --tag baseline

expctl run

When code changes after a failed run:

expctl fix FAILED \
  -m "Fixed incorrect boundary handling" \
  --commit

expctl retry FAILED

Navigation and history

Built-in references are resolved inside the current experiment:

CURRENT_EXP  current selected experiment
LATEST       latest run of CURRENT_EXP
FAILED       latest unsuccessful run of CURRENT_EXP
BEST         selected best run of CURRENT_EXP

Custom aliases are supported:

expctl alias set baseline LATEST
expctl show baseline

Display a Git-inspired tree:

expctl log CURRENT_EXP --graph --metric score

Example:

EXP-20260723-001  baseline  [completed] · BEST=RUN-20260723-002
└── RUN-20260723-001  run  [failed]
    └── CHG-20260723-001  fix  Fixed boundary handling
        └── RUN-20260723-002  retry  [completed] · score=0.91

Compare and select results

expctl compare RUN-001 RUN-002 RUN-003 \
  --metric score \
  --metric latency \
  --field device

Choose the best run manually:

expctl best set RUN-003 -m "Best balance of quality and latency"

Or use one explicit numeric rule:

expctl best select CURRENT_EXP --metric latency --minimize

Tags and typed fields

Tags remain free-form:

expctl tag add LATEST verified
expctl tag add CURRENT_EXP outdoor

Typed custom fields avoid domain-specific columns in the core:

expctl field set LATEST device "Raspberry Pi 5" --type string
expctl field set LATEST temperature 71.5 --type number --unit C
expctl field set CURRENT_EXP controlled true --type boolean
expctl field set CURRENT_EXP started 2026-07-23T14:30:00 --type datetime

Supported field types:

string, number, integer, boolean, datetime, path, json

Observations and next actions

Timestamped observations do not alter run status:

expctl note LATEST "Vibration appeared after five minutes" --kind observation

Minimal next actions stay intentionally smaller than a task manager:

expctl next add LATEST "Repeat outdoors"
expctl next list CURRENT_EXP
expctl next done ACT-...

Export and import

Export metadata, logs, patches, and records:

expctl export CURRENT_EXP --output experiment.zip

Include copied artifact contents:

expctl export CURRENT_EXP \
  --output experiment-with-artifacts.zip \
  --include-artifacts

Import into another initialized project:

expctl init --name target-project
expctl import experiment-with-artifacts.zip

Imports preserve experiment, run, and change IDs and therefore reject collisions.

Manual physical experiment

Git and a child command are optional:

expctl new \
  --name outdoor-range \
  --goal "Measure maximum stable range" \
  --required-metric max_range \
  --tag hardware

expctl run --manual

expctl result LATEST \
  --mark-completed \
  --metric max_range=42.7:m \
  --metric packet_loss=0.8:percent \
  --artifact measurement.txt \
  --copy

Validation model

exit code != 0
→ failed

exit code = 0, but a required file or metric is missing
→ incomplete

exit code = 0 and all configured checks pass
→ completed

Commands in 0.3.0

Area Commands
Project init, config, doctor, status
Experiments new, use, list, show, log, derive, archive
Runs run, retry, resume, cancel, recover, compare
Changes change, fix, diff
Results result, validate, conclude, best
Metadata tag, field, alias, note, next
Portability export, import

Development

git clone https://github.com/CactysFedya/expctl.git
cd expctl
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"
pytest
make demo

Expected for 0.3.0:

9 passed
expctl 0.3.0

Database upgrade

Opening a 0.2.0 project with 0.3.0 automatically migrates the local database from schema version 2 to 3. Back up .expctl/expctl.db before upgrading important projects. Downgrading the migrated database to 0.2.0 is not supported. See docs/UPGRADING.md.

Security

expctl executes commands supplied by the user and can copy files into experiment bundles. Review commands and paths from untrusted projects before running or importing them. See SECURITY.md.

Project status

0.3.0 is alpha software. The data model and CLI may evolve before 1.0.0.

Contributing

Bug reports, design proposals, documentation improvements, and pull requests are welcome. Read CONTRIBUTING.md.

License

MIT. See LICENSE.

Metadata

Release files for expctl 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for expctl 0.3.0
File Size Uploaded Provenance Actions
expctl-0.3.0.tar.gz 57.6 kB With provenance Details for expctl-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for expctl 0.3.0
File Interpreter ABI Platform Actions
expctl-0.3.0-py3-none-any.whl Python 3 none any Details for expctl-0.3.0-py3-none-any.whl

Total release size: 104.6 kB

Release files / expctl-0.3.0.tar.gz

Download URL expctl-0.3.0.tar.gz
Size 57.6 kB
Tags Source
SHA-256 checksum
How to use checksums
bdbb697c6c4024dd13a7d71e04ff0a2ce64cb47ff465d21df14596734cf0d451
BLAKE2b-256 checksum
How to use checksums
b0634d64ae981fc97dd161919f33598c2139319e4b9120ec45ef70d1253191b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 23, 2026.

Transparency log

Release files / expctl-0.3.0-py3-none-any.whl

Download URL expctl-0.3.0-py3-none-any.whl
Size 47.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f4b5e0eaf4e73fbf2cc3836dd850dce2edfbb2ed2e72592ebf16dde298f17ced
BLAKE2b-256 checksum
How to use checksums
d9dc58104f05762c97e1fca48d47546640830a7c5aa6d9ef15c1f6d843c4a10d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 23, 2026.

Transparency log

Security for expctl 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for expctl-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 23, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page