init

arkenv on npm is the CLI. It scaffolds schemas and wires framework config. Validation lives in @arkenv/core or @arkenv/standard. For the walkthrough, see Installation.

npx arkenv init

pnpm dlx arkenv init

yarn dlx arkenv init

bunx arkenv init

Usage

arkenv init [project-name] [options]

Omit project-name to mutate the current directory. Pass a name to create a new folder (optionally from --example).

Global flags (--yes, --quiet, --json, --agent, --help) apply here too.

Options

These flags are specific to init.

--force / -f

Bypass dirty-git and other safety checks, then force scaffolding. The CLI refuses a dirty working tree so a run cannot silently overwrite uncommitted work. Commit or stash first, or pass --force when you accept that risk (for example in CI).

--no-codegen

Skip Next.js env.gen.ts generation and related withArkEnv wiring.

--preset / -P

Pre-populate provider system variables. Values: none, vercel, netlify, cloudflare, railway, render, fly. The CLI also accepts --host-preset and -H as aliases.

See Hosting presets.

--agent

Same macro as the global --agent flag: --yes --quiet --json. It does not imply --force.

When a safety check fails (dirty git tree), stdout is an errored settlement envelope (ok: false) and the process exits non-zero:

{
  "ok": false,
  "commandId": "init",
  "error": {
    "code": "CLI.GIT_TREE_DIRTY",
    "severity": "error",
    "summary": "Git working tree is not clean.",
    "why": "Commit or stash your changes before running arkenv init.",
    "nextActions": [
      {
        "kind": "run-command",
        "label": "Re-run with --force to bypass git working tree check",
        "command": "arkenv init --force"
      }
    ]
  },
  "diagnostics": [],
  "nextActions": [
    {
      "kind": "run-command",
      "label": "Re-run with --force to bypass git working tree check",
      "command": "arkenv init --force"
    }
  ]
}

Branch on error.code (dotted CLI.* / ENV.* codes). Use nextActions for remediation — a run-command action with --force means the refusal is bypassable. Only re-run with that flag after you confirm the bypass is safe. The same envelope shape is documented for check --json.

--example <name>

Scaffold from a named example when creating a new project. Short -e is reserved and rejected.

See Start with an example.

Output

Depending on the detected framework and flags, init writes:

• Schema file: env.ts (often under src/)
• .env / .env.example when missing. Init never reads an existing .env; a missing .env.example is scaffolded from detected keys and defaults. If .env is missing, init may copy .env.example into it.
• Next.js: withArkEnv in next.config.*, .arkenv/ in .gitignore, optional .arkenv/env.gen.ts (import as @/.arkenv)
• Vite / Bun / Rsbuild: plugin configuration in vite.config.* / bunfig.toml / rsbuild.config.*
• Dependency installs for the chosen dialect (@arkenv/core, plugins, Zod/Valibot)

Import the validator from core

The CLI package is not the validation library. Import arkenv() from @arkenv/core (or @arkenv/standard).

// Wrong: arkenv is the CLI package
import arkenv from "arkenv";

// Right
import arkenv from "@arkenv/core";

Importing arkenv as a library throws and points you at @arkenv/core.

Next steps