#CLI

#Contents

• Commands
• napikit new
• napikit build
• napikit bump
• napikit publish
• napikit npm-init

The napikit CLI is the dev-time and release-time tool for @teakit/napi projects. It requires Node.js >=20.19.0, is installed as a dev dependency by npx napikit new (or your manual npm install -D napikit), and is invoked through npx napikit or your package.json scripts.

#Commands

#napikit new

napikit new [name] [--pm <pm>] [--repo <owner/name>]

Scaffolds a new @teakit/napi project. Prompts interactively for anything not provided.

What it writes:

• build.zig, build.zig.zon
• package.json
• src/lib.zig (starter with two example functions)
• test.mjs
• .github/workflows/publish.yml
• A .gitignore and a README.md

After scaffolding, it runs npm install (or your detected PM), zig fetch for the napi Zig dependency from @teakit/napi, and an initial napikit build so the binary is available immediately.

Generated projects pin Zig 0.16.0. When Bun is selected, their workflow pins Bun 1.3.14.

#napikit build

napikit build [--release] [--only <names>] [--current] [--optimize <mode>]

Without --release, builds for the current platform in the optimization mode set by your build.zig (defaults to Debug). Produces:

zig-out/lib/
├── my-addon.node
└── my-addon.d.ts        (if .dts is set)

The CLI also drops a top-level my-addon.js re-exporter so the import path matches what users will see after publish.

With --release, cross-compiles every platform listed in .npm.platforms and lays out the full npm/ package tree. See Cross-compiling.

--only and --current speed up local iteration; both are additive and leave the rest of npm/ untouched. See Building a subset.

#napikit bump

napikit bump [version] [options]

Bumps the version in every package.json (main + per-platform bindings), creates an annotated tag, and pushes branch + tag.

The push triggers your tag-based CI workflow.

Before changing any package file, napikit bump verifies that the worktree (including untracked files) is clean. It also verifies an upstream branch when push is enabled and checks that v<version> does not already exist when tagging is enabled. The push names only the tracked branch and the tag created for this release; --no-tag pushes the branch without pushing any other local tags. Use --no-push or --no-tag only when you intentionally want to skip the corresponding operation and preflight.

#napikit publish

napikit publish [options]

For each package in npm/, runs npm publish --access public. Designed to be run in CI after napikit build --release.

Per-platform binding packages are published before the main package, so users who install during the publish window always get a working set.

Publishing continues far enough to report useful per-package results, but any required package failure makes the command fail with a non-zero exit instead of reporting success. An already-published version is treated as an idempotent skip.

#napikit npm-init

napikit npm-init --repo <owner/name> --workflow <file>

One-time setup: publishes any missing initial 0.0.0 versions, then verifies or configures npm trusted publishing (OIDC) for every package. Existing trust must match the requested repository, workflow, and publish permission. After this, your CI does not need an NPM_TOKEN.

You only run this once per package. The CI pipeline takes over from here. See Publishing for the full pipeline.

Repository names, workflow filenames, npm package names and versions, and generated binding paths are validated before subprocess or filesystem use. Existing trusted-publisher records are skipped only when their provider, repository, workflow filename, and publish permission all match the requested configuration. A mismatched or unverifiable record is retried, and a conflict remains an error instead of being reported as success. Initial publishing and trusted-publisher setup report failures per package; if any required operation fails, the command exits non-zero and can be re-run to retry the incomplete packages.