Skip to main content

Using the CLI

The metadata CLI turns a folder of raw jsPsych data into a Psych-DS compliant project. It works by asking you a short series of questions. This page walks through every prompt you'll see, in order, and explains what each one means and how to answer it. Prefer point-and-click? Use the web wizard instead — it does the same thing in your browser (see Using the wizard).

Each prompt below is shown exactly as it appears in your terminal, followed by what it's asking. Some prompts only appear in certain situations — those are marked (only if…).

Install & run

You'll need Node.js 18+ (check with node --version; install from nodejs.org). Then run:

npx @jspsych/metadata-cli

The first run downloads the tool automatically; after that it launches immediately. Every step is identical on macOS, Windows, and Linux — only the way you type a folder path differs (see step 5). Any modern terminal works: Terminal on macOS, PowerShell or Windows Terminal on Windows.

“What would you like to do?”

? What would you like to do?
❯ Create a new project
  Update an existing project

Your first choice, selected with the arrow keys and Enter:

  • Create a new project — start fresh: read your raw data and build a brand-new Psych-DS project from it. Pick this the first time.
  • Update an existing project — you've already generated metadata for this dataset before and want to refresh it (for example, after collecting more data). This loads the existing dataset_description.json before processing.

“Path to the folder…”

? Path to the folder where the new project will be created:

Type (or paste) the path to an existing folder to build the project inside. The tool creates a new subfolder here named after your project — it doesn't overwrite the folder you point at.

If you chose Update an existing project in step 2, you'll instead see:

? Path to existing project folder (must contain dataset_description.json):

Here you point directly at the project folder you generated before. If the folder doesn't contain a dataset_description.json, the tool rejects it and asks again.

“Enter the project name…”

? Enter the project name (used as the folder name and in the metadata):

(only if creating a new project.) The name is used two ways: it becomes the new subfolder's name, and it's recorded in the metadata as the dataset name. Hyphens are fine; avoid spaces (e.g. flanker-study, not flanker study).

“Path to your raw data folder…”

? Path to your raw data folder (files will be copied, not moved):

Point at the folder holding your jsPsych data files. The tool reads that folder and one level of subfolders. Your originals are copied, never modified.

Typing the folder path on Windows vs macOS

The prompt is the same on every platform; only the path format differs.

  • macOS / Linux: use forward slashes, e.g. /Users/you/Desktop/my-data. ~ is shorthand for your home folder, so ~/Desktop/my-data works too. Tip: drag the folder onto the terminal window to paste its full path.
  • Windows: use your full path, e.g. C:\Users\you\Desktop\my-data (backslashes are fine, and ~ works as well). Tip: hold Shift, right-click the folder, and choose Copy as path — then delete the surrounding " quotes before pressing Enter, since the tool reads them literally.
Which file formats are accepted?

CSV, a JSON array ([ {…}, {…} ]), the { "trials": [...] } wrapper (e.g. OSF exports), or JSON-Lines (.jsonl). Anything else is ignored.

JSON and JSON-Lines are converted to CSV in data/; CSV content is kept as-is where possible. Whenever a file has to change on the way in — a JSON file converted to CSV, or a CSV renamed or rewritten — the untouched original is also saved under data/raw/.

“How should these files be renamed?”

(only if your filenames don't match the Psych-DS pattern.) Psych-DS names data files keyword-value_data.csv (e.g. subject-01_data.csv). If yours don't match, the tool lists them and asks:

? How should these files be renamed?
❯ Use the value found inside each file
  Keep only the part that differs
  Give the files fresh numbered names
  Keep the whole old filename as the value

Each strategy comes with a live preview on your real filenames, so you can see the result before committing:

  • Use the value found inside each file (recommended when offered) — reads an ID column from the data itself, so it works even when the old names are meaningless.
  • Keep only the part that differs — strips the shared prefix/suffix; the varying middle becomes the value.
  • Give the files fresh numbered names — a clean sequence like subject-001, subject-002. You'll be asked Name for the first file….
  • Keep the whole old filename as the value — the safe fallback: nothing is lost, but names get verbose.

After you pick a strategy the tool shows the full set of proposed renames and asks:

? Apply these names?
❯ Apply
  Edit one filename
  Choose a different strategy

Choose Edit one filename to fix a single name by hand (it asks Which file? then New name…), or Choose a different strategy to start over. You may also be asked Choose a Psych-DS keyword to label these files: (the keyword part, like subject or task) and, for names that are technically valid but use an unofficial keyword, Rename these files too?.

For the full strategy table and keyword list, see Data file naming.

“Select additional join-key columns…”

? Select additional join-key columns for extracted array CSVs:

(only if a file contains nested arrays and trial_index isn't unique.) When the tool extracts a nested array into its own CSV, each row needs a column that uniquely identifies it. Candidates are grouped into "Sufficient alone" and "Reduces duplicates," with a "Proceed anyway" escape. Flat, single-participant datasets skip this entirely. See Nested arrays and join keys.

“Would you like to customize the metadata?”

? Would you like to customize the metadata?
❯ Use defaults
  Use a custom metadata file

Pick Use defaults to accept the automatically generated metadata (you can always edit dataset_description.json later, or re-run the CLI). Pick Use a custom metadata file to supply a metadata options file, at which point it asks:

? Path to metadata options .json file:

A metadata options file lets you add authors, a study description, or override variable descriptions — the command-line equivalent of the wizard's forms. See Customizing the output for the file format.

“…fill in unknown descriptions?”

? 3 variable(s) have unknown descriptions. Would you like to fill them in?
❯ Fill in descriptions
  Skip

(only if some variables couldn't be described automatically.) The tool looks up each column's description from the jsPsych plugin that produced it. For anything it can't identify, you can add a description by hand. Pick Fill in descriptions and it walks each one:

? Description for "response" (press Enter to skip):

Type a short description, or press Enter to leave it as unknown.

Validate & get your project

Finally the tool validates the result against Psych-DS and reports pass or fail:

✔ Psych-DS validation passed (2 warnings).
  (Rerun with --verbose to see warnings.)

If a required field is missing, it prompts you to supply it before finishing, e.g. Value for required field "description":. You end up with a self-contained project in your chosen folder:

my-experiment/
├── data/                       Psych-DS compliant copies of your data
│   └── raw/                     your untouched originals, if anything changed
├── dataset_description.json    generated metadata
├── README.md                   placeholder for a description
└── CHANGES.md                  placeholder for a changelog

Open dataset_description.json to see the generated variables and their descriptions.

Next: Customizing the output to add authors and descriptions, or the CLI reference for every flag. Stuck? See Troubleshooting.