CLI reference

Use niral <command> through the installed launcher, or npx niral <command> without configuring PATH. Node.js 22+ is required.

niral --help                    show commands without running them
niral --version                 installed framework version (npm also shows launcher)
niral update                    explicitly update the managed framework
niral di <command>              Developer Intelligence (setup/status/ask/chat/new)
niral create <name|.>            new/empty project [--template minimal|blog|dashboard]
niral dev [dir] [-p port]        dev server (HMR, overlays)      default 5199
niral doctor [dir]               diagnose "why won't it start" problems
niral check [dir]                TypeScript checking
niral test [dir]                 run the project's tests/
niral migrate [dir] [--db path]  apply pending migrations/ (auto-runs at boot)
niral build [dir] [-o dist]      production release
niral start [dir] [-p port]      production server               default 8199
niral deploy [dir]               generate deploy/ — systemd, nginx, Dockerfile
niral export [dir] [-o out]      static site
niral jobs [dir]                 standalone job/cron worker
niral compile <file> [-o out]    compile one component
niral serve [dir] [-p port]      static development server       default 4173
niral add <recipe> [dir]         add a framework recipe
niral shield <status|log|verify|integrity> [dir]
niral watchdog [dir] [-p port]   independent health/integrity guardian
niral snapshot [list] [dir]      local snapshots
niral snapshot --remote [dir]    encrypted remote snapshot
niral snapshot list --remote [dir]
niral snapshot push <label|latest>
niral restore <label|latest> [dir] [--remote]
niral rollback [dir] [--to hash]  restore a previous built release
niral rotate-secret [dir] [--env file]
niral lsp                        language server (stdio)

-h and -v alias --help and --version. Appending --help shows help without executing a command. Unknown commands and failed child commands return a nonzero exit status. Restore, rollback and secret rotation change state; inspect the security guide before using them.

Framework and launcher updates

Launcher 0.1.3 supports explicit framework updates:

npx niral@latest update
niral update

The npm form handles updates before calling the cached CLI, so it can upgrade an older framework without an update command. The direct form works after that framework update. Both update only NIRAL_HOME/framework (default: ~/.niral/framework) from the official repository's main branch. There is no automatic background update or per-command network refresh, and no version pinning to the npm launcher version. Git updates print the revision.

npx create-niral@latest selects the npm launcher; it does not update an already cached framework. Update a globally installed npm launcher separately with npm install -g niral@latest or npm install -g create-niral@latest, whichever you installed. Installing both globally can cause executable conflicts.

Stop active Niral development/build commands before updating. Git installs must be clean, on main, and use the official HTTPS origin; fast-forward failures stop without an archive fallback. Archive replacements are staged and the old directory is kept at the printed framework-backup-*/framework path. Local additions remain there, not merged into the new framework. Backups are not pruned. Concurrent installers and symlinked framework paths are refused. After an interruption, inspect other installers before removing a stale NIRAL_HOME/.framework-install-lock directory.

Keep applications outside the framework installation. Source checkouts outside the managed path must be updated with Git. Updating the framework does not migrate projects, update npm packages or restart/deploy production servers.

Developer Intelligence - niral di

DI is part of the local framework, available through the existing npm launcher. No Niral Cloud account is required. Choose a provider preset or configure a custom endpoint; there is no default model, substitution or provisioning.

niral di setup
niral di status
niral di ask "Explain this project's routes" --root ./myapp --read-only
niral di ask "Add a contact page" --root ./myapp
niral di chat --root ./myapp
niral di new myblog "Customize the home page" --template blog
niral di ask "Explain server blocks" --no-tools

Bare niral di setup offers OpenAI, Claude (Anthropic), Azure OpenAI or Custom. Named providers set protocol/auth automatically. OpenAI uses Responses with bearer auth at https://api.openai.com/v1; Claude uses Messages with x-api-key auth at https://api.anthropic.com/v1 and version 2023-06-01. Azure uses Responses with api-key auth: enter your HTTPS resource URL or /openai/v1 base; a resource URL is expanded to /openai/v1, without an API-version query. Enter the exact deployment name for Azure, or exact model name for other providers. Custom keeps manual protocol, endpoint, auth and optional version choices. There is no endpoint probing. Amazon Bedrock is not yet supported. Setup asks for the credential variable name, never the key. Ctrl-C or end-of-input cancels without saving. For automation, pass explicit flags listed by niral di setup --help. Supply the credential privately in the named environment variable. Do not paste keys into CLI arguments, project files, shell history or chat. setup stores settings and the variable name in NIRAL_HOME/di.json (default ~/.niral/di.json, mode 0600), never the key. It makes no API request and requires --replace to overwrite existing settings. status stays offline and reports credential availability without printing it. DI does not load .env files or use app-side NIRAL_AI_* settings.

Protocols: responses, chat-completions, anthropic. Explicit auth: bearer, api-key, x-api-key, none. The API base excludes the final operation path and query string; use --api-version VERSION when required. HTTPS is required except for loopback endpoints, which can use --auth none. Provider compatibility requires the selected protocol and function calling.

Interactive sessions disclose the destination/model, then request approval for each tool with its JSON-escaped arguments. Only y approves; Enter denies. There is no auto-approve flag. --read-only removes writes, but still requires approval. Noninteractive runs require ask <prompt> --no-tools; no workspace content is attached in that mode. Ctrl-C cancels pending work, not completed edits.

The tools list one directory (at most 100 entries), read UTF-8 source/text files (at most 24 KiB), and create/replace approved source files. Edits require the hash from the latest read; a changed file rejects the edit. Approval displays full new content, not a computed diff. Original content/path/hash are backed up as private JSON under NIRAL_HOME/di-backups/<run-id>/ before writing; originals for new files are null. Backups are retained without pruning or automatic rollback.

Workspace paths cannot escape the selected root. Dot paths, conventional data, dependency, build, backup and secret paths, symlinks, binary/unsupported files and hard-linked file reads/writes are blocked. NIRAL_HOME is excluded too. Supported extensions: .niral, .js, .mjs, .cjs, .ts, .jsx, .tsx, .css, .html, .md, .json, .txt, .sql. Gitignore rules are not interpreted. Ordinary source can still contain secrets: review every read before sending it to your provider. These checks are not an OS sandbox or a guarantee against prompt injection/concurrent hostile filesystem changes. The model is instructed to read applicable AGENTS.md files, but approval remains your responsibility.

chat keeps up to eight user/assistant text exchanges and 32 KiB of context in memory; no transcripts are saved. Use /clear or /exit. Prompts are limited to 32 KiB. new accepts a simple directory name under the current directory, requires an empty/new target, and asks before scaffolding minimal/blog/dashboard. A later DI failure preserves the scaffold. No shell execution, dependency installation, automatic tests, streaming or deployment. Review changes, then run niral check, niral test and niral build yourself. Provider retention and charges depend on your chosen service; DI makes no blanket privacy guarantee.

Testing — niral test

Drop tests/*.test.js in the project. Helpers are ambient — no imports:

test("home renders and the server answers", async () => {
  const app = await startApp()          // boots THIS app on a random port
  const html = await (await fetch(app.url + "/")).text()
  ok(html.includes("<h1>"), "rendered")
})

test ok eq startApp renderRoute — exits 1 on failure, CI-ready.

Doctor — niral doctor

One command that checks the things that actually go wrong: Node version, broken hooks.js/jobs.js (a syntax error there breaks every request), missing declared env vars, .gitignore covering env files, NIRAL_SECRET, data/ writability, pending migrations, and whether a production release exists. ✓ / ! / ✗ lines — exits 1 only on hard failures.

Migrations — niral migrate

Numbered SQL files in migrations/ run once each, in order, in transactions:

migrations/001-create-users.sql
migrations/002-add-votes.sql       → applied to data/app.db, tracked in _migrations

They auto-apply when the server boots — a deploy that adds a migration ships its own schema change. A failing file rolls back and stops the boot loudly.

Recipes — niral add

Recipes either scaffold code you own, or download one official binary. Never npm.

Editor support

The editors/vscode extension gives syntax highlighting, diagnostics with teaching hints, completions and hover docs — driven by niral lsp, which any LSP-capable editor can use.