Publish from your terminal.

mdf is the Materials Data Facility on the command line: describe a dataset once in a manifest, preview exactly what will be sent, then submit and watch it into the curation queue — without leaving the directory the data lives in.

Install it See the commands

~/xrd-mapbi3 — mdf session

$ mdf login --service staging
Authentication ready
Token store: /Users/jalvarez/.config/mdf/tokens.json

$ mdf publish

╭──────────────────────────────────────────────────────────────────────────────╮
│ Publish preflight                                                            │
│ Service: staging                                                             │
│ Files: 14                                                                    │
│ Bytes: 84.7 MB                                                               │
│ Target: https://3xicgt0g7l.execute-api.us-east-1.amazonaws.com/staging       │
╰──────────────────────────────────────────────────────────────────────────────╯
┏━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━┓
┃ Source      ┃ Kind  ┃ Files ┃   Bytes ┃
┡━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━┩
│ ./patterns  │ local │    12 │ 84.2 MB │
│ ./README.md │ local │     1 │  2.1 kB │
│ ./meta.csv  │ local │     1 │456.3 kB │
└─────────────┴───────┴───────┴─────────┘
No preflight issues detected.

Dry run - would submit:
Target: https://3xicgt0g7l.execute-api.us-east-1.amazonaws.com/staging (staging)
{
  "title": "XRD of MAPbI3 Thin Films",
  "authors": [
    {
      "name": "Jane Alvarez"
    }
  ],
  "description": "Grazing-incidence XRD for MAPbI3 films annealed at four temper
  "publisher": "Materials Data Facility",
  "resource_type": "Dataset",
  "data_sources": [
    "/Users/jalvarez/xrd-mapbi3/patterns",
    "/Users/jalvarez/xrd-mapbi3/README.md",
    "/Users/jalvarez/xrd-mapbi3/meta.csv"
  ],
  "test": false,
  "update": false,
  "update_metadata_only": false
}

Ready to publish. Run:
  mdf publish --submit

$ mdf publish --submit
⠿ Upload complete ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 14/14

Published successfully!
  Source ID: alvarez_xrd_mapbi3_films
  Service: staging
  Status: pending_curation
  Version: 1.0
  Try: mdf status alvarez_xrd_mapbi3_films | mdf show alvarez_xrd_mapbi3_films

Watching alvarez_xrd_mapbi3_films (poll every 5s, timeout 1800s)

  ~ pending_curation  (3s)

Backend status: alvarez_xrd_mapbi3_films v1.0
  Status: ~ pending_curation
  Title: XRD of MAPbI3 Thin Films
  Next: Waiting for curation review
  Try: mdf status --watch alvarez_xrd_mapbi3_films

Sixty seconds to your first search

The package is mdf-cli; the command is mdf.

Installs the CLI in its own environment. pip works too.
$pipx install mdf-cli
One browser round-trip with Globus; the token is then cached on disk.
$mdf login --service staging
Check it works — and searching needs no login at all.
$mdf search "perovskite"

Four things you will actually do

Each block is a whole task, start to finish. Every command and flag below comes straight out of mdf --help.

Publish a dataset

A manifest describes the dataset once. The CLI handles transfer, the submit-time checks, and the hand-off to curation — and it will not send anything until you say so.

$mdf login --service staging
Authenticate with Globus once — the token is cached on disk.
$mdf setup
Answer four prompts; writes an mdf.yaml next to your data.
$mdf publish --preflight-only
Run the submit-time checks without uploading a byte.
$mdf publish
Dry run is the default: see the exact payload before it leaves your laptop.
$mdf publish --submit
Uploads, submits, then watches until the record reaches the curation queue.

mdf — find and clone

Find and clone

Reading is public. No account, no login, no browser.

$mdf search "perovskite"
Keyword search across datasets and streams at once.
$mdf search "battery cathode" --semantic
Vector search over title and description embeddings.
$mdf show darpa_sd2_perovskites --cite
The full record, plus a citation you can paste.
$mdf clone darpa_sd2_perovskites ./local_copy
Takes the fastest route available: zip, HTTPS, or Globus Transfer.
$mdf related darpa_sd2_perovskites --by similar
Nearest neighbours over the dataset embedding snapshot.

mdf — enrich a migrated record

Enrich a migrated record

Older records carry thin metadata. Clone one, improve it, publish the improvement.

$mdf list --search perovskite
Find your own submissions by title, source ID, or DOI.
$mdf clone my_dataset_v1 --derive
Clones the data and writes an mdf.yaml carrying derived-from lineage.
$mdf dataset edit my_dataset_v1 --keyword "XRD"
Patch title, description, or keywords directly on the submission.
$mdf publish --update --submit
Anything beyond those three fields resubmits the manifest as a new version.
$mdf dataset versions my_dataset_v1
Confirm the history — every earlier DOI keeps resolving.

mdf — check on your submission

Check on your submission

Curation is a human step. The CLI tells you where you are in it.

$mdf status
With no argument: the last dataset you published from this machine.
$mdf status my_dataset_v1
Status badge, DOI, curator feedback, and the suggested next command.
$mdf status --watch my_dataset_v1
Polls every 10s until a terminal state, then prints the full record.
$mdf status --watch my_dataset_v1 --interval 30
Slow the poll down when the queue is long.
$mdf status --auth
Which service, which credential, and where the token is stored.

Let your coding agent draft the metadata

Writing good metadata is the slow part of publishing, and an agent sitting in your data directory has everything it needs to do the first draft — the README, the instrument logs, the column headers, the paper. One command installs the packaged skill; then you just ask.

mdf skill install --agent claude

/mdf-publish

--agent claude: ~/.claude/skills/
--agent codex: ~/.codex/skills/
--agent gemini: ~/.gemini/skills/
--agent all: all three at once

Add --project to install into ./.claude/skills/ instead, so the skill travels with the repository.

It cannot publish behind your back

The skill is built around two hard stops, and they are the reason it is safe to hand this job to a model at all. The agent gathers evidence, drafts, and validates on its own — but it never invents a value it cannot trace to a file, and it cannot cross either gate without an explicit yes from you in a new message.

Human gate 1
The manifest
The agent shows you the drafted mdf.yaml plus a field-by-field table of value → the evidence it came from, including the fields it left empty and any DOI it could not verify. Nothing is uploaded at this point.
Human gate 2
The submit
Only after a dry run passes does it ask a second time — and approving the manifest is explicitly not approval to submit. Silence is not approval either.

Scanning electron micrograph of dendritic silver microclusters covering a silicon grain. — Ouertani et al. · CC BY 4.0

Ag dendrites on Si · SEMmicrocluster growth

Full documentation lives with the code

The README is the reference: install paths, the complete command surface, the mdf.yaml schema, and the environment variables that let the CLI run unattended in CI.

Read the docs on GitHub Prefer the web form?

README
Install options, every command, environment variables for CI, and the manifest reference.
mdf --help
The CLI documents itself. Every command takes --help, and most list worked examples.
Issues
Something printed the wrong thing, or a flag you expected is missing. File it.