What is the Primitive CLI?

The primitive CLI is a terminal client, built on the oclif framework, that exposes Primitive's email, payments, functions, and account operations as one-shot shell commands instead of SDK calls.

Install it separately from the Node SDK:

npm install -g primitive
primitive whoami
# `prim` is a short alias for the same binary
prim whoami

Install it as primitive. The same build is also published as primcli and the legacy scoped @primitivedotdev/cli, locked to the same version, for environments that already depend on those names.

No-install form:

npx primitive@latest <command>

How it relates to the Node SDK and api-core#

The CLI wraps the Node.js SDK (@primitivedotdev/sdk) runtime client with one-shot commands. Internally, both the CLI and the Node SDK bundle the workspace-internal @primitivedotdev/api-core package inline, so the generated HTTP client, operation manifest, and PrimitiveApiClient error handling are shared code, not reimplementations.

For 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.

The full codegen pipeline that produces this shared surface is covered in Architecture: Shared Codegen Pipeline.

Command style: task-oriented vs. generic#

Most day-to-day work uses task-oriented commands with mnemonic names and curated flags:

primitive send --to alice@example.com --body "Hello"
primitive reply --id <inbound-email-id> --body "Thanks"
primitive emails list
primitive emails get --id <inbound-email-id>
primitive functions templates
primitive functions init my-fn --template email-reply
primitive memories set thread:latest '{"email_id":"em_123"}'
primitive deliveries replay --id <delivery-id>

Every generated OpenAPI operation also remains reachable directly, for full schema parity or when no task-oriented command exists yet:

primitive emails:list-emails
primitive sending:reply-to-email

See Direct API Access and Generic Commands for the api-command shortcut, list-operations, and describe in detail.

Command groups#

The CLI's command surface maps directly onto Primitive's operation domains:

A concrete example: functions deploy#

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.

primitive functions templates
primitive functions init my-fn
cd my-fn && npm install && npm run build
primitive functions deploy --name my-fn --file ./dist/handler.js

Under 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 for the full flag surface.

What the CLI does not own#

Several concepts the CLI exercises are explained in full elsewhere, not on this page:

• The inbound/outbound email model (normalized email object, wait mode, delivery statuses) is explained once in Inbound and Outbound Email Model.
• Webhook signature verification and the event catalog are explained in Webhook Events Overview.
• The non-custodial x402 payment model (payout registration, challenges, spend policy) is explained in x402 Payments Overview.
• Primitive Functions and recipient routing as platform concepts are explained in Primitive Functions and Recipient Routing (Platform Concepts).
• The generated operation manifest that backs every generic command is explained in Operation Manifest Reference.

Next steps#