Setup Primitive CLI

GitHub Action that installs the primitive.dev CLI (@primitivedotdev/cli) and configures auth, so subsequent steps can run primitive … (or prim …) directly. The companion to deploy-function and send-email: one setup step unlocks the whole CLI surface in CI — no per-command Action needed.

Requires Node.js on the runner (GitHub-hosted runners have it by default; otherwise run actions/setup-node first).

Quick start

- uses: primitivedotdev/setup-primitive@v0
  with:
    api-key: ${{ secrets.PRIMITIVE_API_KEY }}

# Any later step can now use the CLI — it reads PRIMITIVE_API_KEY from the env:
- run: primitive emails-wait --to inbox@yourdomain.com --timeout 60
- run: primitive send --from ci@yourdomain.com --to you@example.com --subject hi --text "done"

Inputs

Input	Required	Default	Description
api-key	no	—	Org-scoped Primitive API key. Masked and exported as PRIMITIVE_API_KEY for subsequent steps. Pass via ${{ secrets.* }}. Omit only if a later step supplies auth another way.
api-base-url	no	https://api.primitive.dev/v1	Exported as PRIMITIVE_API_BASE_URL. Override only for a non-production environment.
version	no	latest	npm version spec of @primitivedotdev/cli — 1 (latest 1.x), 1.0.1 (exact), or latest. Pin for reproducible CI.
verify	no	true	Run primitive whoami after install to fail fast on a bad/expired key and populate the outputs. Requires api-key.

Outputs

Output	Description
cli-version	The installed CLI version string.
org-id	Account/org id of the authenticated key (set only when verify ran).
email	Account email of the authenticated key (set only when verify ran).

What it does

1. npm install -g @primitivedotdev/cli@<version>.
2. Masks api-key and exports PRIMITIVE_API_KEY (+ PRIMITIVE_API_BASE_URL) to $GITHUB_ENV, so every later step in the job sees them — the CLI reads PRIMITIVE_API_KEY automatically.
3. (When verify is on and a key is set) runs primitive whoami to confirm the key works before your real steps run, and exposes org-id / email.

Examples

Pin a version + use the org-id output

- uses: primitivedotdev/setup-primitive@v0
  id: primitive
  with:
    api-key: ${{ secrets.PRIMITIVE_API_KEY }}
    version: "1"
- run: echo "Using primitive CLI ${{ steps.primitive.outputs.cli-version }} as org ${{ steps.primitive.outputs.org-id }}"

Install only (auth handled elsewhere)

- uses: primitivedotdev/setup-primitive@v0
  with:
    verify: 'false'   # no api-key → just install the CLI
- run: primitive login   # or set PRIMITIVE_API_KEY yourself before CLI calls

Why a setup Action (vs. one Action per command)

deploy-function and send-email are typed Node Actions for the two most common CI jobs-to-be-done. setup-primitive is the foundation: rather than publishing a thin Action per CLI verb, install the CLI once and run any primitive … command in plain run: steps. It also scales for free — new CLI commands are usable in CI the moment they ship, with no new Action release. Same model as actions/setup-node + raw node.

Security

• api-key is masked. Pass it as a GitHub secret (${{ secrets.* }}) — never hard-code.
• All inputs are passed to the shell via env: (not inline interpolation), so a crafted input can't inject shell commands.

Versioning

• Floating major tag v0 tracks the latest 0.x. Pin v0.1.0 for reproducible runs.

Source

Authored in primitivedotdev/primitive-mono-repo under tools/actions/setup-primitive/ and mirrored here on release tags. See RELEASING.md.

License

MIT — see LICENSE.