Command-line interface#

Zyn is an agent-first application framework written in Zig.

Usage:
  zyn [command]

Commands:
  build       build the production app
  cache       manage the application value cache
  check       check formatting, artifacts, compilation, and tests
  context     show focused application context
  credentials manage encrypted credentials (alias: creds)
  db          manage application data and schema
  deploy      deploy the app
  dev         supervise HTTP, jobs, and PostgreSQL
  docs        show framework documentation
  generate    generate project files (alias: g)
  init        initialize or complete a zyn project
  jobs        run the worker or manage job queues
  notify      send a development notification
  pg          manage the local PostgreSQL server
  production  inspect the production host (alias: prod)
  routes      show the application routes
  serve       start the development HTTP server only
  test        run application tests only
  upgrade     install or check Zyn releases
  version     show the zyn version

Options:
  -h, --help     show this help
      --version  show the zyn version

Run zyn COMMAND --help for details.

Run zyn --help for the current command list and zyn version or zyn --version for the installed release. Project commands operate in a directory containing zyn.zon; zyn, its help and version forms, every zyn docs form, zyn upgrade, zyn init, and command -h/--help forms are also available outside a project. Help does not read project configuration, synchronize packages, compile, or start services.

Project commands keep the ignored .zyn/framework package in sync with the running Zyn release; zyn context and zyn production (alias zyn prod) do not refresh that package. Commands using the same release can run together. A different release waits until active commands finish before replacing the package. zyn credentials schema and zyn credentials get PATH -p PROFILE read credentials without synchronizing the framework package.

Workflows#

The terminal command list and documentation sidebar list commands alphabetically. Top-level help lists commands and options, then ends with Run zyn COMMAND --help for details. Run zyn COMMAND --help for usage, an example, and its documentation command. Known nested commands also accept help, for example zyn db migrate --help. On color-capable terminals, command help dims section headings, renders zyn in cyan on each usage line, and renders command and option labels in green. Descriptions, arguments, and examples remain uncolored. Redirected output and output with NO_COLOR contain no terminal escape codes. A nearby, unambiguous misspelling of a top-level command, database command, PostgreSQL command, production command, or generator produces a suggestion without executing it. Invalid build, check, test, deployment, and development options point to command help and suggest a nearby option where unambiguous.

Common process settings are:

• PORT selects the non-zero development listener port.
• ZYN_ENV selects a named credential and database profile for direct servers; project commands select their documented profile explicitly.
• NO_COLOR disables terminal color in command and development-log output.
• CLICOLOR_FORCE enables color when supported even when output is redirected; NO_COLOR takes precedence.
• VISUAL, then EDITOR, selects the credentials profile editor.

Output and failures#

Requested help, version output, and command results use stdout. Error diagnostics, including usage printed for rejected arguments, use stderr. Human progress output may accompany results. Exit status is 64 for invalid command syntax and 1 for command failures. zyn upgrade uses status 2 for invalid syntax. A production status report remains a result, even when its health classification causes a nonzero exit status.

Inside a project, command syntax is validated before framework synchronization or service startup. Credential profile and field names and development PORT values are also checked before framework synchronization.

On POSIX, SIGINT or SIGTERM delivered to a finite command cancels its work and runs cleanup before exiting with status 128 plus the signal number. Commands stop PostgreSQL only when their startup operation acquired ownership; a reused server remains running. Child launcher cleanup targets command-owned process groups, not the caller's terminal group. Development supervision retains its graceful shutdown behavior.

Automation#

zyn routes --json, zyn jobs status --json, zyn production status --json, and zyn production jobs status --json, and zyn production db status --json emit one JSON object followed by a newline. Each object includes integer schema_version: 1 and its canonical command name, including when invoked through prod. Human output remains the default. JSON is not colored, including with CLICOLOR_FORCE. Diagnostics and local PostgreSQL lifecycle messages go to stderr. Syntax, setup, and remote protocol failures exit nonzero without a status document; production status still emits its document when the inspected deployment is degraded or unknown. Consumers should check the exit status and schema version, and allow additional object fields within a schema version. Field meanings and types do not change within version 1; object key order is not a contract.

--no-input disables prompts for deploy, credentials (creds), dev, init, serve, notify, and production (prod). It does not imply consent. If a required choice is absent, the command fails with a remedy instead of reading a terminal, opening an editor, or approving local TLS trust. Existing configuration, explicit values, and piped credential data remain usable. Credential profile operations require --profile PROFILE or -p PROFILE; get, set, and unset require a path immediately after the operation. After set PATH, supported flag spellings are options, while other flag-looking tokens are literal values. --no-input does not disable deliberate stdin data reads or make an application, database console, or application build hook non-interactive.