CLI Reference

Instant builds. One-command deploys. Zero configuration.

Instant Everything

Nounjs CLI is built for speed. Bun-powered builds complete in milliseconds. One command deploys your app to yourapp.nounjs.app in seconds.

Build: ~30ms
Deploy: ~3 seconds
Hot reload: instant

Installation

# Global installation
npm install -g @noundryfx/nounjs

# Or use bunx/npx without installing
bunx @noundryfx/nounjs <command>
npx @noundryfx/nounjs <command>

Recommended: Use Bun for faster execution: bunx @noundryfx/nounjs <command>

Commands Overview

CommandDescription
createCreate a new project
devBuild and start dev server with hot reload
buildBuild CSS and JS for production
bundle / prodFull production build
publishBuild and deploy to nounjs.app
compileCompile .noun files to JS
generate / gGenerate components and pages
scaffoldGenerate complete UI from OpenAPI spec
addAdd UI components
validateValidate templates
doctorDiagnose project issues
refresh / upgradeUpdate Nounjs core files to latest version

noun create

Create a new Nounjs project with complete scaffolding.

# Create with default Tailwind styling
noun create my-app

# Create with Basecoat UI styling
noun create my-app --basecoat

# Explicit styling options
noun create my-app --style tailwind
noun create my-app --style basecoat

# Include sample components
noun create my-app --sample

Options

OptionDescription
--style <name>Choose styling: tailwind (default) or basecoat
--tailwindShorthand for --style tailwind
--basecoatShorthand for --style basecoat
--sampleInclude sample components

noun dev

Build the project and start a development server with hot reload.

noun dev            # Start on port 3000
noun dev 8080       # Custom port
noun dev --no-banner # Minimal banner output
  _   _                       _ ____
 | \ | | ___  _   _ _ __     | / ___|
 |  \| |/ _ \| | | | '_ \ _  | \___ \
 | |\  | (_) | |_| | | | | |_| |___) |
 |_| \_|\___/ \__,_|_| |_|\___/|____/
 v0.9.31

info Starting development server...
done Compiled 10 components in 28ms
done dist/styles.css (57.7kb) in 1067ms
done Initial build complete in 1217ms

Hot reload watches for changes in CSS, .noun files, and app.js, automatically refreshing the browser.

noun build / noun prod

Build CSS and JavaScript for production.

# Standard build
noun build
noun build --verbose  # Show detailed output

# Full production build (recommended)
noun prod             # Alias for noun bundle
noun bundle --no-banner

Production Build Steps

  1. Copy latest Nounjs runtime (noun.esm.js, router.esm.js) to dist/
  2. Compile .noun files from src/pages/ to src/compiled/
  3. Build and minify Tailwind CSS to dist/styles.css
  4. Bundle and minify JavaScript with source maps to dist/app.bundle.js

noun publish

Build and deploy your app to nounjs.app hosting. One command. Live in seconds.

# Deploy with auto-detected app name
noun publish

# Deploy with specific app name
noun publish my-app

# Preview deployment (7-day expiration)
noun publish my-app --preview

# PR-specific preview
noun publish my-app --pr 123

# Dry run (preview what would be uploaded)
noun publish --dry-run

# Skip build step
noun publish --skip-build
Instant Deploy

Your app is live at https://my-app.nounjs.app

No CI/CD setup. No infrastructure config. No waiting. Just noun publish.

Authentication

Set your token via environment variable, config file, or CLI argument:

# Environment variable
export NOUN_TOKEN=your-token

# Config file (~/.nounrc)
{"token": "your-token"}

# CLI argument
noun publish --token your-token

noun generate

Generate components and pages with templates.

# Generate a component
noun g component Button

# Generate pages with different types
noun g page Dashboard        # Basic page
noun g page Users list       # List page with search/table
noun g page Products grid    # NounTable data grid
noun g page UserEdit form    # Create/edit form
noun g page UserDetail detail # Detail view
noun g page Login login      # Login page

Page Types

TypeDescription
basicSimple page with header and content (default)
listData list with search and table
gridNounTable data grid with inline editing
formCreate/edit form with validation
detailDetail view page
loginAuthentication login page

noun scaffold

Generate a complete Nounjs application from an OpenAPI/Swagger specification. Point at any API, get a full working UI.

API-First Development

Transform any OpenAPI spec into a fully functional admin dashboard with list, detail, and form pages for every resource. Perfect for rapid prototyping or building internal tools.

Supports OpenAPI 3.0/3.1 and Swagger 2.0 specifications in JSON format.
# Generate from a URL
noun scaffold https://api.example.com/openapi.json

# Generate from a local file
noun scaffold ./swagger.json

# With custom output directory and app name
noun scaffold https://api.example.com/openapi.json --output ./my-dashboard --name "Admin Panel"

# Use Basecoat styling instead of Tailwind
noun scaffold ./api-spec.json --basecoat

# Force overwrite existing files
noun scaffold ./swagger.json --force

Options

OptionDescription
--output, -o <dir>Output directory (default: current directory)
--name, -n <name>App name (default: from API title in spec)
--style, -s <style>Styling system: 'tailwind' (default) or 'basecoat'
--basecoatShorthand for --style basecoat
--skip-installDon't run bun install after scaffolding
--skip-compileDon't compile .noun files after generation
--force, -fOverwrite existing files

What Gets Generated

API Client

  • src/api/client.js - Full API client with all endpoints
  • src/api/types.js - JSDoc type definitions from schemas
  • src/api/auth.js - Auth store with token management

Layout & Dashboard

  • src/pages/layout.noun - App shell with sidebar + logout
  • src/pages/dashboard.noun - Overview with resource cards
  • src/pages/login.noun - Login page (if auth defined)

Resource Pages

  • {resource}-list.noun - Data table with search & pagination
  • {resource}-detail.noun - Single item detail view
  • {resource}-form.noun - Create/edit form with validation

Project Files

  • app.js - Entry point with router + auth guards
  • index.html - HTML template
  • noun.config.json - Project configuration

Authentication Support

Scaffold automatically detects securitySchemes in your OpenAPI spec and generates appropriate authentication UI and logic.

Supported Auth Types

  • OAuth2 - Authorization Code, Implicit, Password, Client Credentials
  • HTTP Basic - Username/password authentication
  • HTTP Bearer - JWT or token-based auth
  • API Key - Header, query, or cookie-based keys

Generated Features

  • Login page tailored to auth type
  • Auth store with token persistence
  • Route guards for protected pages
  • Logout button in layout header
  • Token refresh support (OAuth2)

How It Works

  1. 1
    Parse OpenAPI Spec - Fetches and parses the OpenAPI/Swagger JSON from a URL or local file. Resolves $ref references and extracts API metadata.
  2. 2
    Discover Resources - Analyzes paths to identify REST resources (e.g., /products, /users) and their CRUD operations (list, read, create, update, delete).
  3. 3
    Extract Schemas - Pulls schema definitions to understand data models, property types, validation rules, and relationships.
  4. 4
    Generate Code - Creates API client methods, type definitions, and .noun pages tailored to each resource's schema and available operations.
  5. 5
    Compile & Configure - Compiles .noun files to JavaScript and sets up routing for all generated pages.

Common OpenAPI Endpoints

FrameworkTypical Endpoint
.NET / ASP.NET/openapi/v1.json, /swagger/v1/swagger.json
Node.js / Express/api-docs, /swagger.json
FastAPI (Python)/openapi.json
Spring Boot (Java)/v3/api-docs
Rails / Grape/swagger_doc.json

Example: Pet Store API

# Generate a dashboard for the Swagger Pet Store demo API
noun scaffold https://petstore.swagger.io/v2/swagger.json --name "Pet Store Admin"

# Navigate to the project
cd pet-store-admin

# Install dependencies and start
bun install && noun dev
CORS Configuration

The generated app makes requests directly to your API. If your API runs on a different domain, ensure CORS is properly configured to allow requests from your development server.

noun compile

Compile .noun single-file components to JavaScript.

# Compile once
noun compile

# Watch mode
noun compile --watch

# Verbose output with timing
noun compile --verbose

# Custom paths
noun compile --src src/components --out dist/components

noun refresh

Update Nounjs core files in your project when a new version of the CLI is available.

# Check and update to latest version
noun refresh

# Force refresh even if versions match
noun refresh --force

# Alias: upgrade
noun upgrade

When to use: Run noun refresh after updating the Nounjs CLI to get the latest framework improvements in your existing projects.

What Gets Updated

  • build/noun.esm.js - Core framework module (local build artifacts)
  • build/router.esm.js - Router module
  • noun.config.json - Version tracking updated

Options

OptionDescription
--force, -fForce refresh even if project is already up to date

Configuration

Project configuration in noun.config.json:

noun.config.json
{
  "nounVersion": "0.9.19",
  "style": "basecoat",
  "compile": {
    "input": "src/pages",
    "output": "src/compiled"
  },
  "bundle": {
    "entry": "app.js",
    "output": "dist/app.js"
  }
}
OptionDescription
nounVersionNounjs version used to create/update the project (used by noun refresh)
styleStyling system: tailwind or basecoat
compile.inputSource directory for .noun files
compile.outputOutput directory for compiled JS
bundle.entryJavaScript entry point
bundle.outputBundled output file