ProMeta CLI usage

prometa-cli is the command-line application for ProMeta workflows. It depends on the core statistics package, source interoperability package, plot packages, and plot adapters.

This is a full reference, but for the exact options a given command takes, run it with --help — that's always correct and up to date, unlike prose that has to be updated by hand. If you're an AI agent using this CLI on someone's behalf, check --help output for a command's exact flags rather than guess them; this doc is enough context to know which command to reach for.

prometa --help              # list every command
prometa <command> --help    # options for one command
prometa manual               # print this document to the console

Commands, by workflow

Source datasets

A source dataset (CSV or JSON) is the input everything else works from — one row per study, one column per raw effect-size input. These commands create, inspect, and maintain one.

Analysis

Run on a validated source dataset to produce the pooled result and its diagnostics.

Moderators

For testing whether a categorical or continuous moderator explains some of the heterogeneity.

Publication bias

Plots

Render analysis results as SVG. --plot-csv / --plot-json options (see --help) feed a plot command from a prior analysis command's output. Template checkers and renderers live in the standalone plot packages (prometa-forest-plot, prometa-funnel-plot, prometa-scatter-plot); analysis-to-plot conversion lives in prometa-plot-adapters.

Reference / lookup

Don't touch your data — list what the CLI supports, for scripting or documentation purposes.

Inputs and outputs

Common inputs are CSV, JSON, TOML template files, and CLI options. Source dataset commands use the JSON schema in docs/schemas/prometa-source-dataset.schema.json. Commands write human-readable text, CSV/JSON datasets, or SVG plots depending on the command; plot commands use TOML templates where supported.

Most analysis commands (summary, heterogeneity, sensitivity, …) print a human-readable table by default, but also accept --output-json <path> (and --plot-json <path> for the forest-plot rows a command generates). If something downstream — a script, another command, an AI agent — is going to read the result back, use the JSON output instead of parsing the printed table: it's structured, and its field names don't change between a terminal-width table and a redirected file the way column alignment can.

Interactive mode

Every command that needs input accepts -i / --interactive to be prompted for missing values instead of passing them as options. Interactive prompts collect the same values as the non-interactive options and run the same schema/range checks, so scripted and interactive use behave consistently — anything you do pass as an option is used as-is and simply not prompted for.

For example, prometa source-add-row --input-csv studies.csv --raw-effect-size-id 1100 --interactive prompts, in order: Study, then Subgroup / Comparison / Timepoint / Outcome (each defaults to its placeholder if left blank), then one prompt per raw field for format 1100 — Mean group A, Standard deviation group A, Sample size group A, Mean group B, Standard deviation group B, Sample size group B, and Effect direction (allowed: auto | positive | negative), defaulting to auto. Leaving --raw-effect-size-id off too would add one more prompt in front for it.

A typical pipeline

prometa source-init --output-csv studies.csv --raw-effect-size-id 1100
# ... fill in studies.csv, one row per study ...
prometa validate --input-csv studies.csv -e Hedges_s_g
prometa summary --input-csv studies.csv -e Hedges_s_g --plot-csv forest-rows.csv
prometa forest-plot --input-csv forest-rows.csv --output-svg forest.svg --null-value 0

Exact option names vary by command and by effect-size type — --help on each command is the source of truth.

Worked example: adding a row to a source CSV

Every source row needs a raw effect-size format id, which tells the CLI which columns (--data fields) that row needs. List the formats:

prometa raw-formats

This prints every supported format grouped by category and design, each with its numeric id and required field keys — for example 1100 under "Means → Two Independent Groups, Cross Sectional". Get the exact column names and types for one format with:

prometa raw-formats --format 1100

The Field column (group_a_mean, group_a_sd, …) is exactly what --data expects as NAME=VALUE pairs. With that, create the dataset and add one row:

prometa source-init --output-csv studies.csv --raw-effect-size-id 1100

prometa source-add-row \
  --input-csv studies.csv \
  --raw-effect-size-id 1100 \
  --study "Smith2020" \
  --data group_a_mean=12.4 \
  --data group_a_sd=3.1 \
  --data group_a_n=30 \
  --data group_b_mean=9.8 \
  --data group_b_sd=2.9 \
  --data group_b_n=28 \
  --data effect_direction=auto

studies.csv now has a header and one row:

study,rawEffectSizeId,group_a_mean,group_a_sd,group_a_n,group_b_mean,group_b_sd,group_b_n,effect_direction,subgroup,comparison,timepoint,outcome
Smith2020,1100,12.4,3.1,30,9.8,2.9,28,auto,NO-SUBGROUP,NO-COMPARISON,NO-TIMEPOINT,UNKNOWN-OUTCOME

A few things worth knowing about the fields above:

• subgroup, comparison, timepoint, and outcome are optional. Left out, they get a placeholder value (NO-SUBGROUP, and so on) — pass --subgroup, --comparison, --timepoint, or --outcome to set them explicitly instead.
• effect_direction accepts auto for most formats, or one of the fixed values raw-formats --format <id> lists, for formats that don't allow auto.
• To add more studies, repeat source-add-row (with the same --raw-effect-size-id) once per study.
• To be prompted for every field instead of passing --data flags, skip --study etc. and add --interactive.

Or just edit the file directly

source-add-row isn't the only way to add rows — the source file is a plain CSV, so once you know the column names for your raw effect-size format (from raw-formats --format <id>, same as above), you can just open it in a text editor or a spreadsheet program (Excel, LibreOffice Calc, Google Sheets) and fill in rows directly, exactly like any other CSV. source-init still saves a step by writing the correct header row for you; after that, pasting or typing values into the spreadsheet is often faster than one source-add-row command per study, especially with many rows. Run prometa validate --input-csv studies.csv -e Hedges_s_g afterwards either way, to catch typos or out-of-range values before running an analysis.