CLI

The console script is research-tracker (entry point research_tracker:main). Every command takes the store root before the subcommand:

research-tracker --root ./artifacts run show

--root (aliases --artifact-root-dir, -o) is a path and defaults to ./artifacts relative to the current directory. The store is created if it does not exist, and validated if it does. All commands exit non-zero on error; on a schema mismatch or an incomplete store, ExperimentStore raises before any command logic runs.

run, evaluation, condition, metric, artifact

Each of the five tables gets the same three subcommands: show, query, and rm. The table name is the singular record kind, as above.

show

Print the table. Without -c a per-table default column set is printed.

research-tracker --root ./artifacts run show
research-tracker --root ./artifacts metric show -c metric -c value --json

• -c, --column, --col — column to display, repeatable. Replaces the default set.
• --json — emit DataFrame.to_json(orient="records") instead of a fixed-width table.

Default columns:

Table	Default columns
run	model, dataset, status, created_at
evaluation	name, run_id, created_at
condition	name, value, unit
metric	target, metric, value, comparison, sample_id
artifact	kind, sample_id, path

query

Filter with a pandas.DataFrame.query expression — a positional argument, so quote it in the shell.

research-tracker --root ./artifacts metric query "metric == 'mse'"
research-tracker --root ./artifacts run query "status == 'COMPLETED'" --json

• query — the expression, passed straight to DataFrame.query.
• -c, --column, --col — columns to display, repeatable.
• --json — emit DataFrame.to_json(orient="records", index=False).

On evaluation query, two extra flags remove the matched evaluations and everything hanging off them:

research-tracker --root ./artifacts evaluation query "name == 'test'" \
    --remove-all-associated --dry-run

• --remove-all-associated — run the cascade delete over the matched evaluation_ids instead of printing them.
• --dry-run / --dry_run — report the per-table counts and the artifact files that would be unlinked, without changing anything.

The cascade prints one line per table:

2 from evaluations table
14 from metrics table
0 from conditions table
6 from artifacts table

rm

Remove a single record by primary-key value.

research-tracker --root ./artifacts metric rm --id metric_2f3a...

• --id — required; the run_id, evaluation_id, condition_id, metric_id, or artifact_id to delete.
• --dry_run / --dry-run — print the matching row instead of deleting it.

rm deletes exactly the one row in that table; it does not cascade. To remove an evaluation together with its children, use evaluation query ... --remove-all-associated.

sync

Merge a copied store into the local one:

research-tracker --root ./artifacts sync /path/to/copied/store
research-tracker --root ./artifacts sync /path/to/copied/store --skip-copy-artifacts

• external_store — positional; the store directory (containing schema.json and store.sqlite) to merge in.
• --skip_copy_artifacts / --skip-copy-artifacts — merge records but copy no config, checkpoint, or artifact files.

The command prints progress to stdout: the source and destination roots, one line per copied file, and a per-category N copied, M already present summary. A conflict or a schema mismatch fails before any file is copied. See Sync for the merge rules and the quiescent-source requirement.

run import

Import an existing W&B run, including its checkpoint and merged config:

research-tracker --root ./artifacts run import \
    --run-path entity/project/abc123 \
    --model inverse-operator \
    --dataset dynamic-pet \
    --config configs/model.yaml --config configs/data.yaml \
    --checkpoint checkpoints/epoch=10.ckpt

• --run_path / --run-path — required; the W&B run path from its URL.
• --model — required; model name.
• --dataset — required; dataset name.
• --config / --cfg — required and repeatable; multiple files are merged with OmegaConf.merge.
• --checkpoint / --ckpt — required; path to the checkpoint.
• --dry-run / --dry_run — print the merged config and exit without writing.

Without --dry-run the merged config is saved next to the checkpoint as config.yaml and import_wandb_run records the run, reading model class, datamodule class, seed, and research run ID from the checkpoint's research_tracker metadata when present.

migrate

Upgrade a store in place from the legacy Parquet backend (schema version 1) to the SQLite backend (schema version 2):

research-tracker --root ./artifacts migrate --dry-run
research-tracker --root ./artifacts migrate

• --dry-run / --dry_run — print the row counts and modify nothing.
• --no-backup / --no_backup — leave the Parquet files in place instead of moving them into parquet-v1/.

The command prints the source row counts, the prepared table counts, the number of Parquet files moved, and a final Migrated: runs=N, ... summary. A store that is not a version-1 Parquet store, or that already contains a store.sqlite, fails with MigrationError and is left untouched.

Reading the Parquet files needs the migrate extra:

pip install "research-tracker[migrate]"

See Migration for what the command does, the backup directory, and why it refuses to run twice.