Supra is the CLI tool for creating new Supranim projects and managing them!

nimble install supra

😍 What Supra does

• Creates a new Supranim project with a single command
• Two starter kits: full-stack web app and REST API
• Interactive prompts for author, license, and services
• Recipes: pick the services you want and they get wired into your project for you
• Bundles static assets for production
• Written in Nim, uses the clue package manager for development

🚀 Quick start

Install Supra, then create a project:

nimble install supra

Create a web app

supra init myapp

The project name must be a valid Nim identifier, so use letters, numbers and underscores (no dashes).

You will be asked for the author name and a license (press Enter to accept the defaults), then you will get a list of services to choose from. Hit Space to toggle a service and Enter to confirm. When it is done:

cd myapp && nimble build
cd build && ./myapp start .

Starter Kit (web app) features

The web starter kit gives you a working site, not an empty folder:

• Server-side rendered pages with the Tim template engine, with layouts/, partials/ and views/ folders ready to go
• Full auth flow: register, login, logout, and a forgot/reset password flow with email verification
• Session management and flash messages
• A user model from the session service to extend
• Controllers for accounts, auth, pages and errors, wired to the index, account and auth views
• model/, storage/ and src/config/ folders fed by your .env
• Database (with a migrations/ folder), event, middleware and provider services ready to extend
• An assets/ folder for your CSS and images, which Supra can bundle into the binary for production

Create a REST API

Same thing, JSON instead of HTML pages:

supra init myapi restapi

Both project types accept the same recipe list, so everything described below applies to either.

🧩 Recipes

A recipe is a small YAML file that describes one service. Pick the ones you want while creating your project and Supra will:

• add its dependencies to your .nimble file
• copy its service provider into src/service/provider/
• copy any configuration file it needs into src/config/
• add an init() call to App.services for stateful providers

Stateless providers (bag, brotli, multipart, nimcrypto, nimcypher, nimsodium, zippy, zlib and every openparser/* recipe) need no init call, so they are just there for you to import.

🔐 Auth and security

• jose — JWT/JWS auth via nimbase/jose. Ships src/config/jose.toml, where secret accepts ${env.JWT_SECRET} references. Gives you issueToken and verifyToken.
• blackpaper — Password strength validator via openpeeps/blackpaper. Ships src/config/blackpaper.toml with the wordlist dictionary path. Gives you checkPassword and isStrongPassword.
• nimcypher — Encryption and hashing via nimbas/nimcypher. Gives you hashUserPassword and checkUserPassword.
• nimcrypto — Hashing, HMAC, PBKDF2/scrypt passwords, AES-GCM/CBC via cheatfate/nimcrypto. Covers every *Hex hash (SHA-1/2, RIPEMD-160, SHA-3, BLAKE2), plus hmacHex, deriveKey, randomHex, randomToken, constantTimeEqual, encryptData/decryptData (AES-256-GCM) and encryptDataCbc/decryptDataCbc.
• e2ee — E2EE, password hashing and AEAD via openpeeps/e2ee (Monocypher). Argon2id passwords, seal/unseal and BLAKE2b hashing.
• nimsodium — Encryption and password hashing via libsodium.

🗄 Databases

• ormin — Prepared-statement ORM via Araq/ormin. Owns a global sqlite db you can use in query: blocks, and ships src/service/database/schema.sql as a schema example (import it with importModel).
• norm — Object-driven ORM via moigagoo/norm. Validates the DB_* environment variables and offers withNormDb. Ships an account model example.
• ozark — Ozark ORM models and tables via openpeeps/ozark. Prepares its tables on init() and ships an example user model, but only when src/model/user.nim does not exist yet — the web starter kit already has one (the session models), and Supra will not overwrite it. Run ozark.init() after the base db.init().

✅ Validation and uploads

• bag — Input bag validation via openpeeps/bag.
• multipart — Multipart uploads via openpeeps/multipart. Gives you parseUpload.
• mimedb — MIME type database via openpeeps/mimedb. Gives you mimeTypeFor.

🗜 Compression

• brotli — Brotli compression via nimbase/nbrotli. Gives you compressText.
• zippy — Compression via guzba/zippy (gzip, zlib, deflate). Gives you compressData and decompressData.
• zlib — Compression via status-im/nim-zlib (gzip). Gives you compressData and decompressData.

📄 Parsers (openparser)

One recipe per openparser module, so you only pull in the parser you actually use. All of them are plain re-exports of the module, with no init to worry about.

Recipe	What you get
openparser/json	JSON parsing and serialization via openpeeps/openparser
openparser/yaml	YAML parsing and dumping via openpeeps/openparser
openparser/toml	TOML parsing and dumping via openpeeps/openparser
openparser/xml	XML parsing and serialization via openpeeps/openparser
openparser/csv	Zero-copy CSV parsing via openpeeps/openparser
openparser/bson	BSON documents via openpeeps/openparser
openparser/fbe	Fast Binary Encoding via openpeeps/openparser
openparser/html	HTML parsing via openpeeps/openparser
openparser/feed	Atom feed parsing via openpeeps/openparser
openparser/rss	RSS parsing via openpeeps/openparser
openparser/ical	iCalendar RFC 5545 via openpeeps/openparser
openparser/dotenv	Dotenv loading via openpeeps/openparser
openparser/fuzzy	Fuzzy string matching via openpeeps/openparser
openparser/path	Path and URL parsing via openpeeps/openparser
openparser/plist	Apple plist via openpeeps/openparser
openparser/uuid	UUID v1-v8 via openpeeps/openparser
openparser/vcard	vCard contacts via openpeeps/openparser
openparser/css	CSS parsing and validation via openpeeps/openparser
openparser/colors	Color parsing and manipulation via openpeeps/openparser
openparser/qr	QR code encoding via openpeeps/openparser
openparser/regex	Regex matching via openpeeps/openparser
openparser/svg	SVG parsing and serialization via openpeeps/openparser

Non-interactive use

In CI, or if you just like flags, skip the prompts and pick the recipes yourself:

supra init myapi restapi --skipconfig --with=jose,bag,blackpaper

🧰 Other commands

Bundle static assets

supra bundle.assets ./src/storage/assets ./src/service/assets_embed.nim

Walks the given folder, embeds every file into a single .bin blob and writes a generated Nim module that indexes it, so your app can serve CSS, images and fonts straight from memory with no filesystem access. Assets are keyed under / (app.css becomes /app.css); pass --skip-prefix to drop the leading slash. The web starter kit already calls this for you when you build with supraEmbedAssets defined.

❤ Contributions & Support

• 🐛 Found a bug? Create a new Issue
• 👋 Wanna help? Fork it!
• 🎉 Spread the word! Tell your friends about Supranim

🎩 License

Supranim | MIT license. Made by Humans from OpenPeeps.
Copyright © 2025 OpenPeeps & Contributors — All rights reserved.