healthmd export

Export either validated platform-native raw data or files produced by the Health.md mobile app.

Synopsis

healthmd export DATE (--raw [--output <PATH>] | --destination <ABSOLUTE_DIRECTORY>) [OPTIONS]

Choose exactly one date selection and one mode. Running healthmd export without a complete request returns local guidance and does not contact a phone.

Modes

Raw artifact

healthmd export --last 7 --raw --output week.json

--raw returns the source platform’s validated native artifact. Omit --output to stream it to stdout. iPhone uses canonical Apple Health JSON. Android preserves provider-native Health Connect JSON or NDJSON.

Generated files

healthmd export --yesterday --destination /absolute/path/to/vault

The mobile app’s production exporters create the files. The destination must already exist, be absolute, and not be a symbolic link. The CLI validates and binds it before transfer.

Options

Option	Description	Default
--raw	Select raw-artifact mode.	Off
--output <PATH>	Atomically write a raw artifact. Valid only with --raw; omit to use stdout.	stdout
--destination <DIRECTORY>	Select generated-file mode and write under this existing absolute directory.	—
--use-device-settings	Use saved export settings from the paired phone. Alias: --use-iphone-settings.	Off
--profile <PROFILE_ID>	Resolve a saved export profile on the phone. Conflicts with device settings and selectors.	—
--provider <PROVIDER>	Select the Android raw provider.	health_connect
--raw-format <json|ndjson>	Select the physical Android raw format.	ndjson
--metric <METRIC_ID>	Select one canonical metric. Repeatable.	—
--category <CATEGORY>	Select one canonical category. Repeatable.	—
--all-metrics	Select every supported metric. Conflicts with metric and category selectors.	Off
--detail <summary|lossless>	Select summary values or source-record detail.	summary
--object <ALIAS>	Select a canonical object alias. Repeatable.	—
--field <JSON_POINTER>	Retain an RFC 6901 JSON Pointer. Repeatable.	—
--source <SOURCE_ID>	Select a canonical source. Repeatable.	—
--allow-partial	Accept a validated partial result with a successful exit status.	Off
--timeout <SECONDS>	Wait for preparation and transfer. Range: 5–900.	300
--wake-timeout <SECONDS>	Wait for an unavailable paired phone before starting.	120
--no-wake	Skip the best-effort notification nudge.	Off

This command also accepts all date and global options.

Examples

# One complete local-calendar day
healthmd export --yesterday --raw --output yesterday.json

# Exact inclusive range streamed to stdout
healthmd export --from 2026-07-01 --to 2026-07-07 --raw

# Large Android export as NDJSON
healthmd export --all --raw --provider health_connect \
  --raw-format ndjson --output health-connect.ndjson

# Files produced with a saved mobile profile
healthmd export --last 7 \
  --profile 11111111-2222-4333-8444-555555555555 \
  --destination /absolute/path/to/vault

Platform behavior

Source	Raw artifact	Generated files
iPhone	Canonical Apple Health artifact	Supported
Android	Provider-native Health Connect artifact	Supported, up to 4,096 files per job

Use healthmd extract for a selected canonical iPhone projection. Android raw data is not converted into Apple Health-shaped output.

Interruption and partial results

Timeout, Ctrl-C, process exit, network loss, or exhausted mobile background time does not cancel a durable job. Preserve the returned job UUID, inspect it with healthmd status --job, and use healthmd resume.

A validated partial result exits nonzero unless --allow-partial is present.