Verified · 8/11/2026

Payloads Command: Streaming Large Attachments from the CLI

Upload and download large, end-to-end-encrypted attachment objects from the terminal with the primitive payloads command, the CLI counterpart to the Node SDK's Primitive Payloads streaming client.

Use primitive payloads to move an attachment that is too large to send inline from the terminal, without writing application code. It wraps the same Primitive Payloads streaming client the Node SDK exposes as pushFile, pushBytes, and pullFile.

Note

This page covers the terminal entry point only. The object model itself, content-addressed objects, the client-held content-encryption key (CEK), bounded-memory streaming, and the payload reference you attach to an email, is owned by Primitive Payloads: Streaming Large Attachments, which the CLI mirrors.

When to reach for payloads instead of an inline attachment#

Send attachments inline (base64 content on send/reply/forward) whenever they fit under the inline size cap; use Primitive Payloads only for objects above it. In the Node SDK the inline threshold is 25 MiB by default (DEFAULT_INLINE_ATTACHMENT_MAX), above which the SDK uploads the object and delivers it by reference instead.

What you need before you start#

1
Install and authenticate the CLI#
```
npm install -g primitive
primitive whoami
```
See Authentication: login, signup, logout, whoami if whoami fails.
2
Read the command's own flag reference#
The payloads command group mirrors the Node SDK's streaming client one-for-one, so its flags are best read from the installed binary rather than copied from prose:
```
primitive payloads --help
```
Per-command help carries enough detail to compose any operation without leaving the terminal.

Keep the content-encryption key#

Payload objects are end-to-end encrypted with a key the client holds: the CEK never reaches Primitive. An upload gives you two values that travel together, the object's Merkle root (a 64-char lowercase-hex content address) and the hex-encoded CEK, and a download needs both.

Warning

Primitive cannot recover a lost CEK. Without it the stored bytes stay encrypted and unreadable, so store the CEK alongside the root, never separately.

Attaching an uploaded object to an email#

An uploaded object is delivered as an attachment by reference rather than by re-uploading bytes. The reference carries the object's root, a filename, an optional contentType, and the cek the recipient needs; see Primitive Payloads: Streaming Large Attachments for the exact shape and Sending, Replying, and Searching Email from the CLI for the send-side flags.