NNuvaka General AppDeveloper docs
TRDownload

Nuvaka › Developer docs › CLI (nuvaka-ext)

CLI: nuvaka-ext

The @nuvaka/extension-cli package creates, checks, packs, signs and publishes extensions. It needs Node.js 20+. Its major version is the API version it supports (1.x = API v1).

npm i -D @nuvaka/extension-cli     # or: npx nuvaka-ext …
npx nuvaka-ext --help
npx nuvaka-ext <command> --help

Global options: -h, --help, -v, --version, --json (machine-readable output; for CI). Commands that take a folder accept it as a positional argument or with --dir; the default is the current folder. The CLI's own messages are in Turkish.

Commands

CommandWhat it does
init <name>new extension scaffold
lint [folder|.nvx]checks with the same rules as the server
pack [folder]builds the <id>-<version>.nvx package
keys create [name] · keys listcreates / lists Ed25519 signing keys
sign <file.nvx>signs a package and prints the base64 signature
login --token nvd_…saves your developer token
logoutremoves the saved token
whoamiverifies the token and shows the account
publishpacks, signs and uploads
dev [folder]prints the development-mode command and runs lint on changes
test [folder]runs the extension's tests (vitest)

init

nuvaka-ext init <name> [--dir <folder>] [--username <user>] [--ui] [--background] [--force]
  • <name>: 2–40 characters, lower-case letters, digits, -; must start with a letter or digit. The ID becomes <username>.<name>.
  • --dir: target folder (default ./<name>). --force: write into a non-empty folder.
  • --username: your publisher username; if omitted it comes from login, otherwise you are asked.
  • --ui / --background: template; with neither you get both.

npm create @nuvaka/extension <name> -- [options] runs the same command.

lint

nuvaka-ext lint [folder|file.nvx] [--dir <folder>] [--remote] [--key <name>] [--api <url>]

Manifest schema, file types and sizes, forbidden patterns, and whether nuvaka.<name> uses match permissions. Exit code 1 on errors. Checklist: Security rules.

  • --remote: sends the package to the server for checking without publishing (needs a token).
  • --key: signing key for --remote (needed if your account has a key registered).
$ nuvaka-ext lint examples/apps/github-watcher
tarikgkhsn.github-watcher 0.1.0 — 7 dosya, açılmış 16.1 KB, paket 8.1 KB
Tamam: 0 uyarı

pack

nuvaka-ext pack [folder] [--dir <folder>] [--out <file|folder>]

Builds a deterministic .nvx (sorted entries, fixed timestamps) and prints its SHA-256 and size. No package is built if lint finds errors. Left out of the package: .git, node_modules, test/tests/__tests__/__mocks__/coverage folders, *.test.*/*.spec.*, dot files, *.nvx, a root package.json, lock files, tsconfig.json/jsconfig.json, vitest.config.*/vite.config.*.

keys and sign

nuvaka-ext keys create [name] [--force]    # default name: default
nuvaka-ext keys list
nuvaka-ext sign <file.nvx> [--key <name|path>]

The private key is written to ~/.config/nuvaka/keys/<name>.key, readable only by you (0600); the first key becomes the default. Add the public key to your account in the app under Profile › Developer › Publisher signing keys (this needs an app session; it cannot be done with a developer token). sign signs the raw 32-byte SHA-256 digest of the package with Ed25519.

login, logout, whoami

nuvaka-ext login --token nvd_… [--api <url>] [--username <name>] [--no-verify]
nuvaka-ext logout
nuvaka-ext whoami [--api <url>]

Create the token in the app under Profile › Developer › Developer tokens; it starts with nvd_, is shown once, is valid for 1 year, only works on publisher endpoints and can be revoked at any time. login verifies the token with the server and saves it to ~/.config/nuvaka/credentials.json (0600). --no-verify saves without verifying. whoami prints your username and extensions.

publish

nuvaka-ext publish [folder] [--dir <folder>] [--changelog "…"] [--key <name|path>] [--no-sign] [--api <url>]

Packs (stops on lint errors), signs if a key is available, and uploads. The result:

  • published — live;
  • review — waiting for review (a publisher's first extension, a version asking for critical permissions, or a new version of a verified extension);
  • rejected — scan findings are printed, exit code 1.

Key selection: --key › NUVAKA_KEY › default key › the only key. --changelog up to 2000 characters. --no-sign uploads unsigned (rejected if your account has a key registered). Packages are limited to 20 MB.

dev

nuvaka-ext dev [folder] [--dir <folder>]

Watches the folder and runs lint on every change (exit with Ctrl+C). For those running the app from source it also prints the command that loads the folder at startup:

# in the generalappclient folder (only debug builds load it)
NUVAKA_EXT_DEV_DIR='/path/hello' npm run tauri dev
# PowerShell
$env:NUVAKA_EXT_DEV_DIR="C:\path\hello"; npm run tauri dev

Several folders are separated with the operating system's path separator (: on Linux/macOS, ; on Windows). Folders are loaded when the session starts; reload in the app after a change. In the released app, Apps › Manage apps › Load from folder does the same (with developer mode on in the Profile tab).

test

nuvaka-ext test [folder] [--dir <folder>] [-- vitest options]

Runs npx vitest run in the extension folder; anything after -- goes to vitest. Tests use the mock nuvaka from @nuvaka/extension-sdk/testing (SDK).

Environment variables

VariableMeaning
NUVAKA_TOKENdeveloper token (CI); takes precedence over the saved token
NUVAKA_APIAPI URL (default https://generalappapi.nuvaka.com)
NUVAKA_KEYsigning key name or file path
NUVAKA_CONFIG_DIRconfig folder (default ~/.config/nuvaka)

CI example

# Secrets: NUVAKA_TOKEN (nvd_…) and the signing key file
npm ci
npx nuvaka-ext lint
NUVAKA_KEY=./ci.key npx nuvaka-ext publish --json --changelog "$CHANGELOG"

Nuvaka Apps API v1 · last updated 2026-09-27