{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/cli-overview/cli-payloads-command","markdown_url":"https://test.abhinandan.one/cli-overview/cli-payloads-command.md","article":{"id":"9460ed6c-ba88-4363-ab40-6d8f30ea5211","article_slug":"cli-payloads-command","parent_article_slug":"cli-overview","parent_article_title":"What is the Primitive CLI?","kind":"guide","published_at":"2026-08-11T18:54:57.371495+00:00","keywords":["primitive payloads","primitive payloads push","primitive payloads pull","Primitive Payloads CLI","content-addressed attachment upload","pushFile pushBytes pullFile"],"meta_description":"The primitive payloads command uploads and downloads large, end-to-end-encrypted attachment objects from the terminal in bounded memory.","og_image_url":null,"source_file_paths":[],"recording_id":null,"replayable":false,"task_name":"Payloads Command: Streaming Large Attachments from the CLI","category":"CLI","summary":null,"description":"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.","content_kind":"repo_page","content_markdown":"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](node-sdk-payloads) streaming client the Node SDK exposes as `pushFile`, `pushBytes`, and `pullFile`.\n\n<Note>\n\nThis 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](node-sdk-payloads), which the CLI mirrors.\n\n</Note>\n\n## When to reach for payloads instead of an inline attachment\n\nSend 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.\n\n## What you need before you start\n\n<Steps>\n\n<Step title=\"Install and authenticate the CLI\">\n\n```bash\nnpm install -g primitive\nprimitive whoami\n```\n\nSee [Authentication: login, signup, logout, whoami](cli-authentication) if `whoami` fails.\n\n</Step>\n\n<Step title=\"Read the command's own flag reference\">\n\nThe 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:\n\n```bash\nprimitive payloads --help\n```\n\nPer-command help carries enough detail to compose any operation without leaving the terminal.\n\n</Step>\n\n</Steps>\n\n## Keep the content-encryption key\n\nPayload 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.\n\n<Warning>\n\nPrimitive cannot recover a lost CEK. Without it the stored bytes stay encrypted and unreadable, so store the CEK alongside the root, never separately.\n\n</Warning>\n\n## Attaching an uploaded object to an email\n\nAn 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](node-sdk-payloads) for the exact shape and [Sending, Replying, and Searching Email from the CLI](cli-email-commands) for the send-side flags.\n\n## Next steps\n\n<CardGroup cols={2}>\n\n<Card title=\"Primitive Payloads: Streaming Large Attachments\" href=\"node-sdk-payloads\">\n\nThe content-addressed, end-to-end-encrypted object model the CLI command wraps.\n\n</Card>\n\n<Card title=\"Sending, Replying, and Searching Email from the CLI\" href=\"cli-email-commands\">\n\nSend and reply from the terminal, including attachment flags.\n\n</Card>\n\n<Card title=\"x402 Payments from the CLI\" href=\"cli-payments\">\n\nAnother CLI command group built on the same generated API surface.\n\n</Card>\n\n<Card title=\"What is the Primitive CLI?\" href=\"cli-overview\">\n\nHow the CLI's command groups and generated operations fit together.\n\n</Card>\n\n</CardGroup>","canonical_base_url":"https://test.abhinandan.one","seo_indexing_enabled":true,"last_modified":"2026-08-21T18:22:43.359885+00:00","video_url":null,"voiceover_url":null,"tools_used":[],"demonstrated_by":[],"steps":[],"related_links":[],"intro":null,"prerequisites":[],"verification":[],"troubleshooting":[],"suggest_edit_url":null,"raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+Payloads+Command%3A+Streaming+Large+Attachments+from+the+CLI&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fcli-payloads-command","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}