https://github.com/primitivedotdev/setup-primitive
Set up the primitive.dev CLI in a GitHub Actions workflow
https://github.com/primitivedotdev/setup-primitive
Last synced: 11 days ago
JSON representation
Set up the primitive.dev CLI in a GitHub Actions workflow
- Host: GitHub
- URL: https://github.com/primitivedotdev/setup-primitive
- Owner: primitivedotdev
- License: mit
- Created: 2026-06-05T17:27:43.000Z (30 days ago)
- Default Branch: main
- Last Pushed: 2026-06-05T17:29:39.000Z (30 days ago)
- Last Synced: 2026-06-10T11:33:54.526Z (25 days ago)
- Homepage: https://primitive.dev
- Size: 4.88 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Setup Primitive CLI
GitHub Action that installs the [primitive.dev](https://primitive.dev) CLI (`@primitivedotdev/cli`) and configures auth, so subsequent steps can run `primitive …` (or `prim …`) directly. The companion to [`deploy-function`](https://github.com/primitivedotdev/deploy-function) and [`send-email`](https://github.com/primitivedotdev/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
```yaml
- 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@`.
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
```yaml
- 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)
```yaml
- 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](https://github.com/primitivedotdev/primitive-mono-repo) under `tools/actions/setup-primitive/` and mirrored here on release tags. See [RELEASING.md](./RELEASING.md).
## License
MIT — see [LICENSE](./LICENSE).