---
title: "Payloads Command: Streaming Large Attachments from the CLI"
canonical: "https://test.abhinandan.one/cli-overview/cli-payloads-command"
markdown_url: "https://test.abhinandan.one/cli-overview/cli-payloads-command.md"
publisher: "Primitive SDKs"
kind: "guide"
content_type: "reference"
category: "CLI"
parent: "cli-overview"
description: "The primitive payloads command uploads and downloads large, end-to-end-encrypted attachment objects from the terminal in bounded memory."
keywords: ["primitive payloads", "primitive payloads push", "primitive payloads pull", "Primitive Payloads CLI", "content-addressed attachment upload", "pushFile pushBytes pullFile"]
last_modified: "2026-08-21T18:22:43.359885+00:00"
published_at: "2026-08-11T18:54:57.371495+00:00"
sections:
  - {anchor: "when-to-reach-for-payloads-instead-of-an-inline-attachment", title: "When to reach for payloads instead of an inline attachment"}
  - {anchor: "what-you-need-before-you-start", title: "What you need before you start"}
  - {anchor: "step-install-and-authenticate-the-cli", title: "Install and authenticate the CLI"}
  - {anchor: "step-read-the-commands-own-flag-reference", title: "Read the command's own flag reference"}
  - {anchor: "keep-the-content-encryption-key", title: "Keep the content-encryption key"}
  - {anchor: "attaching-an-uploaded-object-to-an-email", title: "Attaching an uploaded object to an email"}
  - {anchor: "next-steps", title: "Next steps"}
---

> Documentation index: https://test.abhinandan.one/llms.txt

# 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](https://test.abhinandan.one/node-sdk-payloads.md) 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](https://test.abhinandan.one/node-sdk-payloads.md), 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

```bash
npm install -g primitive
primitive whoami
```

See [Authentication: login, signup, logout, whoami](https://test.abhinandan.one/cli-overview/cli-authentication.md) 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:

```bash
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](https://test.abhinandan.one/node-sdk-payloads.md) for the exact shape and [Sending, Replying, and Searching Email from the CLI](https://test.abhinandan.one/cli-overview/cli-email-commands.md) for the send-side flags.