CLI

The hephaes CLI is the package’s workspace-backed interface for local authoring and conversion. It now supports the full draft-first workflow:

register or inspect a source asset
create a draft conversion spec
preview the draft
confirm the draft
save the confirmed draft as a reusable config
run later conversions from that saved config

The CLI is built as a thin adapter over hephaes.workspace.Workspace, so the same package services can be reused later by a backend or another integration.

Usage

After installing the package, the hephaes command is available:


hephaes --version
hephaes --help

You can also run it as a module:


python -m hephaes --version
python -m hephaes --help

Workspace Basics

Initialize a workspace:


hephaes init
hephaes init /path/to/workspace
hephaes init --exist-ok

Most workspace commands accept --workspace /path/to/workspace. When omitted, the CLI discovers the workspace by walking up from the current directory.

Quick Start

Recommended human path:


hephaes init ./demo
hephaes add --workspace ./demo ./logs/run_001.mcap
hephaes drafts wizard --workspace ./demo <asset-id>

Recommended scriptable path:


hephaes init ./demo
hephaes add --workspace ./demo ./logs/run_001.mcap
hephaes drafts create --workspace ./demo <asset-id> --topic /camera --trigger-topic /camera
hephaes drafts preview --workspace ./demo <draft-id> --sample-n 5
hephaes drafts confirm --workspace ./demo <draft-id> --yes
hephaes drafts save-config --workspace ./demo <draft-id> --name camera-demo
hephaes convert --workspace ./demo <asset-id> --config camera-demo

Asset Commands


hephaes add data/run_001.mcap data/run_002.mcap
hephaes add --workspace /path/to/workspace data/

Directories are walked recursively for supported asset file types. Registered assets remain in place on disk; the workspace stores and reuses the canonical file path instead of copying raw logs into .hephaes.

Duplicate handling:


hephaes add data/run_001.mcap --on-duplicate error
hephaes add data/run_001.mcap --on-duplicate skip
hephaes add data/run_001.mcap --on-duplicate refresh

List registered assets:


hephaes ls assets
hephaes ls assets --tag driving

Index assets to populate workspace metadata:


hephaes index --all
hephaes index <asset-id>
hephaes index data/run_001.mcap
hephaes index --all --max-workers 4

Index output is line-delimited JSON with asset id, indexing status, file paths, message count, topic count, duration, and sensor types.

Inspecting Assets

Use inspect for standalone inspection outside the draft workflow:


hephaes inspect <asset-id-or-path>
hephaes inspect data/run_001.mcap --topic /camera --sample-n 5

Supported inspection flags:

Flag	Default	Description
`--topic`	all topics	Topic filter. Repeat for multiple topics.
`--sample-n`	`8`	Maximum sampled messages per topic.
`--max-depth`	`4`	Maximum traversal depth for nested payloads.
`--max-sequence-items`	`4`	Maximum sequence items to inspect per message.
`--on-failure`	`warn`	Decode failure policy: `skip`, `warn`, or `fail`.

The command accepts a registered asset id, a registered path, or a direct local file path.

Draft Authoring

The primary CLI flow now lives under drafts.

Interactive Wizard

The default human authoring path is the wizard:


hephaes drafts wizard --workspace ./demo <asset-id>
hephaes drafts wizard --workspace ./demo --draft <draft-id>

The wizard can:

start from a registered asset
resume from an existing draft
prompt for inspection settings and draft settings
preview and confirm drafts
save a confirmed draft as a reusable config
discard a draft while preserving history

Scriptable Commands

Create a draft from a source asset:


hephaes drafts create --workspace ./demo <asset-id>
hephaes drafts create --workspace ./demo <asset-id> \
  --topic /camera \
  --trigger-topic /camera \
  --output-format parquet \
  --include-preview

Useful drafts create flags:

Flag	Default	Description
`--label`	none	Optional revision label.
`--topic`	all topics	Topics to inspect and draft from. Repeat for multiple topics.
`--sample-n`	`8`	Inspection sample count.
`--trigger-topic`	auto	Explicit trigger topic for the draft request.
`--join-topic`	none	Explicit join topic. Repeat for multiple topics.
`--schema-name`	`draft_conversion`	Drafted schema name.
`--schema-version`	`1`	Drafted schema version.
`--output-format`	`tfrecord`	Drafted output format: `tfrecord` or `parquet`.
`--output-compression`	`none`	Drafted output compression.
`--max-features-per-topic`	`2`	Maximum inferred features per topic.
`--label-feature`	none	Optional primary label feature name.
`--include-preview`	disabled	Generate an initial preview during draft creation.
`--preview-rows`	`5`	Preview row count when `--include-preview` is enabled.

List and inspect drafts:


hephaes drafts ls --workspace ./demo
hephaes drafts ls --workspace ./demo --status confirmed
hephaes drafts ls --workspace ./demo --asset <asset-id>
hephaes drafts show --workspace ./demo <draft-id>

Update a draft by appending a new immutable revision:


hephaes drafts update --workspace ./demo <draft-id> --spec-document edited-spec.yaml
hephaes drafts update --workspace ./demo <draft-id> --spec-document edited-spec.yaml --label "Adjusted joins"

Preview the current draft revision:


hephaes drafts preview --workspace ./demo <draft-id>
hephaes drafts preview --workspace ./demo <draft-id> --sample-n 10
hephaes drafts preview --workspace ./demo <draft-id> --type-hint /camera=sensor_msgs/msg/Image

Confirm or discard a draft:


hephaes drafts confirm --workspace ./demo <draft-id>
hephaes drafts confirm --workspace ./demo <draft-id> --yes
hephaes drafts discard --workspace ./demo <draft-id> --yes

Save a confirmed draft as a reusable config:


hephaes drafts save-config --workspace ./demo <draft-id> --name camera-demo
hephaes drafts save-config --workspace ./demo <draft-id> --name camera-demo --description "Front camera TFRecord export"

Output Shape

The drafts commands intentionally mix machine-readable and human-readable output:

drafts create, drafts show, drafts update, drafts preview, drafts confirm, drafts discard, and drafts save-config print JSON
drafts ls prints tab-separated summaries for quick terminal use

Saved Configs

The configs group is still available for direct saved-config management:


hephaes configs ls
hephaes configs show <config-id-or-name>
hephaes configs update <config-id-or-name> spec.yaml
hephaes configs duplicate <config-id-or-name> camera-demo-v2
hephaes configs revisions <config-id-or-name>

You can still import a spec document directly:


hephaes configs save camera-demo spec.yaml

For new authoring work, the recommended path is drafts ... or drafts wizard, not direct configs save.

Running Conversions

Run a conversion from either a saved config or an explicit spec document:


hephaes convert --workspace ./demo <asset-id> --config camera-demo
hephaes convert --workspace ./demo <asset-id> --spec-document spec.yaml
hephaes convert --workspace ./demo <asset-id> --config camera-demo --output-dir output/
hephaes convert --workspace ./demo <asset-id> --config camera-demo --max-workers 4

Exactly one of --config or --spec-document must be provided. Outputs are registered in the workspace automatically.

Runs, Jobs, And Outputs

Inspect durable workflow records after conversions:


hephaes jobs ls
hephaes jobs show <job-id>
hephaes runs ls
hephaes runs show <run-id>
hephaes outputs ls
hephaes outputs show <output-id>

These commands let other tooling inspect conversion history without reopening raw files.

CLI