@cephla/share

CLI for downloading data shared via Cephla magic-link URLs.

Install

Once published to npm:

npx @cephla/share download <magic-link-url>

For local development inside this monorepo:

pnpm --filter @cephla/share build
node apps/cli/dist/bin.js download <magic-link-url>

Usage

cephla-share download [options] <share-url> [dest]

Arguments:
  share-url                 magic-link URL from the share email
  dest                      destination directory (default: "./cephla-download")

Options:
  -a, --acquisition <name>  limit to specific acquisition (repeatable)
  -c, --concurrency <n>     parallel file downloads (default: 8)
  -h, --help                display help for command

The CLI:

1. Parses the token + viewer base URL from the share link.
2. Calls POST /api/shares/:token/sessions to start a download session and receive a manifest with short-lived signed URLs.
3. Downloads files in parallel (default: 8 concurrent), preserving the relative directory structure under each acquisition.
4. Persists progress to <dest>/.cephla-download-state.json after every completed file. Re-running the same command resumes — files already in the state file are skipped.
5. Calls the per-acquisition and per-session completion endpoints so the dashboard's audit log records what was downloaded.

Resume behavior

Re-running with the same destination skips files already marked complete in .cephla-download-state.json. The signed URLs in the original manifest may have expired (4-hour TTL); the CLI requests a fresh manifest each run.

To force a full re-download, delete the state file or pick a different destination.

Limitations

• No partial-file resume: a file interrupted mid-download is restarted from the beginning on the next run.
• No retry on transient HTTP errors. If a file fails, re-run the command — completed files are skipped.