CLI

The primitive CLI is the recommended interface for agents and humans operating from a terminal. It handles auth, file inputs, command discovery, and common workflows that are awkward with raw HTTP.

Install

# Homebrew
brew install primitivedotdev/tap/primitive


# npm
npm install -g @primitivedotdev/cli

Homebrew installs the required Node.js runtime automatically. npm installs require Node.js 22 or newer. Both install the primitive binary.

No-install form:

npx @primitivedotdev/cli@latest <command>

The CLI ships through the primitivedotdev/tap Homebrew tap and as @primitivedotdev/cli on npm. It is separate from the runtime SDK: @primitivedotdev/cli provides the primitive binary, and @primitivedotdev/sdk is imported from application code.

Authenticate

primitive login
primitive whoami

curl https://api.primitive.dev/v1/account \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY"

primitive login opens a browser and stores an OAuth token set locally. whoami verifies the current token and prints the account context visible to the CLI. To revoke the current CLI session, run:

primitive logout

You can also revoke CLI and third-party OAuth grants from Settings -> Connected Apps. For non-interactive automation, API keys still work by setting PRIMITIVE_API_KEY.

Send Mail

primitive send \
  --to alice@example.com \
  --subject "Hello" \
  --body "Hi from Primitive" \
  --wait

curl -X POST https://api.primitive.dev/v1/send-mail \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"hello@your-org.primitive.email","to":"alice@example.com","subject":"Hello","body_text":"Hi from Primitive","wait":true}'

The CLI can infer a valid sender on the managed domain when possible.

Read Inbound Mail

primitive emails:latest --limit 5
primitive emails:get-email --id <email-id>

curl "https://api.primitive.dev/v1/emails?limit=5" \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY"


curl https://api.primitive.dev/v1/emails/<email-id> \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY"

Piped table output keeps ids complete so agents can chain commands safely.

Reply

primitive sending:reply-to-email \
  --id <inbound-email-id> \
  --body-text "Got it."

curl -X POST https://api.primitive.dev/v1/emails/<inbound-email-id>/reply \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body_text":"Got it."}'

Primitive derives recipient and threading headers from the inbound email.

Discover Send Permissions

primitive sending:get-send-permissions

curl https://api.primitive.dev/v1/send-permissions \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY"

Run this before a first outbound send if you are unsure whether a recipient is allowed.

Functions

Create and deploy a hosted Function:

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

CODE=$(cat dist/handler.js | jq -Rs .)


curl -X POST https://api.primitive.dev/v1/functions \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"my-fn\",\"code\":$CODE}"

primitive functions:init is local filesystem scaffolding, so the API equivalent starts when you deploy the built bundle.

Test and inspect it:

primitive functions:test-function --id <function-id>
primitive functions:list-function-logs --id <function-id>

curl -X POST https://api.primitive.dev/v1/functions/<function-id>/test \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY"


curl https://api.primitive.dev/v1/functions/<function-id>/logs \
  -H "Authorization: Bearer $PRIMITIVE_API_KEY"

Operation Discovery

Agents should use CLI help and operation descriptions before guessing command shapes.

primitive --help
primitive list-operations
primitive describe emails:get-email
primitive describe sending:reply-to-email

curl https://api.primitive.dev/v1/openapi

list-operations is the broad machine-readable manifest. describe gives focused parameter and behavior details for one operation.

Proxy Environments

On Node 22+ behind a proxy, set:

export NODE_USE_ENV_PROXY=1

Then HTTP_PROXY and HTTPS_PROXY are respected by Node networking. primitive doctor checks the environment.

primitive doctor is a local environment diagnostic. There is no REST endpoint for inspecting local proxy variables; use primitive whoami or the /v1/account request above to verify API reachability after setting them.

Good Agent Defaults

• Run primitive whoami before state-changing operations.
• Prefer CLI commands for terminal workflows instead of hand-written curl.
• Use --wait when an immediate send result is needed.
• Use describe before composing unfamiliar operations.
• Never print API keys or webhook secrets in logs.