---
title: "What is the Primitive CLI?"
canonical: "https://test.abhinandan.one/cli-overview"
markdown_url: "https://test.abhinandan.one/cli-overview.md"
publisher: "Primitive SDKs"
kind: "concept"
content_type: "reference"
category: "CLI"
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."
keywords: ["primitive CLI", "npm install -g primitive", "oclif command surface", "primitive api-command", "cli-node", "prim alias"]
last_modified: "2026-08-11T18:54:50.979695+00:00"
published_at: "2026-08-11T18:54:50.833895+00:00"
source_files:
  - "cli-node/README.md"
sections:
  - {anchor: "how-it-relates-to-the-node-sdk-and-api-core", title: "How it relates to the Node SDK and api-core"}
  - {anchor: "command-style-task-oriented-vs-generic", title: "Command style: task-oriented vs. generic"}
  - {anchor: "command-groups", title: "Command groups"}
  - {anchor: "a-concrete-example-functions-deploy", title: "A concrete example: functions deploy"}
  - {anchor: "what-the-cli-does-not-own", title: "What the CLI does not own"}
  - {anchor: "next-steps", title: "Next steps"}
---

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

# What is the Primitive CLI?

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.

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.

Install it separately from the Node SDK:

```bash
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`](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.

No-install form:

```bash
npx primitive@latest <command>
```

> **Note:** `@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](https://test.abhinandan.one/node-sdk-quickstart.md). The CLI is for your shell and CI, not for import into a handler.

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

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

```mermaid
flowchart LR
  A[openapi/primitive-api.yaml] --> B[api-core: generated client, operation manifest, PrimitiveApiClient]
  B --> C["@primitivedotdev/sdk (Node SDK)"]
  B --> D["primitive (CLI)"]
  C -.->|imported by| D
```

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](https://test.abhinandan.one/codegen-architecture.md).

## Command style: task-oriented vs. generic

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

```bash
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:

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

| | Task-oriented commands | Generic operation commands |
|---|---|---|
| Naming | Mnemonic verbs (`send`, `reply`, `functions deploy`) | `<tag>:<operation-id>` (kebab-case) |
| Flags | Curated, common defaults pre-filled | Full parity with the OpenAPI operation's parameters |
| When to use | Everyday workflows, scripts, CI | Advanced/uncommon operations, exploring the full API surface |
| Discoverability | `primitive --help`, `primitive <group> --help` | `primitive list-operations`, `primitive describe` |

See [Direct API Access and Generic Commands](https://test.abhinandan.one/cli-overview/cli-generic-api-access.md) 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:

| Group | Example commands | Covered on |
|---|---|---|
| Auth | `login`, `signin`, `signup`, `logout`, `whoami` | [Authentication](https://test.abhinandan.one/cli-overview/cli-authentication.md) |
| Email | `send`, `reply`, `emails list`, `search`, `semantic-search` | [Sending, Replying, and Searching Email from the CLI](https://test.abhinandan.one/cli-overview/cli-email-commands.md) |
| Domains & routing | `domains-zone-file`, `routes add/list/remove/reorder` | [Managing Domains and Recipient Routes](https://test.abhinandan.one/cli-overview/cli-domains-and-routes.md) |
| Functions | `functions init/deploy/redeploy/test/logs` | [Primitive Functions: Deploy, Route, and Manage](https://test.abhinandan.one/cli-overview/cli-functions.md) |
| Org secrets | `org-secrets-list/set/remove` | [Org Secrets Management](https://test.abhinandan.one/cli-overview/cli-org-secrets.md) |
| Payments | `payments register-payout-address/charge/pay/pay-email` | [x402 Payments from the CLI](https://test.abhinandan.one/cli-overview/cli-payments.md) |
| Wake schedules | `wake-schedules-*`, `wake-authorizations-*` | [Wake Schedules and Authorizations](https://test.abhinandan.one/cli-overview/cli-wake.md) |
| Memories & chat | `memories set/get/search/delete`, `chat` | [Memories and Chat Commands](https://test.abhinandan.one/cli-overview/cli-memories-and-chat.md) |
| Payloads | `payloads push/pull` | [Payloads Command: Streaming Large Attachments from the CLI](https://test.abhinandan.one/cli-overview/cli-payloads-command.md) |
| Inbox | `inbox-setup`, `inbox-status` | [Inbox Setup and Status](https://test.abhinandan.one/cli-inbox.md) |
| Agent upgrade | `agent-upgrade` | [Agent Account Upgrade from the CLI](https://test.abhinandan.one/cli-agent-upgrade.md) |
| Generic API access | `<tag>:<operation-id>`, `list-operations`, `describe` | [Direct API Access and Generic Commands](https://test.abhinandan.one/cli-overview/cli-generic-api-access.md) |

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

```bash
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](https://test.abhinandan.one/cli-overview/cli-functions.md) 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](https://test.abhinandan.one/email-model.md).
- Webhook signature verification and the event catalog are explained in [Webhook Events Overview](https://test.abhinandan.one/webhook-events.md).
- The non-custodial x402 payment model (payout registration, challenges, spend policy) is explained in [x402 Payments Overview](https://test.abhinandan.one/x402-payments-overview.md).
- Primitive Functions and recipient routing as platform concepts are explained in [Primitive Functions and Recipient Routing (Platform Concepts)](https://test.abhinandan.one/functions-and-routing-concepts.md).
- The generated operation manifest that backs every generic command is explained in [Operation Manifest Reference](https://test.abhinandan.one/operation-manifest.md).