Initialize Config

Generate or update the Nova config file with an interactive wizard that guides you through each step and saves when you confirm.

Summary

The initialize command scaffolds and maintains the nova.config.json file by opening a guided flow across project metadata, key entities, and canonical URLs.

Existing values populate each prompt so you can edit an accurate snapshot and only persist changes when you confirm them.

Why Use This Command?

• The wizard writes the JSON with only the fields you confirm, no extra cleanup required.
• The wizard lists each field, explains what each field is for, and guides you to fill known values.
• Avoid typos and mismatched formats with built-in validation for slugs, emails, and URLs.
• Dry run lets you walk through the questions without touching the config file until you're ready.

Use Cases

• Onboarding — Create the first nova.config.json for a new or migrated repository.
• Metadata refresh — Keep project descriptions, entities, and canonical URLs in sync after ownership changes.
• Normalization — Clean up manually edited entries without hunting for typos in raw JSON.
• Generator support — Feed consistent metadata to Nova generators so docs, README files, and release notes stay accurate.

Requirements

• Node.js runtime — Use any Node.js LTS release with either the installed nova CLI or npx.
• Project root — Run the command from the directory containing the top-level package.json (monorepo root included).
• Interactive terminal — The session needs to support interactive prompts for the wizard to function.

Usage

You can run this command in two ways:

nova (installed)

# Original
nova utility initialize

# Shorthand
nova util init

Note: If Nova is installed only locally (inside a project), the command will work only within that project's directory. See the npm docs for details.

npx (no install)

# Original
npx --yes @cbnventures/nova@latest utility initialize

# Shorthand
npx --yes @cbnventures/nova@latest util init

Note: If you prefer the shorter nova command, see the Setup and Configure guide for installation instructions.

Options

Flag	Description
-d, --dry-run	Preview the entire wizard without writing nova.config.json to disk.
-r, --replace-file	Overwrite the existing nova.config.json instead of creating a dated copy.

Flow Overview

The command loops until you choose Save & Exit or Cancel. You can edit any category multiple times during the same run.

Editing an existing config?

Existing values are pre-filled in each prompt. Press Enter to keep a value, type a new value to replace it, or enter a single space to clear that field.

Project

• Purpose: Edit project display name, slug, short/long descriptions, and keywords in one guided step.
• Nice to know: Slug updates propagate to workspace names for roles that depend on it (project, docs, config, app, tool) to keep names consistent.
• Things to watch: Slug allows only letters, numbers, hyphens, and underscores up to 214 characters; keywords are validated per item (50 characters max).

Entities

• Purpose: Manage project-related people and organizations with name, email, URL, and roles in a single flow.
• Nice to know: Roles are chosen from the allowed set (author, contributor, supporter) so you don't have to remember labels.
• Things to watch: Emails must be valid (contain @ and a domain); URLs must be valid http:// or https:// before they're saved.

Emails

• Purpose: Capture a canonical contact for issues/support so tools and metadata can reference a single address.
• Nice to know: Single email field today, kept simple for quick updates.
• Things to watch: Only valid addresses persist; blanks remove the stored email.

URLs

• Purpose: Configure canonical links with validation/normalization before persisting: homepage, repository, bugs, license, logo, docs, github, npm, and funding.
• Nice to know: Repository accepts git:, git+https:, git+ssh:, git+http: plus http://, https://; all other URLs are http://, https:// only.
• Things to watch: Funding sources are entered comma-separated and saved as a list after validation.

Workspaces

• Purpose: List detected workspaces (package.json) and edit each with role/policy in one place.
• Nice to know: Roles (project, config, docs, app, package, tool, template) and policies (freezable, trackable, distributable) are constrained to allowed combinations so you don't accidentally pick an invalid pairing.
• Things to watch: Naming rules enforced by role (config/app/tool require the project-slug prefix when set); distributable workspaces can opt into syncing selected metadata fields.

Saving and Canceling

• Choosing Save & Exit writes to a file called nova.config.json.
• Choosing Cancel exits immediately without persisting changes and prints a debug log.

Output Example

nova.config.json

{
  "project": {
    "name": {
      "slug": "example",
      "title": "Example"
    },
    "description": {
      "short": "Sample settings for a Nova-powered JavaScript toolkit.",
      "long": "Use Nova to keep linting, typing, and release metadata consistent across your JavaScript and TypeScript projects."
    },
    "keywords": [
      "example",
      "nova",
      "tooling",
      "config"
    ]
  },
  "entities": [
    {
      "name": "Example Author",
      "email": "author@example.com",
      "url": "https://example.com/author",
      "roles": [
        "author"
      ]
    },
    {
      "name": "Example Collaborator",
      "email": "collab@example.com",
      "url": "https://example.com/collaborator",
      "roles": [
        "contributor",
        "supporter"
      ]
    }
  ],
  "emails": {
    "bugs": "bugs@example.com"
  },
  "urls": {
    "homepage": "https://example.com",
    "repository": "https://github.com/example/example-project",
    "bugs": "https://github.com/example/example-project/issues",
    "license": "https://github.com/example/example-project/blob/main/LICENSE",
    "logo": "https://example.com/assets/logo.svg",
    "documentation": "https://docs.example.com/project",
    "github": "https://github.com/example/example-project",
    "npm": "https://www.npmjs.com/package/example-project",
    "fundSources": [
      "https://github.com/sponsors/example",
      "https://opencollective.com/example"
    ]
  },
  "workspaces": {
    "./": {
      "name": "example-project",
      "role": "project",
      "policy": "freezable",
      "recipes": {
        "cleanup": [
          true,
          {
            "removeUnknownKeys": true,
            "reorderKeys": true
          }
        ],
        "normalize-artifacts": [
          true
        ],
        "normalize-bundler": [
          true
        ],
        "normalize-dependencies": [
          true,
          {
            "pinDependencyVersions": true,
            "pinDevDependencyVersions": true
          }
        ],
        "normalize-modules": [
          true
        ],
        "normalize-tooling": [
          true
        ],
        "sync-environment": [
          true,
          {
            "trackNodeLtsVersions": true
          }
        ],
        "sync-identity": [
          true
        ],
        "sync-ownership": [
          true
        ]
      }
    },
    "./apps/docs": {
      "name": "example-docs",
      "role": "docs",
      "policy": "freezable",
      "recipes": {
        "cleanup": [
          true,
          {
            "removeUnknownKeys": true,
            "reorderKeys": true
          }
        ],
        "normalize-artifacts": [
          true
        ],
        "normalize-bundler": [
          true
        ],
        "normalize-dependencies": [
          true,
          {
            "pinDependencyVersions": true,
            "pinDevDependencyVersions": true
          }
        ],
        "normalize-modules": [
          true
        ],
        "normalize-tooling": [
          true
        ],
        "sync-environment": [
          true,
          {
            "trackNodeLtsVersions": true
          }
        ],
        "sync-identity": [
          true
        ],
        "sync-ownership": [
          true
        ]
      }
    },
    "./packages/nova": {
      "name": "@company/example",
      "role": "package",
      "policy": "distributable",
      "recipes": {
        "cleanup": [
          true,
          {
            "removeUnknownKeys": true,
            "reorderKeys": true
          }
        ],
        "normalize-artifacts": [
          true
        ],
        "normalize-bundler": [
          true
        ],
        "normalize-dependencies": [
          true,
          {
            "pinDependencyVersions": true,
            "pinDevDependencyVersions": true
          }
        ],
        "normalize-modules": [
          true
        ],
        "normalize-tooling": [
          true
        ],
        "sync-environment": [
          true,
          {
            "trackNodeLtsVersions": true
          }
        ],
        "sync-identity": [
          true,
          {
            "description": true,
            "keywords": true
          }
        ],
        "sync-ownership": [
          true,
          {
            "homepage": true,
            "bugs": true,
            "author": true,
            "contributors": true,
            "funding": true,
            "repository": true
          }
        ]
      }
    }
  }
}

Troubleshooting

• "Must be run inside the project root directory." — Verify you execute the command where the project root package.json resides. App or package folders inside monorepos are not allowed.
• Validation loops keep reappearing. — Fix the highlighted email or URL before continuing. To drop the value, enter a single space and press Enter.
• No file was created. — Confirm that nova.config.json is writable and that --dry-run was not passed or Cancel was not chosen.