zynagent-first application framework

Initialize command#

Usage:
  zyn init [--name NAME] [--no-input]

Options:
      --name NAME   application name (letters, digits, _ and -)
      --no-input    fail rather than prompt

Initialize or complete a project in the current directory, preserving existing application files.

Example:
  zyn init --name weave-wonders

Documentation: zyn docs cli/init

zyn init initializes the current directory; it never creates a project directory. On a new project, supply --name NAME or enter a name at the terminal prompt. The suggested name combines a verb and a noun and appears as an editable dim placeholder: typing replaces it, and Enter accepts it. The prompt uses color on color-capable terminals; NO_COLOR disables color without disabling input. If input is not interactive, or --no-input is passed, a missing name fails without changing files. zyn init --help prints usage without creating files.

For interactive text entry, Backspace removes one character, and Escape followed by Backspace (commonly Option/Alt+Backspace) or Ctrl-W removes the previous whitespace-delimited word. A valid application name contains no spaces, so deleting its preceding word clears the typed name and reveals the suggestion again. Ctrl-U removes input to the cursor's left; arrow keys move the cursor within typed input.

Names contain 1–64 ASCII letters, digits, underscores, or hyphens and cannot start with a hyphen. The name is recorded verbatim in zyn.zon and used in the starter page; it does not change database names or the Zig package identity. Existing projects retain their configured name and application files on rerun, without prompting. Initialization reports the configured name when resuming, escaping control bytes before terminal output. A conflicting explicit name fails. New projects do not record a template choice.

Initializes or completes a zyn project in the current directory. It creates missing application, build, route, view, database, configuration, credential, log, and contributor-guidance files. Existing build files and customized application files are preserved.

The scaffold contains a root page and health route. Add authentication to an application with zyn docs recipes/add-session-authentication.

A newly initialized project prints zyn dev and the authentication recipe as next steps; rerunning zyn init does not print the starter guidance.

A fresh project includes and packages src/assets/application.css, then links the stylesheet from its application layout with the compile-checked template asset('application.css') helper. Rerunning initialization never replaces an existing stylesheet or layout.

Initialization also downloads or reuses the configured PostgreSQL bundle and ensures the development database exists. PostgreSQL versions must be semantic; PostgreSQL 18 or newer is required.

Generated security-sensitive files follow these defaults:

  • credentials/development.key is ignored.
  • credentials/test.key is tracked so tests are reproducible.
  • The encrypted development and test profiles use independent keys.
  • Each profile receives an encrypted PROFILE.data-keys.zon.enc file containing an independent database data key.

The generated zyn.zon configures the application name, common PostgreSQL defaults, explicit development, testing, and production database profiles, and HTTP limits. The profiles select databases development, test, and production; all initially use host 127.0.0.1, port 7542, and the restricted zyn application role. Managed local development and testing authenticate without an application credential; deployment uses the production profile's configured authentication mode.

ZYN.md contains framework guidance and a common-change recipe index for coding agents. The application-owned AGENTS.md links to it without replacing customized guidance, and rerunning zyn init refreshes ZYN.md as the framework evolves.

A fresh build.zig.zon receives a Zig-compatible package fingerprint with a random identity component. Resumed initialization preserves that package identity with the existing manifest.

Rerunning initialization adds missing scaffold files and retains the existing package identity and user-owned files. When adding configuration defaults, it preserves explicitly configured email transports and capture paths.

Outside an existing Git worktree, initialization commits the complete tracked scaffold and leaves the new repository clean. Zig's .zig-cache/ and zyn's .zyn/ implementation state remain ignored.