Skip to content

dexr-outpost

DEXR Outpost — DEXR Party Interface.

Exit codes: 0 success, 1 generic, 2 usage, 3 config/permission, 4 DEXR-auth, 5 network, 6 crypto, 7 payload-too-large.

Usage:

$ dexr-outpost [OPTIONS] COMMAND [ARGS]...

Options:

  • --env-file PATH: Path to an env file to load before subcommand execution (CLI-08).
  • --json: Emit {ok, data, error} JSON envelope on stdout; suppress chrome.
  • -q, --quiet: Suppress progress + success one-liner; only errors go to stderr.
  • --version: Print DEXR Outpost version + commit hash and exit.
  • --install-completion [SHELL]: Print shell completion snippet + recommended rc-file path (does NOT modify rc files).
  • --show-completion [SHELL]: Print shell completion snippet only (no path hint).
  • --help: Show this message and exit.

Commands:

  • put: Upload + encrypt a payload (writer role).
  • get: Download + decrypt a payload (reader role).
  • env: Print eval-able env exports for the...
  • init: Guided wizard: collect DEXR_* keys,...
  • config: Manage env-file config.
  • history: List transfer history (default) or prune...

dexr-outpost put

Upload + encrypt a payload (writer role).

Secrets are NEVER accepted as CLI flags. Keys flow only via env vars / config file (loaded by the top-level _main callback's load_env() call before this function executes).

Every attempt — success or failure — writes one history row.

Note: NO re-attempt loop, NO --redo flag. DEXR PUT idempotency under repeat sample_id is unconfirmed; auto-redo could create duplicate server-side records. Caller (CI / human) decides whether to re-invoke after failure.

Usage:

$ dexr-outpost put [OPTIONS] FILE

Arguments:

  • FILE: [required]

Options:

  • --reader TEXT: [required]
  • --sample TEXT: [required]
  • --stage TEXT
  • --workflow TEXT
  • --json: Emit D-04 envelope {ok, data, error} on stdout; equivalent to the top-level dexr-outpost --json put ... calling convention.
  • --help: Show this message and exit.

dexr-outpost get

Download + decrypt a payload (reader role).

Usage:

$ dexr-outpost get [OPTIONS] SAMPLE_ID

Arguments:

  • SAMPLE_ID: [required]

Options:

  • --stage TEXT
  • --workflow TEXT
  • -o, --output PATH: Destination path for decrypted bytes. Use - for stdout. Default: <sample_id>.bin.
  • --mark-complete / --no-mark-complete: Mark the transfer complete on DEXR after fetch. Default --no-mark-complete — 30-day TTL covers the common case. [default: no-mark-complete]
  • --json: Emit D-04 envelope {ok, data, error} on stdout; equivalent to dexr-outpost --json get ....
  • --hook TEXT: Override DEXR_GET_HOOK for this invocation.
  • --no-retry: Cap hook at a single attempt.
  • --force: Overwrite output file if it exists.
  • -v, --verbose: Echo captured hook output to stderr on failure.
  • -q, --quiet: Suppress all stderr progress output.
  • --help: Show this message and exit.

dexr-outpost env

Print eval-able env exports for the current DEXR_* os.environ keys.

Honors global --json — emits {ok: true, data: {shell, lines}} envelope when ctx.obj.json_mode is True; bare export lines otherwise.

Usage:

$ dexr-outpost env [OPTIONS]

Options:

  • --shell TEXT: Override shell auto-detection: bash | zsh | fish | powershell.
  • --json: Emit D-04 envelope on stdout (overrides bare-export lines). Equivalent to dexr-outpost --json env ....
  • --help: Show this message and exit.

dexr-outpost init

Guided wizard: collect DEXR_* keys, validate, and write config atomically.

Usage:

$ dexr-outpost init [OPTIONS]

Options:

  • --env-file PATH: Populate DEXR_* values from a dotenv-format answer file without interactive prompts (INST-05, D-05).
  • -y, --yes: Skip the final confirmation prompt.
  • --json: Emit D-04 JSON envelope on stdout.
  • --help: Show this message and exit.

dexr-outpost config

Manage env-file config.

Usage:

$ dexr-outpost config [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • get: Print the value of key from the env file...
  • set: Set key=value in the env file via atomic...
  • list: List all keyvalue entries from the env...
  • unset: Remove the first occurrence of key from...
  • verify: Probe DEXR with current env keys; report...
  • purge: Remove config file + history DB + logs...

dexr-outpost config get

Print the value of key from the env file (dexr-outpost config get).

Usage:

$ dexr-outpost config get [OPTIONS] KEY

Arguments:

  • KEY: [required]

Options:

  • --json: Emit D-04 envelope on stdout.
  • --help: Show this message and exit.

dexr-outpost config set

Set key=value in the env file via atomic write (dexr-outpost config set).

Usage:

$ dexr-outpost config set [OPTIONS] KEY VALUE

Arguments:

  • KEY: [required]
  • VALUE: [required]

Options:

  • --json: Emit D-04 envelope on stdout (silent on success otherwise).
  • --help: Show this message and exit.

dexr-outpost config list

List all keyvalue entries from the env file with secret redaction by default.

Usage:

$ dexr-outpost config list [OPTIONS]

Options:

  • --show-secrets: Reveal secret values; default redacts *KEY*/*SECRET*/*PRIVATE* to ***.
  • --json: Emit D-04 envelope on stdout.
  • --help: Show this message and exit.

dexr-outpost config unset

Remove the first occurrence of key from the env file (config unset).

Usage:

$ dexr-outpost config unset [OPTIONS] KEY

Arguments:

  • KEY: [required]

Options:

  • --json: Emit D-04 envelope on stdout.
  • --help: Show this message and exit.

dexr-outpost config verify

Probe DEXR with current env keys; report per-key OK/FAIL.

Reuses dexr-outpost.auth.verify_*_key — same code path Phase 3 GUI rotation view will call (so a passing CLI verify is the GUI's pre-save gate).

verify_private_key requires a SealedBox-encrypted probe blob (a write/encrypt round-trip from a known-good writer); generating one client-side is non-trivial and out of scope for v1. Marked "skipped" with reason; Phase 3 GUI rotation supplies the probe.

Usage:

$ dexr-outpost config verify [OPTIONS]

Options:

  • --json: Emit D-04 envelope on stdout.
  • --help: Show this message and exit.

dexr-outpost config purge

Remove config file + history DB + logs together (opt-in purge).

Default uninstall LEAVES these files. This command is the only thing that deletes them. Supports --yes, PURGE_CONFIG=1 env var, or interactive confirmation. Idempotent: missing directories are skipped silently.

Paths removed: config_path().parent (the whole config dir), data_dir(), log_dir(). A dry-run preview of ABSOLUTE resolved paths is always shown before deletion.

Usage:

$ dexr-outpost config purge [OPTIONS]

Options:

  • -y, --yes: Skip confirmation prompt. Also triggered by PURGE_CONFIG=1 env var (D-07).
  • --json: Emit D-04 envelope on stdout.
  • --help: Show this message and exit.

dexr-outpost history

List transfer history (default) or prune to reclaim space.

Usage:

$ dexr-outpost history [OPTIONS] COMMAND [ARGS]...

Options:

  • --since TEXT: Lower bound on ts_started. Accepts ISO 8601 (YYYY-MM-DD[THH:MM:SS]) or relative shorthand (Nd, Nh, Nw, Nm — e.g. 7d). Default: 30 days ago.
  • --until TEXT: Upper bound on ts_started. Same format as --since. Default: no upper bound.
  • --direction TEXT: Filter by direction: put | get.
  • --columns TEXT: Comma-separated columns from the 13-name allow-list (transfer_uuid, ts_started, ts_completed, direction, sample_id, reader_id, stage_id, workflow_id, byte_count, status, error_class, error_message, client_version).
  • --show-all: Render all 13 user-facing columns (default is 5-col compact).
  • --format TEXT: Row rendering when --json is OFF: table | json | csv | tsv. [default: table]
  • --json: Emit D-04 envelope (overrides --format).
  • --help: Show this message and exit.

Commands:

  • prune: Hard-delete history rows older than...

dexr-outpost history prune

Hard-delete history rows older than --days N.

Default-deny: --days is REQUIRED. Without --yes, deletion is gated by an interactive `` confirm prompt on stderr;--dry-runpreviews the count without deletion.--jsonmode is non-interactive — no prompt fires under--json``.

Usage:

$ dexr-outpost history prune [OPTIONS]

Options:

  • --days INTEGER: Hard-delete rows older than this many days. REQUIRED (default-deny). [required]
  • --dry-run: Show what would be deleted without actually deleting.
  • -y, --yes: Skip confirmation prompt.
  • --json: Emit D-04 envelope on stdout (non-interactive).
  • --help: Show this message and exit.

Exit Codes

Code Label Trigger
0 OK Command completed successfully.
1 GENERIC Unexpected error not covered by a more specific code. Label shown as INTERNAL.
2 USAGE Argument or option parse failure (Typer raises directly).
3 CONFIG Config file permission denied (ConfigPermissionError).
4 AUTH DEXR authentication failure (DEXRAuthError, KeyValidationFailed).
5 NETWORK Network or server error (DEXRNetworkError, DEXRServerError).
6 CRYPTO NaCl decrypt/encrypt failure (nacl.exceptions.CryptoError; or ValueError whose message contains "decrypt").
7 PAYLOAD Payload too large: 50 MB plaintext abuse guard or 400 KB total wire-size DEXR service ceiling (PayloadTooLargeError).
8 HOOK_FAILURE Retrieval OK, but the post-get hook failed or timed out (--hook / DEXR_GET_HOOK). The payload is on disk; only the hook failed. A user Ctrl-C is 130, not this code.

Hooks

A --hook (or the DEXR_GET_HOOK config value) runs an external command after a successful get. The hook is a side-effect step: it receives the decrypted payload two ways — piped to its stdin (Unix-filter style) and as a 0600 file at DEXR_HOOK_PAYLOAD_PATH — but it cannot change what get outputs. The hook's own stdout/stderr are captured for logging (and shown via -v only on failure), never forwarded to the terminal, so get -o - stays a clean payload stream.

Rule of thumb: use --hook for side effects (upload, index, notify); use a shell pipe for transforms that should reach stdout.

Goal Command
Filtered data → stdout, don't persist the payload dexr-outpost get 12345678 -o - \| jq .output
Persist payload and send filtered data → stdout dexr-outpost get 12345678 -o - \| tee 12345678.json \| jq .output
Filter into a file as a side effect dexr-outpost get 12345678 -o 12345678.json --hook 'sh -c "jq .output > filtered.json"'
Hook reads the payload by path dexr-outpost get 12345678 --hook 'sh -c "process \"$DEXR_HOOK_PAYLOAD_PATH\""'

Payload-rewriting / veto hooks (a hook whose stdout replaces the payload) are a deferred capability, intentionally out of scope so get semantics stay predictable.

For the full hook-author contract — DEXR_HOOK_* env vars, retry model, quoting rules, and cookbook examples — see Hook Author Reference.