{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/cli-overview/cli-email-commands","markdown_url":"https://test.abhinandan.one/cli-overview/cli-email-commands.md","article":{"id":"518dad17-a526-4550-9612-dae77c1ae6d5","article_slug":"cli-email-commands","parent_article_slug":"cli-overview","parent_article_title":"What is the Primitive CLI?","kind":"guide","published_at":"2026-08-11T18:54:52.309658+00:00","keywords":["primitive send","primitive reply","primitive emails latest","primitive search","primitive semantic-search","primitive emails watch"],"meta_description":"Send mail with primitive send --wait, reply with primitive reply --id, and run keyword or semantic search from the terminal.","og_image_url":null,"source_file_paths":["cli-node/src/oclif/commands/inbox-setup.ts","cli-node/src/oclif/commands/inbox-status.ts"],"recording_id":null,"replayable":false,"task_name":"Sending, Replying, and Searching Email from the CLI","category":"CLI","summary":null,"description":"Send, reply to, and search email straight from the terminal with the primitive CLI, using the same wait-mode delivery semantics and search model as the SDKs.","content_kind":"repo_page","content_markdown":"Use these commands when you want to send, reply to, or inspect mail without leaving the terminal, for one-off testing, CI smoke checks, or scripting an agent workflow around the [CLI](cli-overview). All of them wrap the same high-level `send`/`reply`/`forward` flow documented in [Inbound and Outbound Email Model](email-model); the CLI just gives you flags instead of SDK calls.\n\n<Note>\n\nEvery command below needs an authenticated CLI session or an API key. See [Authentication: login, signup, logout, whoami](cli-authentication) if you haven't run `primitive login` yet.\n\n</Note>\n\n## Send a new email\n\n`primitive send` posts a new outbound message; `--to` and `--body` are enough for a minimal send.\n\n```bash\nprimitive send --to alice@example.com --body \"Hello!\"\n```\n\nRun `primitive send --help` for the full flag list in your installed version. Add `--wait` to hold the command open until the first downstream SMTP delivery outcome instead of returning as soon as Primitive accepts the message, the same [wait mode](email-model) the SDKs expose as `wait: true`:\n\n<Steps>\n\n<Step title=\"Send with wait mode\">\n\n```bash\nprimitive send --to alice@example.com --body \"Hello!\" --wait\n```\n\n</Step>\n\n<Step title=\"Read the delivery status\">\n\nThe JSON response includes a `delivery_status` field: `delivered`, `bounced`, `deferred`, or `wait_timeout`. Treat `wait_timeout` as \"outcome unknown\", the send may still complete after the command returns.\n\n</Step>\n\n</Steps>\n\n\n\n## Reply to an inbound email\n\n`primitive reply --id <inbound-email-id> --body \"...\"` replies to a specific inbound message. Recipients, subject (`Re: ...`), and threading headers are derived server-side from the inbound row, matching every SDK's `reply()` behavior. A custom subject is not supported, because Gmail's Conversation View needs a normalized-subject match in addition to a References match, so overriding the subject silently breaks threading for half the recipient population.\n\n```bash\nprimitive reply --id <inbound-email-id> --body \"Thanks for reaching out.\"\n```\n\nAttach a file with `--attachment`:\n\n```bash\nprimitive reply --id <inbound-email-id> --body \"See attached\" --attachment ./report.pdf\n```\n\nThe interactive REPL form, `primitive chat reply \"...\" --attachment ./report.pdf`, works the same way inside a chat session. See [Memories and Chat Commands](cli-memories-and-chat).\n\n<Warning>\n\nIf the inbound row isn't in a repliable state (rejected at ingestion, content discarded, or no recipient recorded), the API returns `inbound_not_repliable` (HTTP 422) and the CLI exits non-zero. Retrying will not help; the original inbound message has to be resent. A missing `Message-Id` does not block the reply, it only omits the threading headers.\n\n</Warning>\n\n## Forward an inbound email\n\nThe CLI has no dedicated forward command. Forwarding in the SDKs is a `send` with a generated \"Forwarded message\" body, so from the terminal you compose the same thing with `primitive send`, or drive the API directly through the generic operation shortcut described in [Direct API Access and Generic Commands](cli-generic-api-access). Run `primitive list-operations` to see every operation available in your installed version.\n\n## List and inspect emails\n\n`primitive emails list` lists inbound mail; `primitive emails get --id <inbound-email-id>` fetches one. `primitive sent list` lists outbound mail the same way.\n\n```bash\nprimitive emails list\nprimitive emails get --id <inbound-email-id>\nprimitive sent list\n```\n\n### View the latest messages\n\n```bash\nprimitive emails latest --limit 5\n```\n\n### Poll an inbox\n\nRun `primitive emails --help` for the polling and watch subcommands available in your installed version, along with their poll-interval and filter flags.\n\n## Search email\n\nTwo search modes are available, matching the generated `search` and `semantic-search` operations:\n\n- **`primitive search`**, keyword search across received and sent mail.\n- **`primitive semantic-search`**, ranked semantic/hybrid/keyword search with match excerpts and a score breakdown. Requires the Pro plan and the `semantic_search_enabled` entitlement; without them the API returns a 403.\n\n```bash\nprimitive search --help\nprimitive semantic-search --help\n```\n\n<Tip>\n\nSemantic search concepts (modes, corpus selection, scoring) are shared across every SDK and the CLI, and each ranked row carries matched fields, a match-centered excerpt, and an additive score breakdown. See [Semantic Search](go-semantic-search) for the shared parameter reference.\n\n</Tip>\n\n## Verify your inbox is set up to receive mail\n\nBefore you can reply to anything, inbound mail has to actually reach an endpoint or Function. `primitive inbox-status` reports readiness without side effects: it fetches the server-owned inbox status, shows the first usable receive address on a Primitive-managed domain, and tells you whether inbound mail is stored-only or actively processed by a route.\n\n```bash\nprimitive inbox-status\n```\n\nOutput includes:\n\n- **Readiness**: whether the account overall is `ready`, plus separate `receiving_ready` / `processing_ready` flags.\n- **Receive address**: the first receiving-ready, active, Primitive-managed domain, formatted as `inbox@<domain>`.\n- **Mode**: `actively_processed` (a route is bound), `stored_only` (mail arrives but nothing processes it), or `not_receiving`.\n- **Domains**: per-domain status, receive/process readiness, and route count.\n\nRun `primitive inbox-setup` for the same readiness data plus copy-pasteable next steps, the exact `primitive functions init`, `deploy --wait`, and `functions test --id <function-id> --wait --show-sends` commands to scaffold and wire up a processing Function when none is bound yet:\n\n```bash\nprimitive inbox-setup\n```\n\n<Note>\n\n`inbox-setup` never deploys anything itself; it only prints the commands. Follow the printed scaffold steps (or see [Primitive Functions: Deploy, Route, and Manage](cli-functions)) to actually wire up a processing route.\n\n</Note>\n\n## Next steps\n\n<CardGroup cols={2}>\n\n<Card title=\"Inbound and Outbound Email Model\" href=\"email-model\">\n\nUnderstand the normalized email object and wait-mode delivery statuses these commands rely on.\n\n</Card>\n\n<Card title=\"Managing Domains and Recipient Routes\" href=\"cli-domains-and-routes\">\n\nConfigure inbound DNS and recipient routing rules so mail actually reaches an endpoint.\n\n</Card>\n\n<Card title=\"Primitive Functions: Deploy, Route, and Manage\" href=\"cli-functions\">\n\nScaffold and deploy the Function that inbox-setup points you toward.\n\n</Card>\n\n<Card title=\"Direct API Access and Generic Commands\" href=\"cli-generic-api-access\">\n\nCall any generated operation (like forward-email) directly when a task command doesn't exist yet.\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":"https://github.com/abhi-browzer/primitive-sdks/edit/main/cli-node/src/oclif/commands/inbox-setup.ts","raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+Sending%2C+Replying%2C+and+Searching+Email+from+the+CLI&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fcli-email-commands","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}