{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/cli-overview","markdown_url":"https://test.abhinandan.one/cli-overview.md","article":{"id":"1747ce38-db8b-48e5-8156-24044bd08b08","article_slug":"cli-overview","parent_article_slug":null,"parent_article_title":null,"kind":"concept","published_at":"2026-08-11T18:54:50.833895+00:00","keywords":["primitive CLI","npm install -g primitive","oclif command surface","primitive api-command","cli-node","prim alias"],"meta_description":"The primitive CLI is an oclif terminal client, published as primitive/prim/primcli, that wraps @primitivedotdev/sdk and api-core for email, payments, and functions.","og_image_url":null,"source_file_paths":["cli-node/README.md"],"recording_id":null,"replayable":false,"task_name":"What is the Primitive CLI?","category":"CLI","summary":null,"description":"The primitive CLI is an oclif-based terminal client that wraps the Node SDK and api-core to send mail, deploy Primitive Functions, manage payments, and administer your account without writing code.","content_kind":"repo_page","content_markdown":"The `primitive` CLI is a terminal client, built on the [oclif](https://oclif.io) framework, that exposes Primitive's email, payments, functions, and account operations as one-shot shell commands instead of SDK calls.\n\nInstall it separately from the Node SDK:\n\n```bash\nnpm install -g primitive\nprimitive whoami\n# `prim` is a short alias for the same binary\nprim whoami\n```\n\nInstall it as `primitive`. The same build is also published as [`primcli`](https://www.npmjs.com/package/primcli) and the legacy scoped [`@primitivedotdev/cli`](https://www.npmjs.com/package/@primitivedotdev/cli), locked to the same version, for environments that already depend on those names.\n\nNo-install form:\n\n```bash\nnpx primitive@latest <command>\n```\n\n<Note>\n\n`@primitivedotdev/sdk` no longer ships a `primitive` bin. If you're embedding Primitive in application code, install the SDK directly; see [Node.js SDK Quickstart](node-sdk-quickstart). The CLI is for your shell and CI, not for import into a handler.\n\n</Note>\n\n## How it relates to the Node SDK and api-core\n\nThe CLI wraps the [Node.js SDK](node-sdk-overview) (`@primitivedotdev/sdk`) runtime client with one-shot commands. Internally, both the CLI and the Node SDK bundle the workspace-internal [`@primitivedotdev/api-core`](api-core-overview) package inline, so the generated HTTP client, operation manifest, and `PrimitiveApiClient` error handling are shared code, not reimplementations.\n\n```mermaid\nflowchart LR\n  A[openapi/primitive-api.yaml] --> B[api-core: generated client, operation manifest, PrimitiveApiClient]\n  B --> C[\"@primitivedotdev/sdk (Node SDK)\"]\n  B --> D[\"primitive (CLI)\"]\n  C -.->|imported by| D\n```\n\nFor in-handler use, calling Primitive from inside a Primitive Function, import `createPrimitiveClient` from `@primitivedotdev/sdk/api` directly. The CLI is for operator and deploy workflows: signing in, sending test mail, deploying functions, managing secrets, from your terminal or CI pipeline.\n\nThe full codegen pipeline that produces this shared surface is covered in [Architecture: Shared Codegen Pipeline](codegen-architecture).\n\n## Command style: task-oriented vs. generic\n\nMost day-to-day work uses task-oriented commands with mnemonic names and curated flags:\n\n```bash\nprimitive send --to alice@example.com --body \"Hello\"\nprimitive reply --id <inbound-email-id> --body \"Thanks\"\nprimitive emails list\nprimitive emails get --id <inbound-email-id>\nprimitive functions templates\nprimitive functions init my-fn --template email-reply\nprimitive memories set thread:latest '{\"email_id\":\"em_123\"}'\nprimitive deliveries replay --id <delivery-id>\n```\n\nEvery generated OpenAPI operation also remains reachable directly, for full schema parity or when no task-oriented command exists yet:\n\n```bash\nprimitive emails:list-emails\nprimitive sending:reply-to-email\n```\n\n| | Task-oriented commands | Generic operation commands |\n|---|---|---|\n| Naming | Mnemonic verbs (`send`, `reply`, `functions deploy`) | `<tag>:<operation-id>` (kebab-case) |\n| Flags | Curated, common defaults pre-filled | Full parity with the OpenAPI operation's parameters |\n| When to use | Everyday workflows, scripts, CI | Advanced/uncommon operations, exploring the full API surface |\n| Discoverability | `primitive --help`, `primitive <group> --help` | `primitive list-operations`, `primitive describe` |\n\nSee [Direct API Access and Generic Commands](cli-generic-api-access) for the `api-command` shortcut, `list-operations`, and `describe` in detail.\n\n## Command groups\n\nThe CLI's command surface maps directly onto Primitive's operation domains:\n\n| Group | Example commands | Covered on |\n|---|---|---|\n| Auth | `login`, `signin`, `signup`, `logout`, `whoami` | [Authentication](cli-authentication) |\n| Email | `send`, `reply`, `emails list`, `search`, `semantic-search` | [Sending, Replying, and Searching Email from the CLI](cli-email-commands) |\n| Domains & routing | `domains-zone-file`, `routes add/list/remove/reorder` | [Managing Domains and Recipient Routes](cli-domains-and-routes) |\n| Functions | `functions init/deploy/redeploy/test/logs` | [Primitive Functions: Deploy, Route, and Manage](cli-functions) |\n| Org secrets | `org-secrets-list/set/remove` | [Org Secrets Management](cli-org-secrets) |\n| Payments | `payments register-payout-address/charge/pay/pay-email` | [x402 Payments from the CLI](cli-payments) |\n| Wake schedules | `wake-schedules-*`, `wake-authorizations-*` | [Wake Schedules and Authorizations](cli-wake) |\n| Memories & chat | `memories set/get/search/delete`, `chat` | [Memories and Chat Commands](cli-memories-and-chat) |\n| Payloads | `payloads push/pull` | [Payloads Command: Streaming Large Attachments from the CLI](cli-payloads-command) |\n| Inbox | `inbox-setup`, `inbox-status` | [Inbox Setup and Status](cli-inbox) |\n| Agent upgrade | `agent-upgrade` | [Agent Account Upgrade from the CLI](cli-agent-upgrade) |\n| Generic API access | `<tag>:<operation-id>`, `list-operations`, `describe` | [Direct API Access and Generic Commands](cli-generic-api-access) |\n\n## A concrete example: functions deploy\n\n`primitive functions deploy` shows the pattern the whole CLI follows: a task-oriented command that wraps a generated operation and adds terminal-specific ergonomics (reading a file off disk, an optional wait loop, stderr hints) around it.\n\n```bash\nprimitive functions templates\nprimitive functions init my-fn\ncd my-fn && npm install && npm run build\nprimitive functions deploy --name my-fn --file ./dist/handler.js\n```\n\nUnder the hood this calls the same `createFunction` generated operation available as `primitive functions:create-function`, but reads the bundle from `--file` instead of requiring you to shell-escape an entire ESM module into a JSON body. Passing `--secret KEY=VALUE` fans the same command out into `create-function` → `set-secret` per pair → a final `update-function` redeploy, so the running handler picks up the bindings in one call. See [Primitive Functions: Deploy, Route, and Manage](cli-functions) for the full flag surface.\n\n## What the CLI does not own\n\nSeveral concepts the CLI exercises are explained in full elsewhere, not on this page:\n\n- The inbound/outbound email model (normalized email object, wait mode, delivery statuses) is explained once in [Inbound and Outbound Email Model](email-model).\n- Webhook signature verification and the event catalog are explained in [Webhook Events Overview](webhook-events).\n- The non-custodial x402 payment model (payout registration, challenges, spend policy) is explained in [x402 Payments Overview](x402-payments-overview).\n- Primitive Functions and recipient routing as platform concepts are explained in [Primitive Functions and Recipient Routing (Platform Concepts)](functions-and-routing-concepts).\n- The generated operation manifest that backs every generic command is explained in [Operation Manifest Reference](operation-manifest).\n\n## Next steps\n\n<CardGroup cols={2}>\n\n<Card title=\"Authentication\" href=\"cli-authentication\">\n\nSign in, check who you're authenticated as, and diagnose credential issues.\n\n</Card>\n\n<Card title=\"Sending, Replying, and Searching Email from the CLI\" href=\"cli-email-commands\">\n\nSend your first email and poll an inbox from the terminal.\n\n</Card>\n\n<Card title=\"Direct API Access and Generic Commands\" href=\"cli-generic-api-access\">\n\nCall any generated operation directly and explore the full API surface.\n\n</Card>\n\n<Card title=\"Primitive Functions: Deploy, Route, and Manage\" href=\"cli-functions\">\n\nScaffold, deploy, and test serverless email handlers.\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/src/smartmemo/cli.py","raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+What+is+the+Primitive+CLI%3F&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fcli-overview","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}